claude-mpm 4.16.0__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/core/hook_error_memory.py

@@ -0,0 +1,381 @@
+"""Hook Error Memory System.
+
+This module provides error detection and memory for hook execution to prevent
+repeated errors and provide helpful diagnostics.
+
+WHY this is needed:
+- Hook processor can encounter transient or persistent errors
+- Repeated failing commands waste resources and clutter logs
+- Users need actionable suggestions to fix configuration issues
+- System should learn from errors and prevent repetition
+
+DESIGN DECISION: Store errors in JSON file rather than database because:
+- Simple, human-readable format
+- Easy to inspect and manually clear
+- No additional dependencies
+- Fast read/write for small datasets
+- Users can easily delete to retry failed commands
+"""
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..core.logger import get_logger
+
+
+class HookErrorMemory:
+    """Tracks and prevents repeated hook execution errors.
+
+    WHY this design:
+    - Detects common error patterns automatically
+    - Stores error history to prevent repetition
+    - Provides actionable fix suggestions
+    - Allows manual retry by clearing memory
+    - Minimal performance overhead (<1ms per check)
+    """
+
+    # Error pattern definitions with detection regexes
+    ERROR_PATTERNS = [
+        (r"no such file or directory[:\s]+(.+?)(?:\n|$)", "file_not_found"),
+        (r"command not found[:\s]+(.+?)(?:\n|$)", "command_not_found"),
+        (r"permission denied[:\s]+(.+?)(?:\n|$)", "permission_denied"),
+        (r"syntax error", "syntax_error"),
+        (r"Error:\s*\(eval\):(\d+):\s*(.+?)(?:\n|$)", "eval_error"),
+        (r"Error:\s*(.+?)(?:\n|$)", "general_error"),
+    ]
+
+    def __init__(self, memory_file: Optional[Path] = None):
+        """Initialize hook error memory.
+
+        Args:
+            memory_file: Path to memory file (default: .claude-mpm/hook_errors.json)
+        """
+        self.logger = get_logger("hook_error_memory")
+
+        # Use default location if not specified
+        if memory_file is None:
+            memory_file = Path.cwd() / ".claude-mpm" / "hook_errors.json"
+
+        self.memory_file = memory_file
+        self.errors: Dict[str, Any] = self._load_errors()
+
+    def _load_errors(self) -> Dict[str, Any]:
+        """Load previously encountered errors from disk.
+
+        Returns:
+            Dictionary of error records
+        """
+        if not self.memory_file.exists():
+            return {}
+
+        try:
+            content = self.memory_file.read_text()
+            if not content.strip():
+                return {}
+            return json.loads(content)
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Failed to parse error memory file: {e}")
+            return {}
+        except Exception as e:
+            self.logger.error(f"Error loading error memory: {e}")
+            return {}
+
+    def _save_errors(self):
+        """Persist errors to disk."""
+        try:
+            # Ensure directory exists
+            self.memory_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write with pretty formatting for human readability
+            self.memory_file.write_text(json.dumps(self.errors, indent=2))
+        except Exception as e:
+            self.logger.error(f"Failed to save error memory: {e}")
+
+    def detect_error(
+        self, output: str, stderr: str, returncode: int
+    ) -> Optional[Dict[str, str]]:
+        """Detect if output contains an error.
+
+        WHY check both stdout and stderr:
+        - Some commands write errors to stdout
+        - Some write to stderr
+        - Return code alone isn't enough (some hooks return non-zero on purpose)
+
+        Args:
+            output: Standard output from command
+            stderr: Standard error from command
+            returncode: Exit code from command
+
+        Returns:
+            Dict with error info if detected, None otherwise
+        """
+        # Combine output sources for comprehensive error detection
+        combined_output = f"{output}\n{stderr}"
+
+        # Try each pattern in order of specificity
+        for pattern, error_type in self.ERROR_PATTERNS:
+            match = re.search(pattern, combined_output, re.IGNORECASE | re.MULTILINE)
+            if match:
+                # Extract details from the match
+                details = match.group(1) if match.groups() else match.group(0)
+
+                return {
+                    "type": error_type,
+                    "pattern": pattern,
+                    "match": match.group(0).strip(),
+                    "details": details.strip() if details else "",
+                    "returncode": returncode,
+                }
+
+        # If no pattern matched but returncode is non-zero, record as generic error
+        if returncode != 0 and combined_output.strip():
+            return {
+                "type": "unknown_error",
+                "pattern": "non-zero exit code",
+                "match": f"Exit code: {returncode}",
+                "details": combined_output[:200].strip(),  # First 200 chars
+                "returncode": returncode,
+            }
+
+        return None
+
+    def record_error(self, error_info: Dict[str, str], hook_type: str):
+        """Record an error to prevent future repetition.
+
+        WHY use composite key:
+        - Same error type can occur with different details
+        - Want to track specific error instances
+        - Hook type context helps with diagnosis
+
+        Args:
+            error_info: Error information from detect_error()
+            hook_type: Type of hook that failed (e.g., "PreToolUse")
+        """
+        # Create unique key for this error
+        key = f"{error_info['type']}:{hook_type}:{error_info['details']}"
+
+        now = datetime.now(timezone.utc).isoformat()
+
+        if key in self.errors:
+            # Update existing error
+            self.errors[key]["count"] += 1
+            self.errors[key]["last_seen"] = now
+        else:
+            # Record new error
+            self.errors[key] = {
+                "type": error_info["type"],
+                "hook_type": hook_type,
+                "details": error_info["details"],
+                "match": error_info["match"],
+                "returncode": error_info.get("returncode", 1),
+                "count": 1,
+                "first_seen": now,
+                "last_seen": now,
+            }
+
+        self._save_errors()
+        self.logger.debug(
+            f"Recorded error: {error_info['type']} (count: {self.errors[key]['count']})"
+        )
+
+    def is_known_failing_hook(self, hook_type: str) -> Optional[Dict[str, Any]]:
+        """Check if a hook type is known to fail repeatedly.
+
+        WHY check for 2+ failures:
+        - Single failure could be transient
+        - 2+ failures indicate persistent issue
+        - Balance between retry attempts and error prevention
+
+        Args:
+            hook_type: Type of hook to check
+
+        Returns:
+            Error data if hook is known to fail, None otherwise
+        """
+        # Find any errors for this hook type with 2+ occurrences
+        for key, error_data in self.errors.items():
+            if error_data["hook_type"] == hook_type and error_data["count"] >= 2:
+                return error_data
+
+        return None
+
+    def should_skip_hook(self, hook_type: str, threshold: int = 2) -> bool:
+        """Determine if a hook should be skipped due to repeated failures.
+
+        Args:
+            hook_type: Type of hook to check
+            threshold: Minimum failure count to skip (default: 2)
+
+        Returns:
+            True if hook should be skipped
+        """
+        error_data = self.is_known_failing_hook(hook_type)
+        return error_data is not None and error_data["count"] >= threshold
+
+    def suggest_fix(self, error_info: Dict[str, str]) -> str:
+        """Suggest a fix for the detected error.
+
+        WHY provide suggestions:
+        - Users need actionable guidance
+        - Common errors have known solutions
+        - Reduces support burden
+        - Improves user experience
+
+        Args:
+            error_info: Error information from detect_error()
+
+        Returns:
+            Human-readable fix suggestion
+        """
+        error_type = error_info["type"]
+        details = error_info.get("details", "")
+
+        suggestions = {
+            "file_not_found": f"""File not found: {details}
+
+Possible fixes:
+1. Check if the file exists: ls -la {details}
+2. Verify the path is correct in your hook configuration
+3. If it's a script, ensure it's executable: chmod +x {details}
+4. Clear error memory to retry: rm {self.memory_file}
+""",
+            "command_not_found": f"""Command not found: {details}
+
+Possible fixes:
+1. Install the missing command
+2. Check if it's in your PATH: which {details}
+3. Update hook configuration to use absolute path
+4. Remove the hook if no longer needed
+""",
+            "permission_denied": f"""Permission denied: {details}
+
+Possible fixes:
+1. Check file permissions: ls -la {details}
+2. Make file executable: chmod +x {details}
+3. Run with appropriate privileges
+4. Check file ownership
+""",
+            "syntax_error": """Syntax error in hook configuration or script
+
+Possible fixes:
+1. Review hook configuration in .claude-mpm/config
+2. Check script syntax if using shell hooks
+3. Validate JSON configuration format
+4. Check for typos in hook definitions
+""",
+            "eval_error": f"""Error in hook execution: {details}
+
+Possible fixes:
+1. Review hook handler logs for details
+2. Check hook configuration syntax
+3. Verify all required dependencies are available
+4. Test hook handler manually: python {details}
+""",
+            "general_error": f"""Error during hook execution: {error_info.get("match", "Unknown error")}
+
+Possible fixes:
+1. Check logs for detailed error information
+2. Verify hook configuration is correct
+3. Ensure all dependencies are installed
+4. Clear error memory to retry: rm {self.memory_file}
+""",
+        }
+
+        return suggestions.get(
+            error_type, f"Unknown error type: {error_type}\n\nDetails: {details}"
+        )
+
+    def clear_errors(self, hook_type: Optional[str] = None):
+        """Clear error memory to allow retry of failed hooks.
+
+        Args:
+            hook_type: If specified, only clear errors for this hook type
+        """
+        if hook_type is None:
+            # Clear all errors
+            count = len(self.errors)
+            self.errors.clear()
+            self._save_errors()
+            self.logger.info(f"Cleared all {count} error records")
+        else:
+            # Clear errors for specific hook type
+            keys_to_remove = [
+                key
+                for key, data in self.errors.items()
+                if data["hook_type"] == hook_type
+            ]
+            for key in keys_to_remove:
+                del self.errors[key]
+            self._save_errors()
+            self.logger.info(
+                f"Cleared {len(keys_to_remove)} error records for {hook_type}"
+            )
+
+    def get_error_summary(self) -> Dict[str, Any]:
+        """Get summary of all recorded errors.
+
+        Returns:
+            Dictionary with error statistics and details
+        """
+        if not self.errors:
+            return {
+                "total_errors": 0,
+                "unique_errors": 0,
+                "errors_by_type": {},
+                "errors_by_hook": {},
+            }
+
+        errors_by_type = {}
+        errors_by_hook = {}
+
+        total_count = 0
+
+        for error_data in self.errors.values():
+            error_type = error_data["type"]
+            hook_type = error_data["hook_type"]
+            count = error_data["count"]
+
+            total_count += count
+
+            errors_by_type[error_type] = errors_by_type.get(error_type, 0) + count
+            errors_by_hook[hook_type] = errors_by_hook.get(hook_type, 0) + count
+
+        return {
+            "total_errors": total_count,
+            "unique_errors": len(self.errors),
+            "errors_by_type": errors_by_type,
+            "errors_by_hook": errors_by_hook,
+            "memory_file": str(self.memory_file),
+        }
+
+
+# Global instance
+_hook_error_memory: Optional[HookErrorMemory] = None
+
+
+def get_hook_error_memory(memory_file: Optional[Path] = None) -> HookErrorMemory:
+    """Get the global hook error memory instance.
+
+    Args:
+        memory_file: Optional custom memory file path
+
+    Returns:
+        HookErrorMemory instance
+    """
+    global _hook_error_memory
+    if _hook_error_memory is None:
+        _hook_error_memory = HookErrorMemory(memory_file)
+    return _hook_error_memory
+
+
+def clear_hook_errors(hook_type: Optional[str] = None):
+    """Convenience function to clear hook error memory.
+
+    Args:
+        hook_type: If specified, only clear errors for this hook type
+    """
+    memory = get_hook_error_memory()
+    memory.clear_errors(hook_type)

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

