claude-mpm 4.0.31__py3-none-any.whl → 4.0.34__py3-none-any.whl

claude_mpm/services/socketio/handlers/connection.py

@@ -161,8 +161,13 @@ class ConnectionEventHandler(BaseEventHandler):
                 
                 for sid in list(self.clients):
                     try:
-                        # Send ping and record time
-                        await self.sio.emit('ping', {'timestamp': current_time}, room=sid)
+                        # Send ping and record time (using new schema)
+                        await self.sio.emit('ping', {
+                            'type': 'system',
+                            'subtype': 'ping',
+                            'timestamp': current_time,
+                            'source': 'server'
+                        }, room=sid)
                         self.last_ping_times[sid] = current_time
                         
                         # Update connection metrics
@@ -284,16 +289,35 @@ class ConnectionEventHandler(BaseEventHandler):
             self.logger.info(f"📱 User Agent: {user_agent[:100]}...")
             self.logger.info(f"📈 Total clients now: {len(self.clients)}")
 
-            # Send initial status immediately with enhanced data
+            # Get monitor build info
+            monitor_build_info = {}
+            try:
+                from ....services.monitor_build_service import get_monitor_build_service
+                monitor_service = get_monitor_build_service()
+                monitor_build_info = monitor_service.get_build_info_sync()
+            except Exception as e:
+                self.logger.debug(f"Could not get monitor build info: {e}")
+                monitor_build_info = {
+                    "monitor": {"version": "1.0.0", "build": 1, "formatted_build": "0001"},
+                    "mpm": {"version": "unknown", "build": "unknown"}
+                }
+
+            # Send initial status immediately with enhanced data (using new schema)
             status_data = {
-                "server": "claude-mpm-python-socketio",
+                "type": "connection",
+                "subtype": "status",
                 "timestamp": datetime.utcnow().isoformat() + "Z",
-                "clients_connected": len(self.clients),
+                "source": "server",
                 "session_id": self.server.session_id,
-                "claude_status": self.server.claude_status,
-                "claude_pid": self.server.claude_pid,
-                "server_version": "2.0.0",
-                "client_id": sid,
+                "data": {
+                    "server": "claude-mpm-python-socketio",
+                    "clients_connected": len(self.clients),
+                    "claude_status": self.server.claude_status,
+                    "claude_pid": self.server.claude_pid,
+                    "server_version": "2.0.0",
+                    "client_id": sid,
+                    "build_info": monitor_build_info,
+                }
             }
 
             try:
@@ -302,9 +326,17 @@ class ConnectionEventHandler(BaseEventHandler):
                     sid,
                     "welcome",
                     {
-                        "message": "Connected to Claude MPM Socket.IO server",
-                        "client_id": sid,
-                        "server_time": datetime.utcnow().isoformat() + "Z",
+                        "type": "connection",
+                        "subtype": "welcome",
+                        "timestamp": datetime.utcnow().isoformat() + "Z",
+                        "source": "server",
+                        "session_id": self.server.session_id,
+                        "data": {
+                            "message": "Connected to Claude MPM Socket.IO server",
+                            "client_id": sid,
+                            "server_time": datetime.utcnow().isoformat() + "Z",
+                            "build_info": monitor_build_info,
+                        }
                     },
                 )
 
@@ -349,12 +381,17 @@ class ConnectionEventHandler(BaseEventHandler):
             to update their UI or verify connection health.
             """
             status_data = {
-                "server": "claude-mpm-python-socketio",
+                "type": "connection",
+                "subtype": "status",
                 "timestamp": datetime.utcnow().isoformat() + "Z",
-                "clients_connected": len(self.clients),
+                "source": "server",
                 "session_id": self.server.session_id,
-                "claude_status": self.server.claude_status,
-                "claude_pid": self.server.claude_pid,
+                "data": {
+                    "server": "claude-mpm-python-socketio",
+                    "clients_connected": len(self.clients),
+                    "claude_status": self.server.claude_status,
+                    "claude_pid": self.server.claude_pid,
+                }
             }
             await self.emit_to_client(sid, "status", status_data)
 
@@ -395,7 +432,13 @@ class ConnectionEventHandler(BaseEventHandler):
             for filtered event streaming.
             """
             channels = data.get("channels", ["*"]) if data else ["*"]
