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

claude_mpm/services/core/interfaces.py

@@ -20,7 +20,62 @@ focused modules for better maintainability and testing.
 """
 
 # Re-export everything from the new modular structure for backward compatibility
-from .interfaces import *
+from .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,
+)
 
 # All interface definitions have been moved to the interfaces/ package
 # This file now serves as a compatibility layer that delegates to the modular structure

claude_mpm/services/core/models/agent_config.py

@@ -19,6 +19,9 @@ from typing import Any, Dict, List, Optional
 
 from ....core.enums import OperationResult, ValidationSeverity
 
+# Backward compatibility alias (consolidated in Phase 3A Batch 25)
+ConfigurationStatus = OperationResult
+
 
 class AgentSpecialization(str, Enum):
     """Agent specialization categories.

claude_mpm/services/core/models/process.py

@@ -25,6 +25,9 @@ from typing import Any, Dict, List, Optional
 
 from claude_mpm.core.enums import ServiceState
 
+# Backward compatibility alias (consolidated in Phase 3A Batch 24)
+ProcessStatus = ServiceState
+
 
 @dataclass
 class DeploymentState:
@@ -230,6 +233,7 @@ __all__ = [
     "PROTECTED_PORT_RANGES",
     "DeploymentState",
     "ProcessInfo",
+    "ProcessStatus",  # Backward compatibility alias for ServiceState
     "StartConfig",
     "is_port_protected",
 ]

claude_mpm/services/diagnostics/checks/agent_check.py

@@ -188,7 +188,6 @@ class AgentCheck(BaseDiagnosticCheck):
     def _check_agent_versions(self) -> DiagnosticResult:
         """Check if deployed agents are up-to-date."""
         try:
-
             from ....services.agents.deployment.agent_version_manager import (
                 AgentVersionManager,
             )
@@ -258,7 +257,6 @@ class AgentCheck(BaseDiagnosticCheck):
     def _validate_agents(self) -> DiagnosticResult:
         """Validate agent configurations."""
         try:
-
             from ....services.agents.deployment.agent_validator import AgentValidator
 
             AgentValidator()

claude_mpm/services/diagnostics/checks/instructions_check.py

@@ -220,8 +220,7 @@ class InstructionsCheck(BaseDiagnosticCheck):
                 files_str = ", ".join(str(path) for path, _ in occurrences)
                 snippet = occurrences[0][1]
                 duplicates.append(
-                    f"Duplicate content found in: {files_str}\n"
-                    f"  Snippet: {snippet}..."
+                    f"Duplicate content found in: {files_str}\n  Snippet: {snippet}..."
                 )
 
         if duplicates:

claude_mpm/services/diagnostics/checks/mcp_check.py

@@ -29,7 +29,6 @@ class MCPCheck(BaseDiagnosticCheck):
     def run(self) -> DiagnosticResult:
         """Run MCP diagnostics."""
         try:
-
             sub_results = []
             details = {}
 

claude_mpm/services/diagnostics/checks/monitor_check.py

@@ -26,7 +26,6 @@ class MonitorCheck(BaseDiagnosticCheck):
     def run(self) -> DiagnosticResult:
         """Run monitor diagnostics."""
         try:
-
             sub_results = []
             details = {}
 

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -271,15 +271,17 @@ class DoctorReporter:
             + summary.skipped_count
         )
         if total > 0:
-            print(f"| ✅ OK | {summary.ok_count} | {summary.ok_count*100//total}% |")
             print(
-                f"| ⚠️  Warning | {summary.warning_count} | {summary.warning_count*100//total}% |"
+                f"| ✅ OK | {summary.ok_count} | {summary.ok_count * 100 // total}% |"
             )
             print(
-                f"| ❌ Error | {summary.error_count} | {summary.error_count*100//total}% |"
+                f"| ⚠️  Warning | {summary.warning_count} | {summary.warning_count * 100 // total}% |"
             )
             print(
-                f"| ⏭️  Skipped | {summary.skipped_count} | {summary.skipped_count*100//total}% |"
+                f"| ❌ Error | {summary.error_count} | {summary.error_count * 100 // total}% |"
+            )
+            print(
+                f"| ⏭️  Skipped | {summary.skipped_count} | {summary.skipped_count * 100 // total}% |"
             )
         print()
 

claude_mpm/services/diagnostics/models.py