@@ -85,8 +85,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 +293,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
@@ -383,6 +388,14 @@ class InteractiveSession:
             self.logger.debug(f"Raw claude_args received: {self.runner.claude_args}")
             cmd.extend(self.runner.claude_args)
 
+        # Add --agents flag if native agents mode is enabled
+        if getattr(self.runner, "use_native_agents", False):
+            agents_flag = self._build_agents_flag()
+            if agents_flag:
+                # Add --agents JSON directly (already properly formatted)
+                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
 
@@ -402,6 +415,38 @@ class InteractiveSession:
 
         return cmd
 
+    def _build_agents_flag(self) -> Optional[list]:
+        """Build --agents flag with all MPM agents.
+
+        Returns:
+            List with ["--agents", "<json>"] or None if conversion fails
+        """
+        try:
+            from claude_mpm.services.native_agent_converter import NativeAgentConverter
+
+            converter = NativeAgentConverter()
+            agents = converter.load_agents_from_templates()
+
+            if not agents:
+                self.logger.warning("No agents loaded for native mode")
+                return None
+
+            # Generate JSON for --agents flag
+            agents_json = converter.generate_agents_json(agents)
+            summary = converter.get_conversion_summary(agents)
+
+            self.logger.info(
+                f"Native agents: {summary['total_agents']} agents, "
+                f"{summary['json_size_kb']} KB JSON"
+            )
+
+            # Return as list: ["--agents", "<json>"]
+            return ["--agents", agents_json]
+
+        except Exception as e:
+            self.logger.error(f"Failed to build --agents flag: {e}", exc_info=True)
+            return None
+
     def _prepare_environment(self) -> dict:
         """Prepare clean environment variables for Claude."""
         clean_env = os.environ.copy()