-            await self.emit_to_client(sid, "subscribed", {"channels": channels})
+            await self.emit_to_client(sid, "subscribed", {
+                "type": "connection",
+                "subtype": "subscribed",
+                "timestamp": datetime.utcnow().isoformat() + "Z",
+                "source": "server",
+                "data": {"channels": channels}
+            })
 
         @self.sio.event
         @timeout_handler(timeout_seconds=5.0)
@@ -409,10 +452,24 @@ class ConnectionEventHandler(BaseEventHandler):
             self.logger.info(f"🔵 Received claude_event from {sid}: {data}")
             
             # Check if this is a hook event and route to HookEventHandler
-            # Hook events have types like "hook.user_prompt", "hook.pre_tool", etc.
+            # Hook events can have either:
+            # 1. Normalized format: type="hook", subtype="pre_tool"
+            # 2. Legacy format: type="hook.pre_tool"
             if isinstance(data, dict):
                 event_type = data.get("type", "")
-                if isinstance(event_type, str) and event_type.startswith("hook."):
+                event_subtype = data.get("subtype", "")
+                
+                # Check for both normalized and legacy formats
+                is_hook_event = False
+                if isinstance(event_type, str):
+                    # Legacy format: type="hook.something"
+                    if event_type.startswith("hook."):
+                        is_hook_event = True
+                    # Normalized format: type="hook" with any subtype
+                    elif event_type == "hook":
+                        is_hook_event = True
+                
+                if is_hook_event:
                     # Get the hook handler if available
                     hook_handler = None
                     # Check if event_registry exists and has handlers
@@ -502,7 +559,8 @@ class ConnectionEventHandler(BaseEventHandler):
             elif event_name == 'ToolCall':
                 normalized['type'] = 'tool'
             elif event_name == 'UserPrompt':
-                normalized['type'] = 'hook.user_prompt'
+                normalized['type'] = 'hook'
+                normalized['subtype'] = 'user_prompt'
             else:
                 # Default to system type for unknown events
                 normalized['type'] = 'system'

claude_mpm/services/socketio/handlers/hook.py

@@ -41,14 +41,23 @@ class HookEventHandler(BaseEventHandler):
             return
             
         # Extract hook event details
-        # Hook events come as: { type: "hook.user_prompt", timestamp: "...", data: {...} }
+        # Hook events can come in two formats:
+        # 1. Normalized: { type: "hook", subtype: "user_prompt", ... }
+        # 2. Legacy: { type: "hook.user_prompt", ... }
         event_type = data.get("type", "")
-        
-        # Extract the actual hook event name from the type (e.g., "hook.user_prompt" -> "user_prompt")
-        if event_type.startswith("hook."):
+        event_subtype = data.get("subtype", "")
+        
+        # Determine the actual hook event name
+        hook_event = ""
+        if event_type == "hook" and event_subtype:
+            # Normalized format: use subtype directly
+            hook_event = event_subtype
+        elif isinstance(event_type, str) and event_type.startswith("hook."):
+            # Legacy format: extract from dotted type
             hook_event = event_type[5:]  # Remove "hook." prefix
         else:
-            hook_event = data.get("event", "")  # Fallback for legacy format
+            # Fallback: check for 'event' field (another legacy format)
+            hook_event = data.get("event", "")
             
         hook_data = data.get("data", {})
         

claude_mpm/services/socketio/migration_utils.py