@@ -6,11 +6,32 @@ consistency across all checks and reporting.
 """
 
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Any, Dict, List, Optional, Union
 
 from ...core.enums import OperationResult, ValidationSeverity
 
 
+class DiagnosticStatus(str, Enum):
+    """Backward compatibility wrapper for diagnostic status values.
+
+    WHY: Provides backward compatibility for tests and code that use
+    DiagnosticStatus instead of the consolidated OperationResult/ValidationSeverity.
+
+    DESIGN DECISION: Maps to the appropriate consolidated enum values:
+    - OK → OperationResult.SUCCESS
+    - WARNING → ValidationSeverity.WARNING
+    - ERROR → ValidationSeverity.ERROR
+
+    Note: This is a compatibility layer. New code should use OperationResult
+    and ValidationSeverity directly.
+    """
+
+    OK = "success"  # Maps to OperationResult.SUCCESS
+    WARNING = "warning"  # Maps to ValidationSeverity.WARNING
+    ERROR = "error"  # Maps to ValidationSeverity.ERROR
+
+
 @dataclass
 class DiagnosticResult:
     """Result from a diagnostic check.

claude_mpm/services/event_bus/README.md

@@ -0,0 +1,244 @@
+# EventBus Service
+
+A decoupled event handling system for claude-mpm that enables loose coupling between event producers (like hooks) and consumers (like Socket.IO).
+
+## Overview
+
+The EventBus service provides a centralized publish-subscribe system that:
+- Decouples event producers from consumers
+- Supports both synchronous and asynchronous handlers
+- Provides event filtering and routing capabilities
+- Isolates failures in individual consumers
+- Offers comprehensive monitoring and statistics
+
+## Architecture
+
+```
+Hook Handler → EventBus → Multiple Consumers
+                         ├── Socket.IO Relay
+                         ├── Logging Service
+                         ├── Analytics
+                         └── Custom Handlers
+```
+
+## Key Components
+
+### EventBus (`event_bus.py`)
+- Singleton pattern for centralized event coordination
+- Thread-safe event publishing from any context
+- Support for wildcard subscriptions (`hook.*`)
+- Event filtering and routing
+- Built-in statistics and history tracking
+
+### SocketIORelay (`relay.py`)
+- Consumes events from EventBus
+- Relays to Socket.IO clients
+- Handles connection failures gracefully
+- Single point of Socket.IO management
+
+### Configuration (`config.py`)
+- Environment variable support
+- Runtime configuration changes
+- Easy testing with different settings
+
+## Installation
+
+The EventBus requires `pyee` (Python EventEmitter):
+
+```bash
+pip install pyee>=13.0.0
+```
+
+## Usage
+
+### Basic Publishing
+
+```python
+from claude_mpm.services.event_bus import EventBus
+
+# Get singleton instance
+event_bus = EventBus.get_instance()
+
+# Publish an event
+event_bus.publish("hook.pre_tool", {
+    "tool_name": "Read",
+    "file_path": "/example.py",
+    "sessionId": "abc-123"
+})
+```
+
+### Subscribing to Events
+
+```python
+# Subscribe to specific event
+def handle_pre_tool(data):
+    print(f"Tool: {data.get('tool_name')}")
+
+event_bus.on("hook.pre_tool", handle_pre_tool)
+
+# Subscribe to wildcard pattern
+def handle_all_hooks(event_type, data):
+    print(f"Hook event: {event_type}")
+
+event_bus.on("hook.*", handle_all_hooks)
+```
+
+### Async Handlers
+
+```python
+async def async_handler(data):
+    await process_async(data)
+
+event_bus.on("app.async_event", async_handler)
+```
+
+### Event Filtering
+
+```python
+# Only allow specific events
+event_bus.add_filter("hook.*")
+event_bus.add_filter("system.critical.*")
+
+# Events outside filters will be dropped
+event_bus.publish("app.user_action", {})  # Filtered out
+```
+
+### Socket.IO Integration
+
+```python
+from claude_mpm.services.event_bus import SocketIORelay
+
+# Create and start relay
+relay = SocketIORelay(port=8765)
+relay.start()
+
+# Events published to EventBus will be relayed to Socket.IO
+event_bus.publish("hook.subagent_stop", {
+    "agent_type": "Engineer",
+    "result": "Success"
+})
+```
+
+## Configuration
+
+Configure via environment variables:
+
+```bash
+# EventBus settings
+export CLAUDE_MPM_EVENTBUS_ENABLED=true
+export CLAUDE_MPM_EVENTBUS_DEBUG=false
+export CLAUDE_MPM_EVENTBUS_HISTORY_SIZE=100
+export CLAUDE_MPM_EVENTBUS_FILTERS="hook.*,system.critical.*"
+
+# Relay settings
+export CLAUDE_MPM_RELAY_ENABLED=true
+export CLAUDE_MPM_SOCKETIO_PORT=8765
+export CLAUDE_MPM_RELAY_DEBUG=false
+export CLAUDE_MPM_RELAY_MAX_RETRIES=3
+```
+
+## Migration from Direct Socket.IO
+
+### Before (Direct Socket.IO)
+```python
+# In hook_handler.py
+client = socketio.Client()
+client.connect("http://localhost:8765")
+client.emit("claude_event", normalized_data)
+```
+
+### After (EventBus)
+```python
+# In hook_handler.py
+event_bus = EventBus.get_instance()
+event_bus.publish("hook.pre_tool", data)
+
+# Socket.IO handled by relay (separate concern)
+```
+
+## Benefits
+
+1. **Decoupling**: Hooks don't need to know about Socket.IO
+2. **Testability**: Easy to test without Socket.IO running
+3. **Reliability**: Failures in one consumer don't affect others
+4. **Flexibility**: Add new consumers without modifying producers
+5. **Performance**: Events processed asynchronously
+6. **Monitoring**: Built-in statistics and event history
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Integration tests
+python scripts/test_eventbus_integration.py
+
+# Usage examples
+python scripts/eventbus_usage_example.py
+
+# Complete flow test
+python scripts/test_eventbus_flow.py
+```
+
+## Monitoring
+
+Get EventBus statistics:
+
+```python
+stats = event_bus.get_stats()
+print(f"Events published: {stats['events_published']}")
+print(f"Events filtered: {stats['events_filtered']}")
+
+# Recent event history
+recent = event_bus.get_recent_events(10)
+for event in recent:
+    print(f"{event['type']} at {event['timestamp']}")
+```
+
+## Error Handling
+
+Errors in consumers are isolated:
+
+```python
+def good_handler(data):
+    process(data)  # Always runs
+
+def bad_handler(data):
+    raise Exception("Error")  # Doesn't affect good_handler
+
+event_bus.on("app.event", good_handler)
+event_bus.on("app.event", bad_handler)
+```
+
+## Performance
+
+- Handles 30,000+ events/second
+- Minimal memory overhead
+- Thread-safe for concurrent publishing
+- Efficient wildcard matching
+
+## Troubleshooting
+
+### Events not being received
+1. Check if EventBus is enabled: `CLAUDE_MPM_EVENTBUS_ENABLED=true`
+2. Verify no filters are blocking: `event_bus.clear_filters()`
+3. Check handler registration: `event_bus.on("event_type", handler)`
+
+### Socket.IO relay not working
+1. Verify Socket.IO server is running on configured port
+2. Check relay is started: `relay.start()`
+3. Enable debug logging: `CLAUDE_MPM_RELAY_DEBUG=true`
+
+### High memory usage
+1. Reduce history size: `CLAUDE_MPM_EVENTBUS_HISTORY_SIZE=50`
+2. Clear history periodically: `event_bus.clear_history()`
+
+## Future Enhancements
+
+- [ ] Persistent event storage
+- [ ] Event replay capabilities
+- [ ] Advanced routing rules
+- [ ] Event prioritization
+- [ ] Distributed EventBus (Redis backend)
+- [ ] Event schema validation
+- [ ] Rate limiting per consumer

claude_mpm/services/event_bus/direct_relay.py

@@ -256,9 +256,9 @@ class DirectSocketIORelay:
                                         event_type, broadcast_data
                                     )
                                     self.stats["events_relayed"] += 1
-                                    self.stats[
-                                        "events_failed"
-                                    ] -= 1  # Undo the failure count
+                                    self.stats["events_failed"] -= (
+                                        1  # Undo the failure count
+                                    )
                                     logger.info(
                                         f"[DirectRelay] Retry successful for {event_type}"
                                     )

claude_mpm/services/event_bus/event_bus.py

@@ -68,6 +68,9 @@ class EventBus:
         # Track async handler tasks to prevent garbage collection
         self._handler_tasks: Set[asyncio.Task] = set()
 
+        # Track handler wrappers for removal
+        self._handler_wrappers: Dict[tuple, Callable] = {}
+
         logger.info("EventBus initialized")
 
     @classmethod
@@ -266,8 +269,20 @@ class EventBus:
 
             logger.debug(f"Registered wildcard handler for: {event_type}")
         else:
-            # Regular event registration
-            self._emitter.on(event_type, handler)
+            # Wrap handler to catch exceptions and prevent them from stopping other handlers
+            def safe_handler(data):
+                try:
+                    handler(data)
+                except Exception as e:
+                    if self._debug:
+                        logger.debug(f"Handler error for {event_type}: {e}")
+
+            # Store mapping for later removal
+            wrapper_key = (event_type, handler)
+            self._handler_wrappers[wrapper_key] = safe_handler
+
+            # Regular event registration with wrapped handler
+            self._emitter.on(event_type, safe_handler)
             logger.debug(f"Registered handler for: {event_type}")
 
     def once(self, event_type: str, handler: Callable) -> None:
@@ -287,7 +302,17 @@ class EventBus:
             event_type: The event type
             handler: The handler to remove
         """
-        self._emitter.remove_listener(event_type, handler)
+        # Check if we have a wrapped version of this handler
+        wrapper_key = (event_type, handler)
+        if wrapper_key in self._handler_wrappers:
+            # Remove the wrapped handler from pyee
+            wrapped_handler = self._handler_wrappers[wrapper_key]
+            self._emitter.remove_listener(event_type, wrapped_handler)
+            # Remove from our tracking dict
+            del self._handler_wrappers[wrapper_key]
+        else:
+            # No wrapper, remove directly (e.g., for wildcard handlers or direct registrations)
+            self._emitter.remove_listener(event_type, handler)
         logger.debug(f"Removed handler for: {event_type}")
 
     def remove_all_listeners(self, event_type: Optional[str] = None) -> None:
@@ -298,9 +323,17 @@ class EventBus:
         """
         if event_type:
             self._emitter.remove_all_listeners(event_type)
+            # Clean up wrappers for this event type
+            wrappers_to_remove = [
+                key for key in self._handler_wrappers if key[0] == event_type
+            ]
+            for key in wrappers_to_remove:
+                del self._handler_wrappers[key]
             logger.debug(f"Removed all handlers for: {event_type}")
         else:
             self._emitter.remove_all_listeners()
+            # Clean up all wrappers
+            self._handler_wrappers.clear()
             logger.debug("Removed all event handlers")
 
     def _record_event(self, event_type: str, data: Any) -> None:

claude_mpm/services/event_bus/relay.py

@@ -9,6 +9,7 @@ WHY separate relay component:
 """
 
 import os
+import threading
 import time
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
@@ -271,11 +272,15 @@ class SocketIORelay:
 
 # Global relay instance
 _relay_instance: Optional[SocketIORelay] = None
+_relay_lock = threading.Lock()
 
 
 def get_relay(port: Optional[int] = None) -> SocketIORelay:
     """Get or create the global SocketIO relay instance.
 
+    Thread-safe implementation using double-checked locking pattern to
+    prevent race conditions during concurrent initialization.
+
     Args:
         port: Optional port number
 
@@ -283,9 +288,16 @@ def get_relay(port: Optional[int] = None) -> SocketIORelay:
         SocketIORelay: The relay instance
     """
     global _relay_instance
-    if _relay_instance is None:
-        _relay_instance = SocketIORelay(port)
-    return _relay_instance
+
+    # Fast path - check without lock
+    if _relay_instance is not None:
+        return _relay_instance
+
+    # Slow path - acquire lock and double-check
+    with _relay_lock:
+        if _relay_instance is None:
+            _relay_instance = SocketIORelay(port)
+        return _relay_instance
 
 
 def start_relay(port: Optional[int] = None) -> SocketIORelay:
@@ -303,8 +315,12 @@ def start_relay(port: Optional[int] = None) -> SocketIORelay:
 
 
 def stop_relay() -> None:
-    """Stop the global SocketIO relay."""
+    """Stop the global SocketIO relay.
+
+    Thread-safe implementation ensures proper cleanup.
+    """
     global _relay_instance
-    if _relay_instance:
-        _relay_instance.stop()
-        _relay_instance = None
+    with _relay_lock:
+        if _relay_instance:
+            _relay_instance.stop()
+            _relay_instance = None