claude_mpm/core/interfaces.py

@@ -33,7 +33,62 @@ from pathlib import Path
 from typing import Any, Dict, Generic, List, Optional, Tuple, TypeVar
 
 # Re-export everything from the new location for backward compatibility
-from claude_mpm.services.core.interfaces import *
+from claude_mpm.services.core.interfaces import (  # noqa: F401
+    AgentCapabilitiesInterface,
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    CommandHandlerInterface,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    ICrashDetector,
+    IDeploymentStateManager,
+    IErrorHandler,
+    IEventBus,
+    IHealthCheck,
+    IHealthCheckManager,
+    IHealthMonitor,
+    ILocalProcessManager,
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IModelProvider,
+    IModelRouter,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IResourceMonitor,
+    IRestartManager,
+    IRestartPolicy,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryHookInterface,
+    MemoryServiceInterface,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+    ProjectAnalyzerInterface,
+    RunnerConfigurationInterface,
+    ServiceType,
+    SessionManagementInterface,
+    SocketIOServiceInterface,
+    SubprocessLauncherInterface,
+    SystemInstructionsInterface,
+    T,
+    TemplateRenderContext,
+    TicketManagerInterface,
+    UtilityServiceInterface,
+    VersionServiceInterface,
+)
 
 # Type variables for generic interfaces
 T = TypeVar("T")

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