@@ -0,0 +1,329 @@
+"""
+Migration utilities for Socket.IO event schema migration.
+
+WHY: This module provides utilities to help migrate from the old event
+formats to the new normalized schema, ensuring backward compatibility
+during the transition period.
+
+DESIGN DECISION: Provide both transformation and validation utilities
+to help identify and fix inconsistent event formats across the codebase.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+import json
+
+from ...core.logging_config import get_logger
+
+
+class EventMigrationHelper:
+    """Helper class for migrating events to the new schema.
+    
+    WHY: Provides utilities to identify old format events and
+    transform them to the new normalized schema.
+    """
+    
+    def __init__(self):
+        self.logger = get_logger(self.__class__.__name__)
+        self.migration_stats = {
+            "old_format_detected": 0,
+            "transformed": 0,
+            "validation_failed": 0,
+            "already_normalized": 0
+        }
+    
+    def is_old_format(self, event_data: Any) -> bool:
+        """Check if an event is in the old format.
+        
+        WHY: Need to identify which events need migration.
+        """
+        if not isinstance(event_data, dict):
+            return True  # Non-dict events are definitely old format
+        
+        # Check for new format fields
+        required_new_fields = {"event", "type", "subtype", "timestamp", "data"}
+        has_all_new_fields = all(field in event_data for field in required_new_fields)
+        
+        if has_all_new_fields:
+            self.migration_stats["already_normalized"] += 1
+            return False
+        
+        # Old format indicators
+        old_format_indicators = [
+            # Hook format with "hook." prefix in type
+            "type" in event_data and isinstance(event_data.get("type"), str) and event_data["type"].startswith("hook."),
+            # Missing subtype field
+            "type" in event_data and "subtype" not in event_data,
+            # Event field used differently
+            "event" in event_data and event_data.get("event") != "claude_event",
+        ]
+        
+        if any(old_format_indicators):
+            self.migration_stats["old_format_detected"] += 1
+            return True
+        
+        return False
+    
+    def transform_to_new_format(self, event_data: Any) -> Dict[str, Any]:
+        """Transform an old format event to the new schema.
+        
+        WHY: Provides a migration path from old to new format.
+        """
+        # Import here to avoid circular dependency
+        from .event_normalizer import EventNormalizer
+        
+        normalizer = EventNormalizer()
+        normalized = normalizer.normalize(event_data)
+        
+        self.migration_stats["transformed"] += 1
+        return normalized.to_dict()
+    
+    def validate_event_schema(self, event_data: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """Validate an event against the new schema.
+        
+        WHY: Ensures events conform to the expected structure
+        before being sent to clients.
+        
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        errors = []
+        
+        # Check required fields
+        required_fields = {"event", "type", "subtype", "timestamp", "data"}
+        missing_fields = required_fields - set(event_data.keys())
+        if missing_fields:
+            errors.append(f"Missing required fields: {missing_fields}")
+        
+        # Validate field types
+        if "event" in event_data and event_data["event"] != "claude_event":
+            errors.append(f"Invalid event name: {event_data['event']} (should be 'claude_event')")
+        
+        if "type" in event_data and not isinstance(event_data["type"], str):
+            errors.append(f"Invalid type field: should be string, got {type(event_data['type'])}")
+        
+        if "subtype" in event_data and not isinstance(event_data["subtype"], str):
+            errors.append(f"Invalid subtype field: should be string, got {type(event_data['subtype'])}")
+        
+        if "timestamp" in event_data:
+            timestamp = event_data["timestamp"]
+            if not isinstance(timestamp, str) or "T" not in timestamp:
+                errors.append(f"Invalid timestamp format: {timestamp} (should be ISO format)")
+        
+        if "data" in event_data and not isinstance(event_data["data"], dict):
+            errors.append(f"Invalid data field: should be dict, got {type(event_data['data'])}")
+        
+        if errors:
+            self.migration_stats["validation_failed"] += 1
+            return False, errors
+        
+        return True, []
+    
+    def get_migration_report(self) -> str:
+        """Generate a report of migration statistics.
+        
+        WHY: Helps track migration progress and identify issues.
+        """
+        report = "Event Migration Report\n"
+        report += "=" * 50 + "\n"
+        report += f"Old format detected: {self.migration_stats['old_format_detected']}\n"
+        report += f"Events transformed: {self.migration_stats['transformed']}\n"
+        report += f"Validation failures: {self.migration_stats['validation_failed']}\n"
+        report += f"Already normalized: {self.migration_stats['already_normalized']}\n"
+        return report
+    
+    def reset_stats(self):
+        """Reset migration statistics."""
+        self.migration_stats = {
+            "old_format_detected": 0,
+            "transformed": 0,
+            "validation_failed": 0,
+            "already_normalized": 0
+        }
+
+
+class EventTypeMapper:
+    """Maps old event types to new type/subtype categories.
+    
+    WHY: Provides a consistent mapping from legacy event names
+    to the new categorized structure.
+    """
+    
+    # Comprehensive mapping of old event formats to new categories
+    TYPE_MAPPINGS = {
+        # Hook events with "hook." prefix
+        "hook.pre_tool": ("hook", "pre_tool"),
+        "hook.post_tool": ("hook", "post_tool"),
+        "hook.pre_response": ("hook", "pre_response"),
+        "hook.post_response": ("hook", "post_response"),
+        "hook.start": ("hook", "start"),
+        "hook.stop": ("hook", "stop"),
+        "hook.subagent_start": ("hook", "subagent_start"),
+        "hook.subagent_stop": ("hook", "subagent_stop"),
+        
+        # Hook events without prefix
+        "pre_tool": ("hook", "pre_tool"),
+        "post_tool": ("hook", "post_tool"),
+        "pre_response": ("hook", "pre_response"),
+        "post_response": ("hook", "post_response"),
+        
+        # System events
+        "system_heartbeat": ("system", "heartbeat"),
+        "heartbeat": ("system", "heartbeat"),
+        "system_status": ("system", "status"),
+        
+        # Session events
+        "session_started": ("session", "started"),
+        "session_ended": ("session", "ended"),
+        
+        # File events
+        "file_changed": ("file", "changed"),
+        "file_created": ("file", "created"),
+        "file_deleted": ("file", "deleted"),
+        
+        # Connection events
+        "client_connected": ("connection", "connected"),
+        "client_disconnected": ("connection", "disconnected"),
+        
+        # Memory events
+        "memory_loaded": ("memory", "loaded"),
+        "memory_created": ("memory", "created"),
+        "memory_updated": ("memory", "updated"),
+        "memory_injected": ("memory", "injected"),
+        
+        # Git events
+        "git_operation": ("git", "operation"),
+        "git_commit": ("git", "commit"),
+        "git_push": ("git", "push"),
+        
+        # Todo events
+        "todo_updated": ("todo", "updated"),
+        "todo_created": ("todo", "created"),
+        
+        # Ticket events
+        "ticket_created": ("ticket", "created"),
+        "ticket_updated": ("ticket", "updated"),
+        
+        # Agent events
+        "agent_delegated": ("agent", "delegated"),
+        "agent_completed": ("agent", "completed"),
+        
+        # Claude events
+        "claude_status": ("claude", "status"),
+        "claude_output": ("claude", "output"),
+        
+        # Error events
+        "error": ("error", "general"),
+        "error_occurred": ("error", "occurred"),
+        
+        # Performance events
+        "performance": ("performance", "metric"),
+        "performance_metric": ("performance", "metric"),
+    }
+    
+    @classmethod
+    def map_event_type(cls, old_type: str) -> Tuple[str, str]:
+        """Map an old event type to new type/subtype.
+        
+        WHY: Provides consistent categorization for all events.
+        
+        Args:
+            old_type: The old event type string
+            
+        Returns:
+            Tuple of (type, subtype)
+        """
+        # Direct mapping
+        if old_type in cls.TYPE_MAPPINGS:
+            return cls.TYPE_MAPPINGS[old_type]
+        
+        # Try to infer from patterns
+        old_lower = old_type.lower()
+        
+        # Hook events
+        if "hook" in old_lower or old_lower.startswith("pre_") or old_lower.startswith("post_"):
+            # Remove "hook." prefix if present
+            clean_type = old_type.replace("hook.", "")
+            return "hook", clean_type
+        
+        # System events
+        if "system" in old_lower or "heartbeat" in old_lower:
+            return "system", old_type.replace("system_", "")
+        
+        # Session events
+        if "session" in old_lower:
+            if "start" in old_lower:
+                return "session", "started"
+            elif "end" in old_lower:
+                return "session", "ended"
+            return "session", "generic"
+        
+        # File events
+        if "file" in old_lower:
+            if "create" in old_lower:
+                return "file", "created"
+            elif "delete" in old_lower:
+                return "file", "deleted"
+            elif "change" in old_lower or "modify" in old_lower:
+                return "file", "changed"
+            return "file", "generic"
+        
+        # Default mapping
+        return "unknown", old_type
+    
+    @classmethod
+    def get_event_category(cls, event_type: str, event_subtype: str) -> str:
+        """Get a human-readable category for an event.
+        
+        WHY: Helps with filtering and display in UIs.
+        """
+        categories = {
+            "hook": "Claude Hooks",
+            "system": "System Status",
+            "session": "Session Management",
+            "file": "File Operations",
+            "connection": "Client Connections",
+            "memory": "Memory System",
+            "git": "Git Operations",
+            "todo": "Todo Management",
+            "ticket": "Ticket System",
+            "agent": "Agent Delegation",
+            "claude": "Claude Process",
+            "error": "Errors",
+            "performance": "Performance Metrics",
+            "unknown": "Uncategorized"
+        }
+        return categories.get(event_type, "Other")
+
+
+def create_backward_compatible_event(normalized_event: Dict[str, Any]) -> Dict[str, Any]:
+    """Create a backward-compatible version of a normalized event.
+    
+    WHY: During migration, some clients may still expect the old format.
+    This creates an event that works with both old and new clients.
+    
+    Args:
+        normalized_event: Event in the new normalized format
+        
+    Returns:
+        Event that includes both old and new format fields
+    """
+    # Start with the normalized event
+    compat_event = normalized_event.copy()
+    
+    # Add old format fields based on type/subtype
+    event_type = normalized_event.get("type", "")
+    event_subtype = normalized_event.get("subtype", "")
+    
+    # For hook events, add the old "hook." prefix format
+    if event_type == "hook":
+        compat_event["type_legacy"] = f"hook.{event_subtype}"
+    
+    # For other events, use the old naming convention
+    elif event_type in ["session", "file", "memory", "git", "todo", "ticket", "agent", "claude"]:
+        compat_event["type_legacy"] = f"{event_type}_{event_subtype}"
+    
+    # Add event_type field for really old clients
+    compat_event["event_type"] = compat_event.get("type_legacy", f"{event_type}_{event_subtype}")
+    
+    return compat_event

claude_mpm/services/socketio/server/broadcaster.py

@@ -17,6 +17,7 @@ from datetime import datetime
 from typing import Any, Deque, Dict, List, Optional, Set
 
 from ....core.logging_config import get_logger
+from ..event_normalizer import EventNormalizer
 
 
 @dataclass
@@ -178,6 +179,9 @@ class SocketIOEventBroadcaster:
         self.retry_queue = RetryQueue(max_size=1000)
         self.retry_task = None
         self.retry_interval = 2.0  # Process retry queue every 2 seconds
+        
+        # Initialize event normalizer for consistent schema
+        self.normalizer = EventNormalizer()
     
     def start_retry_processor(self):
         """Start the background retry processor.
@@ -274,21 +278,25 @@ class SocketIOEventBroadcaster:
         """Retry broadcasting a failed event.
         
         WHY: Isolated retry logic allows for special handling
-        and metrics tracking of retry attempts.
+        and metrics tracking of retry attempts. Uses normalizer
+        to ensure consistent schema.
         """
         try:
             self.logger.debug(
                 f"🔄 Retrying {event.event_type} (attempt {event.attempt_count + 1}/{event.max_retries})"
             )
             
-            # Reconstruct the full event
-            full_event = {
+            # Reconstruct the raw event
+            raw_event = {
                 "type": event.event_type,
                 "timestamp": datetime.now().isoformat(),
-                "data": event.data,
-                "retry_attempt": event.attempt_count + 1
+                "data": {**event.data, "retry_attempt": event.attempt_count + 1},
             }
             
+            # Normalize the event
+            normalized = self.normalizer.normalize(raw_event)
+            full_event = normalized.to_dict()
+            
             # Attempt broadcast
             if event.skip_sid:
                 await self.sio.emit("claude_event", full_event, skip_sid=event.skip_sid)
@@ -309,16 +317,22 @@ class SocketIOEventBroadcaster:
         """Broadcast an event to all connected clients with retry support.
         
         WHY: Enhanced with retry queue to ensure reliable delivery
-        even during transient network issues.
+        even during transient network issues. Now uses EventNormalizer
+        to ensure consistent event schema.
         """
         if not self.sio:
             return
 
-        event = {
+        # Create raw event for normalization
+        raw_event = {
             "type": event_type,
             "timestamp": datetime.now().isoformat(),
             "data": data,
         }
+        
+        # Normalize the event to consistent schema
+        normalized = self.normalizer.normalize(raw_event)
+        event = normalized.to_dict()
 
         # Buffer the event for reliability AND add to event history for new clients
         with self.buffer_lock:
@@ -329,7 +343,7 @@ class SocketIOEventBroadcaster:
             # Access through server reference to maintain single history source
             if hasattr(self, 'server') and hasattr(self.server, 'event_history'):
                 self.server.event_history.append(event)
-                self.logger.debug(f"Added {event_type} to history (total: {len(self.server.event_history)})")
+                self.logger.debug(f"Added {event['type']}/{event['subtype']} to history (total: {len(self.server.event_history)})")
 
         # Broadcast to all connected clients
         broadcast_success = False
@@ -521,29 +535,8 @@ class SocketIOEventBroadcaster:
         
         WHY: System events are separate from hook events to provide
         server health monitoring independent of Claude activity.
+        Now uses broadcast_event for consistency with buffering and normalization.
         """
-        if not self.sio:
-            return
-            
-        # Create system event with consistent format
-        event = {
-            "type": "system",
-            "event": "heartbeat",
-            "timestamp": datetime.now().isoformat(),
-            "data": heartbeat_data,
-        }
-        
-        # Broadcast to all connected clients
-        try:
-            if self.loop and not self.loop.is_closed():
-                future = asyncio.run_coroutine_threadsafe(
-                    self.sio.emit("system_event", event), self.loop
-                )
-                self.logger.debug(
-                    f"Broadcasted system heartbeat - clients: {len(self.connected_clients)}, "
-                    f"uptime: {heartbeat_data.get('uptime_seconds', 0)}s"
-                )
-            else:
-                self.logger.warning("Cannot broadcast heartbeat: server loop not available")
-        except Exception as e:
-            self.logger.error(f"Failed to broadcast system heartbeat: {e}")
+        # Use the standard broadcast_event method which handles normalization,
+        # buffering, and retry logic
+        self.broadcast_event("heartbeat", heartbeat_data)

claude_mpm/services/socketio/server/core.py

@@ -414,11 +414,12 @@ class SocketIOServerCore:
                     except Exception as e:
                         self.logger.debug(f"Could not get active sessions: {e}")
                 
-                # Prepare heartbeat data
+                # Prepare heartbeat data (using new schema)
                 heartbeat_data = {
                     "type": "system",
-                    "event": "heartbeat",
+                    "subtype": "heartbeat",
                     "timestamp": datetime.now().isoformat(),
+                    "source": "server",
                     "data": {
                         "uptime_seconds": uptime_seconds,
                         "connected_clients": len(self.connected_clients),
@@ -435,7 +436,7 @@ class SocketIOServerCore:
                 if self.main_server and hasattr(self.main_server, 'event_history'):
                     self.main_server.event_history.append(heartbeat_data)
                 
-                # Emit heartbeat to all connected clients
+                # Emit heartbeat to all connected clients (already using new schema)
                 await self.sio.emit("system_event", heartbeat_data)
                 
                 self.logger.info(