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

claude_mpm/core/hook_manager.py

@@ -23,6 +23,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from ..core.logger import get_logger
+from .hook_error_memory import get_hook_error_memory
 from .hook_performance_config import get_hook_performance_config
 from .unified_paths import get_package_root
 
@@ -42,6 +43,9 @@ class HookManager:
         self.session_id = self._get_or_create_session_id()
         self.hook_handler_path = self._find_hook_handler()
 
+        # Initialize error memory for tracking and preventing repeated errors
+        self.error_memory = get_hook_error_memory()
+
         # Initialize background hook processing for async execution
         self.performance_config = get_hook_performance_config()
         queue_config = self.performance_config.get_queue_config()
@@ -97,11 +101,31 @@ class HookManager:
         self.logger.debug("Started background hook processor thread")
 
     def _execute_hook_sync(self, hook_data: Dict[str, Any]):
-        """Execute a single hook synchronously in the background thread."""
+        """Execute a single hook synchronously in the background thread with error detection.
+
+        WHY error detection:
+        - Prevents repeated execution of failing hooks
+        - Provides actionable error messages to users
+        - Learns from failures to improve system reliability
+        - Reduces log noise from repeated errors
+        """
         try:
             hook_type = hook_data["hook_type"]
             event_data = hook_data["event_data"]
 
+            # Check if this hook is known to fail repeatedly
+            if self.error_memory.should_skip_hook(hook_type):
+                known_error = self.error_memory.is_known_failing_hook(hook_type)
+                if known_error:
+                    # Log warning but don't spam - only on first skip
+                    if known_error["count"] == 2:  # First time we're skipping
+                        self.logger.warning(
+                            f"⚠️  Skipping {hook_type} hook - failed {known_error['count']} times previously\n"
+                            f"Error: {known_error['match']}\n"
+                            f"To retry: rm {self.error_memory.memory_file}"
+                        )
+                return
+
             # Create the hook event
             hook_event = {
                 "hook_event_name": hook_type,
@@ -127,7 +151,22 @@ class HookManager:
                 check=False,
             )
 
-            if result.returncode != 0:
+            # Detect errors in the output
+            error_info = self.error_memory.detect_error(
+                result.stdout or "", result.stderr or "", result.returncode
+            )
+
+            if error_info:
+                # Record the error
+                self.error_memory.record_error(error_info, hook_type)
+
+                # Get fix suggestion
+                suggestion = self.error_memory.suggest_fix(error_info)
+
+                # Log error with suggestion
+                self.logger.warning(f"Hook {hook_type} error detected:\n{suggestion}")
+            elif result.returncode != 0:
+                # Non-zero return without detected pattern
                 self.logger.debug(f"Hook {hook_type} returned code {result.returncode}")
                 if result.stderr:
                     self.logger.debug(f"Hook stderr: {result.stderr}")

claude_mpm/core/interactive_session.py

@@ -2,6 +2,12 @@
 
 This module provides the InteractiveSession class that manages Claude's interactive mode
 with proper separation of concerns and reduced complexity.
+
+DEPENDENCY INJECTION:
+This module uses protocol-based dependency injection to break circular imports.
+Instead of importing ClaudeRunner directly, it uses ClaudeRunnerProtocol which
+defines the interface it needs. This allows ClaudeRunner to create instances
+of InteractiveSession without circular dependency issues.
 """
 
 import contextlib
@@ -9,11 +15,18 @@ import os
 import subprocess
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 from claude_mpm.core.enums import ServiceState
 from claude_mpm.core.logger import get_logger
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class InteractiveSession:
     """
@@ -28,13 +41,14 @@ class InteractiveSession:
     and makes testing easier while preserving all original functionality.
     """
 
-    def __init__(self, runner):
+    def __init__(self, runner: "ClaudeRunnerProtocol"):
         """Initialize interactive session handler.
 
         Args:
-            runner: ClaudeRunner instance with all necessary services
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
+                    with all necessary services
         """
-        self.runner = runner
+        self.runner: ClaudeRunnerProtocol = runner
         self.logger = get_logger("interactive_session")
         self.session_id = None
         self.original_cwd = Path.cwd()
@@ -85,8 +99,8 @@ class InteractiveSession:
                     self.logger.warning(f"WebSocket initialization failed: {error}")
                     # Continue without WebSocket - not a fatal error
 
-            # Display welcome message
-            self._display_welcome_message()
+            # Banner now displayed in CLI startup - see startup_display.py
+            # Removed duplicate _display_welcome_message() to consolidate with main banner
 
             # Log session start
             if self.runner.project_logger:
@@ -293,7 +307,12 @@ class InteractiveSession:
             return False, f"Unexpected error with Socket.IO: {e}"
 
     def _display_welcome_message(self) -> None:
-        """Display the interactive session welcome message."""
+        """Display the interactive session welcome message.
+
+        DEPRECATED: This method is kept for backward compatibility with tests.
+        The main banner is now displayed in startup_display.py during CLI startup.
+        This consolidated approach prevents duplicate banners.
+        """
         version_str = self.runner._get_version()
 
         # Get output style status
@@ -391,12 +410,74 @@ class InteractiveSession:
                 cmd.extend(agents_flag)
                 self.logger.info("✓ Native agents mode: Using --agents CLI flag")
 
-        # Add system instructions
-        from claude_mpm.core.claude_runner import create_simple_context
+        # Add system instructions with file-based caching
+        from claude_mpm.core.system_context import create_simple_context
+        from claude_mpm.services.instructions.instruction_cache_service import (
+            InstructionCacheService,
+        )
 
         system_prompt = self.runner._create_system_prompt()
         if system_prompt and system_prompt != create_simple_context():
-            cmd.extend(["--append-system-prompt", system_prompt])
+            # Try to use cached instruction file for better performance
+            try:
+                # Initialize cache service with project root
+                if "CLAUDE_MPM_USER_PWD" in os.environ:
+                    project_root = Path(os.environ["CLAUDE_MPM_USER_PWD"])
+                else:
+                    project_root = Path.cwd()
+
+                # Instruction Caching (1M-446)
+                # Cache assembled instructions to file to avoid ARG_MAX limits on Linux/Windows.
+                # - Linux: 128 KB limit, instructions are ~152 KB (exceeds by 19.1%)
+                # - Windows: 32 KB limit (exceeds by 476%)
+                # Cache updates only when content hash changes (hash-based invalidation).
+                # Fallback to inline instruction if cache fails (graceful degradation).
+                cache_service = InstructionCacheService(project_root=project_root)
+
+                # Update cache with assembled instruction content
+                cache_result = cache_service.update_cache(
+                    instruction_content=system_prompt
+                )
+
+                # Use cache file if available
+                if (
+                    cache_result.get("updated")
+                    or cache_service.get_cache_path().exists()
+                ):
+                    cache_file = cache_service.get_cache_path()
+
+                    # Log cache operation
+                    if cache_result.get("updated"):
+                        self.logger.info(
+                            f"Instruction cache updated: {cache_result.get('reason', 'unknown')}"
+                        )
+                        self.logger.debug(
+                            f"Cache hash: {cache_result.get('content_hash', 'N/A')[:8]}..."
+                        )
+                        self.logger.debug(
+                            f"Cache size: {cache_result.get('content_size_kb', 'N/A')} KB"
+                        )
+                    else:
+                        self.logger.debug(
+                            f"Using cached instructions: {cache_result.get('reason', 'unknown')}"
+                        )
+
+                    # Use file-based loading for better performance
+                    cmd.extend(["--system-prompt-file", str(cache_file)])
+                    self.logger.info(
+                        f"✓ Using file-based instruction loading: {cache_file}"
+                    )
+                else:
+                    # Fallback to inline if cache file doesn't exist
+                    self.logger.warning(
+                        "Cache file not available, falling back to inline instruction"
+                    )
+                    cmd.extend(["--append-system-prompt", system_prompt])
+
+            except Exception as e:
+                # Graceful fallback - cache failures don't break deployment
+                self.logger.warning(f"Failed to cache instructions, using inline: {e}")
+                cmd.extend(["--append-system-prompt", system_prompt])
 
         # Final command verification
         # self.logger.info(f"Final Claude command built: {' '.join(cmd)}")

claude_mpm/core/logger.py

@@ -225,7 +225,9 @@ def setup_logging(
 
             # Use rotating file handler
             file_handler = logging.handlers.RotatingFileHandler(
-                log_file, maxBytes=10 * 1024 * 1024, backupCount=5  # 10 MB
+                log_file,
+                maxBytes=10 * 1024 * 1024,
+                backupCount=5,  # 10 MB
             )
         else:
             # Use default log directory

claude_mpm/core/oneshot_session.py

@@ -2,19 +2,32 @@
 
 This module encapsulates the logic for running one-time Claude commands,
 breaking down the monolithic run_oneshot method into focused, testable components.
+
+DEPENDENCY INJECTION:
+This module uses protocol-based dependency injection to break circular imports.
+Instead of importing ClaudeRunner directly, it uses ClaudeRunnerProtocol which
+defines the interface it needs.
 """
 
 import contextlib
 import os
 import subprocess
+import tempfile
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 from claude_mpm.core.enums import OperationResult, ServiceState
 from claude_mpm.core.logger import get_logger
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class OneshotSession:
     """Manages a single oneshot Claude execution session.
@@ -26,17 +39,18 @@ class OneshotSession:
     complexity < 10 and lines < 80, making the code easier to test and modify.
     """
 
-    def __init__(self, runner):
+    def __init__(self, runner: "ClaudeRunnerProtocol"):
         """Initialize the oneshot session with a reference to the runner.
 
         Args:
-            runner: The ClaudeRunner instance that owns this session
+            runner: The ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
         """
-        self.runner = runner
+        self.runner: ClaudeRunnerProtocol = runner
         self.logger = get_logger("oneshot_session")
         self.start_time = None
         self.session_id = None
         self.original_cwd = None
+        self.temp_system_prompt_file = None
 
     def initialize_session(self, prompt: str) -> Tuple[bool, Optional[str]]:
         """Initialize the oneshot session.
@@ -134,7 +148,13 @@ class OneshotSession:
     def _build_final_command(
         self, prompt: str, context: Optional[str], infrastructure: Dict[str, Any]
     ) -> list:
-        """Build the final command with prompt and system instructions."""
+        """Build the final command with prompt and system instructions.
+
+        Uses file-based caching to avoid Linux ARG_MAX limits:
+        - Linux MAX_ARG_STRLEN: 128 KB per argument
+        - System prompt size: ~138.7 KB (exceeds limit by 7.7 KB)
+        - Solution: Write to temp file, pass file path (~60 bytes)
+        """
         full_prompt = f"{context}\n\n{prompt}" if context else prompt
         cmd = infrastructure["cmd"] + ["--print", full_prompt]
 
@@ -148,9 +168,38 @@ class OneshotSession:
                 self.logger.warning("System prompt contains Python code references!")
 
         if system_prompt and system_prompt != self._get_simple_context():
-            # The problem might be with insert positioning
-            # Let's add system prompt differently
-            cmd.extend(["--append-system-prompt", system_prompt])
+            # Use file-based loading to avoid ARG_MAX limits (1M-485)
+            # Create temp file for system prompt
+            try:
+                # Create temp file in system temp directory
+                temp_fd, temp_path = tempfile.mkstemp(
+                    suffix=".md", prefix="claude_mpm_system_prompt_"
+                )
+
+                # Write system prompt to temp file
+                with os.fdopen(temp_fd, "w", encoding="utf-8") as f:
+                    f.write(system_prompt)
+
+                # Store temp file path for cleanup
+                self.temp_system_prompt_file = temp_path
+
+                # Use --system-prompt-file flag (matches interactive mode pattern)
+                cmd.extend(["--system-prompt-file", temp_path])
+
+                # User-visible notification
+                print(f"📄 Reading system prompt from: {temp_path}")
+
+                self.logger.info(
+                    f"Using file-based system prompt loading: {temp_path} "
+                    f"({len(system_prompt) / 1024:.1f} KB)"
+                )
+
+            except Exception as e:
+                # Fallback to inline if file creation fails
+                self.logger.warning(
+                    f"Failed to create temp file for system prompt, using inline: {e}"
+                )
+                cmd.extend(["--append-system-prompt", system_prompt])
 
         return cmd
 
@@ -203,6 +252,20 @@ class OneshotSession:
 
     def cleanup_session(self) -> None:
         """Clean up the session and restore state."""
+        # Clean up temp system prompt file
+        if self.temp_system_prompt_file:
+            try:
+                temp_file_path = Path(self.temp_system_prompt_file)
+                if temp_file_path.exists():
+                    temp_file_path.unlink()
+                    self.logger.debug(
+                        f"Cleaned up temp system prompt file: {self.temp_system_prompt_file}"
+                    )
+            except Exception as e:
+                self.logger.warning(f"Failed to clean up temp system prompt file: {e}")
+            finally:
+                self.temp_system_prompt_file = None
+
         # Restore original working directory
         if self.original_cwd:
             with contextlib.suppress(Exception):

claude_mpm/core/protocols/__init__.py

@@ -0,0 +1,23 @@
+"""Protocol interfaces for dependency injection.
+
+This module defines Protocol interfaces to break circular dependencies
+using Python's typing.Protocol feature for structural subtyping.
+"""
+
+from claude_mpm.core.protocols.runner_protocol import (
+    ClaudeRunnerProtocol,
+    SystemPromptProvider,
+)
+from claude_mpm.core.protocols.session_protocol import (
+    InteractiveSessionProtocol,
+    OneshotSessionProtocol,
+    SessionManagementProtocol,
+)
+
+__all__ = [
+    "ClaudeRunnerProtocol",
+    "InteractiveSessionProtocol",
+    "OneshotSessionProtocol",
+    "SessionManagementProtocol",
+    "SystemPromptProvider",
+]

claude_mpm/core/protocols/runner_protocol.py

@@ -0,0 +1,103 @@
+"""Protocol definitions for ClaudeRunner dependencies.
+
+These protocols use Python's typing.Protocol for structural subtyping,
+allowing dependency injection without circular imports.
+"""
+
+from pathlib import Path
+from typing import Any, Optional, Protocol
+
+
+class SystemPromptProvider(Protocol):
+    """Protocol for providing system prompts without circular dependency.
+
+    This protocol allows InteractiveSession to get system prompts without
+    directly importing ClaudeRunner, breaking the circular dependency.
+    """
+
+    def _create_system_prompt(self) -> str:
+        """Create the complete system prompt including instructions.
+
+        Returns:
+            Complete system prompt as string
+        """
+        ...
+
+
+class ClaudeRunnerProtocol(Protocol):
+    """Protocol defining the interface InteractiveSession needs from ClaudeRunner.
+
+    This protocol breaks the circular dependency between InteractiveSession
+    and ClaudeRunner by defining only the methods that InteractiveSession
+    actually uses, without requiring the full ClaudeRunner import.
+
+    Design Decision: Uses Protocol instead of ABC to allow structural subtyping.
+    This means ClaudeRunner doesn't need to explicitly inherit from this protocol,
+    it just needs to implement these methods with matching signatures.
+    """
+
+    # Configuration attributes
+    enable_websocket: bool
+    enable_tickets: bool
+    log_level: str
+    claude_args: Optional[list]
+    launch_method: str
+    websocket_port: int
+    use_native_agents: bool
+    config: Any
+    session_log_file: Optional[Path]
+
+    # Service references
+    project_logger: Any
+    websocket_server: Any
+    command_handler_service: Any
+    subprocess_launcher_service: Any
+
+    def setup_agents(self) -> bool:
+        """Deploy native agents to .claude/agents/.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def deploy_project_agents_to_claude(self) -> bool:
+        """Deploy project agents from .claude-mpm/agents/ to .claude/agents/.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def _create_system_prompt(self) -> str:
+        """Create the complete system prompt including instructions.
+
+        Returns:
+            Complete system prompt as string
+        """
+        ...
+
+    def _get_version(self) -> str:
+        """Get version string.
+
+        Returns:
+            Version string
+        """
+        ...
+
+    def _log_session_event(self, event_data: dict) -> None:
+        """Log an event to the session log file.
+
+        Args:
+            event_data: Event data to log
+        """
+        ...
+
+    def _launch_subprocess_interactive(self, cmd: list, env: dict) -> None:
+        """Launch Claude as a subprocess with PTY for interactive mode.
+
+        Args:
+            cmd: Command to execute
+            env: Environment variables
+        """
+        ...

claude_mpm/core/protocols/session_protocol.py

@@ -0,0 +1,131 @@
+"""Protocol definitions for session management dependencies.
+
+These protocols use Python's typing.Protocol for structural subtyping,
+allowing dependency injection without circular imports.
+"""
+
+from typing import Any, Dict, Optional, Protocol, Tuple
+
+
+class InteractiveSessionProtocol(Protocol):
+    """Protocol for interactive session orchestration.
+
+    This protocol defines the interface that SessionManagementService
+    needs from InteractiveSession without requiring a full import.
+    """
+
+    def initialize_interactive_session(self) -> Tuple[bool, Optional[str]]:
+        """Initialize the interactive session environment.
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        ...
+
+    def setup_interactive_environment(self) -> Tuple[bool, Dict[str, Any]]:
+        """Set up the interactive environment including agents and commands.
+
+        Returns:
+            Tuple of (success, environment_dict)
+        """
+        ...
+
+    def handle_interactive_input(self, environment: Dict[str, Any]) -> bool:
+        """Handle the interactive input/output loop.
+
+        Args:
+            environment: Dictionary with command, env vars, and session info
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def cleanup_interactive_session(self) -> None:
+        """Clean up resources after interactive session ends."""
+        ...
+
+
+class OneshotSessionProtocol(Protocol):
+    """Protocol for oneshot session orchestration.
+
+    This protocol defines the interface that SessionManagementService
+    needs from OneshotSession without requiring a full import.
+    """
+
+    def initialize_session(self, prompt: str) -> Tuple[bool, Optional[str]]:
+        """Initialize the oneshot session.
+
+        Args:
+            prompt: The command or prompt to execute
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        ...
+
+    def deploy_agents(self) -> bool:
+        """Deploy agents for the session.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def setup_infrastructure(self) -> Dict[str, Any]:
+        """Set up session infrastructure.
+
+        Returns:
+            Dictionary with infrastructure configuration
+        """
+        ...
+
+    def execute_command(
+        self, prompt: str, context: Optional[str], infrastructure: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """Execute the command with given context and infrastructure.
+
+        Args:
+            prompt: Command to execute
+            context: Optional context
+            infrastructure: Infrastructure configuration
+
+        Returns:
+            Tuple of (success, response)
+        """
+        ...
+
+    def cleanup_session(self) -> None:
+        """Clean up session resources."""
+        ...
+
+
+class SessionManagementProtocol(Protocol):
+    """Protocol for session management service.
+
+    This protocol defines the interface that ClaudeRunner needs from
+    SessionManagementService without requiring a full import.
+    """
+
+    def run_interactive_session(self, initial_context: Optional[str] = None) -> bool:
+        """Run Claude in interactive mode.
+
+        Args:
+            initial_context: Optional initial context to pass to Claude
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def run_oneshot_session(self, prompt: str, context: Optional[str] = None) -> bool:
+        """Run Claude with a single prompt.
+
+        Args:
+            prompt: The command or prompt to execute
+            context: Optional context to prepend to the prompt
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...

claude_mpm/core/shared/singleton_manager.py

@@ -16,11 +16,14 @@ class SingletonManager:
 
     Reduces duplication by providing thread-safe singleton patterns
     that can be used across different classes.
+
+    Uses RLock (reentrant locks) to support recursive calls from
+    SingletonMixin.__new__ and @singleton decorator patterns.
     """
 
     _instances: Dict[Type, Any] = {}
-    _locks: Dict[Type, threading.Lock] = {}
-    _global_lock = threading.Lock()
+    _locks: Dict[Type, threading.RLock] = {}
+    _global_lock = threading.RLock()
 
     @classmethod
     def get_instance(
@@ -42,7 +45,7 @@ class SingletonManager:
         if singleton_class not in cls._locks:
             with cls._global_lock:
                 if singleton_class not in cls._locks:
-                    cls._locks[singleton_class] = threading.Lock()
+                    cls._locks[singleton_class] = threading.RLock()
 
         # Get instance with class-specific lock
         with cls._locks[singleton_class]:
@@ -50,9 +53,13 @@ class SingletonManager:
                 logger = get_logger("singleton_manager")
                 logger.debug(f"Creating singleton instance: {singleton_class.__name__}")
 
-                instance = singleton_class(*args, **kwargs)
+                # Use object.__new__ to bypass SingletonMixin.__new__ and avoid recursion
+                instance = object.__new__(singleton_class)
                 cls._instances[singleton_class] = instance
 
+                # Now call __init__ explicitly with the stored instance
+                instance.__init__(*args, **kwargs)
+
                 return instance
 
             return cls._instances[singleton_class]