@@ -268,8 +268,47 @@ class OneshotSession:
         if self.runner.claude_args:
             cmd.extend(self.runner.claude_args)
 
+        # Add --agents flag if native agents mode is enabled
+        if getattr(self.runner, "use_native_agents", False):
+            agents_flag = self._build_agents_flag()
+            if agents_flag:
+                cmd.extend(agents_flag)
+                self.logger.info("✓ Native agents mode: Using --agents CLI flag")
+
         return cmd
 
+    def _build_agents_flag(self) -> Optional[list]:
+        """Build --agents flag with all MPM agents.
+
+        Returns:
+            List with ["--agents", "<json>"] or None if conversion fails
+        """
+        try:
+            from claude_mpm.services.native_agent_converter import NativeAgentConverter
+
+            converter = NativeAgentConverter()
+            agents = converter.load_agents_from_templates()
+
+            if not agents:
+                self.logger.warning("No agents loaded for native mode")
+                return None
+
+            # Generate JSON for --agents flag
+            agents_json = converter.generate_agents_json(agents)
+            summary = converter.get_conversion_summary(agents)
+
+            self.logger.info(
+                f"Native agents: {summary['total_agents']} agents, "
+                f"{summary['json_size_kb']} KB JSON"
+            )
+
+            # Return as list: ["--agents", "<json>"]
+            return ["--agents", agents_json]
+
+        except Exception as e:
+            self.logger.error(f"Failed to build --agents flag: {e}", exc_info=True)
+            return None
+
     def _handle_successful_response(self, response: str, prompt: str) -> None:
         """Process a successful Claude response."""
         print(response)

claude_mpm/core/optimized_agent_loader.py

@@ -236,7 +236,7 @@ class OptimizedAgentLoader:
 
         self.metrics.total_time = time.time() - start_time
 
-        self.logger.info(
+        self.logger.debug(
             f"Loaded {self.metrics.loaded_agents}/{self.metrics.total_agents} agents "
             f"in {self.metrics.total_time:.2f}s "
             f"(cache hits: {self.metrics.cache_hits}, misses: {self.metrics.cache_misses})"
@@ -286,7 +286,7 @@ class OptimizedAgentLoader:
 
         self.metrics.total_time = time.time() - start_time
 
-        self.logger.info(
+        self.logger.debug(
             f"Async loaded {self.metrics.loaded_agents}/{self.metrics.total_agents} agents "
             f"in {self.metrics.total_time:.2f}s"
         )
@@ -418,7 +418,7 @@ class OptimizedAgentLoader:
         Args:
             agent_dirs: List of directories containing agents
         """
-        self.logger.info(f"Preloading agents from {len(agent_dirs)} directories")
+        self.logger.debug(f"Preloading agents from {len(agent_dirs)} directories")
 
         all_paths = []
         for dir_path in agent_dirs: