claude-mpm 4.1.6__tar.gz → 4.1.7__tar.gz

claude_mpm-4.1.7/BUILD_NUMBER

@@ -0,0 +1 @@
+304

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.1.6
+Version: 4.1.7
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team

claude_mpm-4.1.7/VERSION

@@ -0,0 +1 @@
+4.1.7

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.1.6"
+version = "4.1.7"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -244,7 +244,7 @@ ignore-imports = false
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.1.6"
+version = "4.1.7"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.1.7/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.1.7

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/agents/templates/agent-manager.json

@@ -6,7 +6,7 @@
   "tool_choice": "auto",
   "metadata": {
     "description": "Manages agent creation, customization, deployment, and PM instruction configuration",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "capabilities": [
       "agent-creation",
       "variant-management",

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/agents/templates/agent-manager.md

@@ -8,30 +8,72 @@ You are the Agent Manager, responsible for creating, customizing, deploying, and
 
 ## Agent Hierarchy Understanding
 
-You operate within a three-tier agent hierarchy with clear precedence:
+You operate within a three-source agent hierarchy with VERSION-BASED precedence:
 
-1. **Project Level** (`.claude/agents/`) - Highest priority
-   - Project-specific agents that override all others
-   - Deployed per-project for custom workflows
+1. **Project Level** (`.claude/agents/`) - Project-specific deployment
+   - Project-specific agents for custom workflows
+   - Deployed per-project for team collaboration
    - Persists with project repository
 
-2. **User Level** (`~/.claude/agents/`) - Middle priority
+2. **User Level** (`~/.claude/agents/`) - User's personal deployment
    - User's personal agent collection
    - Shared across all projects for that user
-   - Overrides system agents but not project agents
+   - Personal customizations and preferences
 
-3. **System Level** (Framework installation) - Lowest priority
+3. **System Level** (`/src/claude_mpm/agents/templates/`) - Framework built-in
    - Default agents shipped with claude-mpm
    - Available to all users and projects
-   - Can be overridden at user or project level
+   - Base templates and standard agents
 
-## PM Instructions Hierarchy
+**IMPORTANT: VERSION-BASED PRECEDENCE**
+- The agent with the HIGHEST semantic version wins, regardless of source
+- Example: Project agent v1.0.0 < User agent v2.0.0 < System agent v3.0.0
+- Development agents use version 999.x.x to always override production versions
+- MultiSourceAgentDeploymentService handles version resolution
 
-You also manage PM (Project Manager) instruction files:
+## PM Instructions Customization System
 
-1. **User CLAUDE.md** (`~/.claude/CLAUDE.md`) - User's global PM instructions
-2. **Project CLAUDE.md** (`<project>/CLAUDE.md`) - Project-specific PM instructions
-3. **Framework Instructions** (`BASE_PM.md`, `INSTRUCTIONS.md`) - Default PM behavior
+You manage a comprehensive PM (Project Manager) customization system:
+
+### Instruction Loading Order (Highest to Lowest Priority)
+
+1. **Project Instructions** (`./.claude-mpm/`) - Project-specific PM behavior
+   - `INSTRUCTIONS.md` - Main PM instructions
+   - `WORKFLOW.md` - Custom workflow patterns
+   - `MEMORY.md` - Memory system configuration
+   - `OUTPUT_STYLE.md` - Response formatting preferences
+   - Highest priority, overrides all others
+
+2. **User Instructions** (`~/.claude-mpm/`) - User's personal PM settings
+   - Same files as project level
+   - Applied across all user's projects
+   - Overrides system defaults
+
+3. **System Instructions** (Framework built-in) - Default PM behavior
+   - `BASE_PM.md` - Core PM framework
+   - `INSTRUCTIONS.md` - Default instructions
+   - Base behavior for all deployments
+
+### Configuration System
+
+Additionally manage configuration files:
+
+1. **Project Config** (`./.claude-mpm/configuration.yaml`)
+2. **User Config** (`~/.claude-mpm/configuration.yaml`)
+3. **System Config** (`/etc/claude-mpm/configuration.yaml`)
+
+Features configured:
+- Response logging settings
+- Agent exclusion lists
+- Memory system parameters
+- SocketIO server configuration
+- Performance tuning
+
+**IMPORTANT NOTES**:
+- CLAUDE.md files are NOT loaded by MPM (handled by Claude Code directly)
+- SystemInstructionsDeployer auto-deploys PM instructions on first run
+- FrameworkLoader orchestrates all customization loading
+- Template variable {{CAPABILITIES}} is dynamically replaced with agent list
 
 ## Core Responsibilities
 
@@ -61,10 +103,13 @@ You also manage PM (Project Manager) instruction files:
 - Clean deployment of obsolete agents
 
 ### 5. PM Instruction Management
-- Create and edit CLAUDE.md files
-- Customize delegation patterns
-- Modify workflow sequences
-- Configure PM behavior at user/project level
+- Create and edit INSTRUCTIONS.md files at project/user levels
+- Customize WORKFLOW.md for delegation patterns
+- Configure MEMORY.md for memory system behavior
+- Manage OUTPUT_STYLE.md for response formatting
+- Edit configuration.yaml for system settings
+- Deploy instruction templates with SystemInstructionsDeployer
+- Note: CLAUDE.md is for Claude Code, not MPM
 
 ### 6. Discovery & Listing
 - List all available agents across tiers
@@ -111,11 +156,17 @@ You also manage PM (Project Manager) instruction files:
 
 ### `customize-pm` - Edit PM Instructions
 ```python
-# Edit CLAUDE.md at user or project level
-# Provide template if creating new
-# Validate markdown structure
+# Edit instruction files at user or project level:
+#   - INSTRUCTIONS.md (main PM behavior)
+#   - WORKFLOW.md (delegation patterns)
+#   - MEMORY.md (memory configuration)
+#   - OUTPUT_STYLE.md (response formatting)
+# Edit configuration.yaml for system settings
+# Provide templates if creating new
+# Validate file structure
 # Show diff of changes
 # Backup before modification
+# Note: CLAUDE.md is separate (for Claude Code)
 ```
 
 ### `show` - Display Agent Details
@@ -149,7 +200,7 @@ When creating agents, use this structure:
   "tool_choice": "auto|required|any",
   "metadata": {
     "description": "Agent purpose and capabilities",
-    "version": "1.0.0",
+    "version": "1.0.0",  // Semantic version - determines precedence!
     "capabilities": ["capability1", "capability2"],
     "tags": ["tag1", "tag2"],
     "author": "Creator Name",
@@ -158,6 +209,12 @@ When creating agents, use this structure:
 }
 ```
 
+### Version Guidelines
+- Production versions: Use standard semantic versioning (1.0.0, 1.1.0, 2.0.0)
+- Development versions: Use 999.x.x to override all other versions
+- Version determines precedence across ALL sources (project/user/system)
+- Higher version always wins regardless of deployment location
+
 ## Validation Rules
 
 ### Agent ID Validation
@@ -218,9 +275,12 @@ When creating agents, use this structure:
 
 ### PM Customization
 - Keep instructions focused and clear
-- Document custom workflows
-- Test delegation patterns
-- Version control CLAUDE.md files
+- Use INSTRUCTIONS.md for main behavior (not CLAUDE.md)
+- Document workflows in WORKFLOW.md
+- Configure memory in MEMORY.md
+- Set output style in OUTPUT_STYLE.md
+- Test delegation patterns thoroughly
+- Version control all .claude-mpm/ files
 
 ### Deployment Strategy
 - Start with user level for testing
@@ -237,16 +297,31 @@ When creating agents, use this structure:
 - Integrate with discovery service
 
 ### With MultiSourceAgentDeploymentService
-- Handle multi-tier deployments
-- Manage source precedence
-- Coordinate cross-tier operations
-- Track deployment sources
+- Handle multi-source deployments
+- Manage VERSION-BASED precedence (highest version wins)
+- Coordinate cross-source operations
+- Track deployment sources and versions
+- Resolve agent conflicts by semantic version
+- Support development versions (999.x.x)
 
 ### With Agent Discovery
-- Register new agents
-- Update agent registry
-- Refresh discovery cache
-- Notify of changes
+- Register new agents with version tracking
+- Update agent registry with version resolution
+- Refresh discovery cache after deployments
+- Notify of version conflicts or overrides
+- Display effective agent (highest version)
+
+### With SystemInstructionsDeployer
+- Auto-deploy PM instructions on first run
+- Create .claude-mpm directories as needed
+- Deploy instruction templates
+- Handle user/project customization
+
+### With FrameworkLoader
+- Load PM instructions in priority order
+- Process {{CAPABILITIES}} template variable
+- Merge instruction files appropriately
+- Handle configuration loading
 
 ## Memory Considerations
 
@@ -285,8 +360,10 @@ Brief description of action taken
 ### Agent Information (if relevant)
 - ID: agent-id
 - Location: [P/U/S] /path/to/agent
-- Version: 1.0.0
-- Overrides: [list if any]
+- Version: 1.0.0 (determines precedence)
+- Effective Source: [Project/User/System] based on version
+- Overridden Versions: [list lower versions if any]
+- Development Mode: Yes/No (if version 999.x.x)
 ```
 
 ## Security Considerations

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/config/socketio_config.py

@@ -10,6 +10,8 @@ WHY configuration management:
 - Supports multiple deployment scenarios (local, PyPI, Docker, etc.)
 - Provides environment-specific defaults
 - Allows runtime configuration overrides
+
+CRITICAL: Ping/pong settings MUST match between client and server to prevent disconnections!
 """
 
 import os
@@ -19,6 +21,33 @@ from typing import Any, Dict, List, Optional
 # Import constants for default values
 from claude_mpm.core.constants import NetworkConfig, RetryConfig, SystemLimits
 
+# Connection stability settings - MUST be consistent between client and server
+CONNECTION_CONFIG = {
+    # Ping/pong intervals (milliseconds for client, seconds for server)
+    'ping_interval_ms': 45000,     # 45 seconds (for client JavaScript)
+    'ping_interval': 45,            # 45 seconds (for server Python)
+    'ping_timeout_ms': 20000,       # 20 seconds (for client JavaScript)  
+    'ping_timeout': 20,             # 20 seconds (for server Python)
+    
+    # Connection management
+    'stale_timeout': 180,           # 3 minutes before considering connection stale
+    'health_check_interval': 30,    # Health check every 30 seconds
+    'event_ttl': 300,              # Keep events for 5 minutes for replay
+    
+    # Client reconnection settings
+    'reconnection_attempts': 5,     # Number of reconnection attempts
+    'reconnection_delay': 1000,     # Initial delay in ms
+    'reconnection_delay_max': 5000, # Maximum delay in ms
+    
+    # Feature flags
+    'enable_extra_heartbeat': False,  # Disable redundant heartbeats
+    'enable_health_monitoring': True,  # Enable connection health monitoring
+    
+    # Buffer settings
+    'max_events_buffer': 1000,      # Maximum events to buffer per client
+    'max_http_buffer_size': 1e8,    # 100MB max buffer for large payloads
+}
+
 
 @dataclass
 class SocketIOConfig:
@@ -29,11 +58,11 @@ class SocketIOConfig:
     port: int = NetworkConfig.DEFAULT_DASHBOARD_PORT
     server_id: Optional[str] = None
 
-    # Connection settings
+    # Connection settings - Use centralized config for consistency
     cors_allowed_origins: str = "*"  # Configure properly for production
-    ping_timeout: int = NetworkConfig.PING_TIMEOUT_STANDARD
-    ping_interval: int = NetworkConfig.PING_INTERVAL_STANDARD
-    max_http_buffer_size: int = 1000000
+    ping_timeout: int = CONNECTION_CONFIG['ping_timeout']  # 20 seconds
+    ping_interval: int = CONNECTION_CONFIG['ping_interval']  # 45 seconds
+    max_http_buffer_size: int = int(CONNECTION_CONFIG['max_http_buffer_size'])
 
     # Compatibility settings
     min_client_version: str = "0.7.0"

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/dashboard/static/js/socket-client.js

@@ -38,10 +38,10 @@ class SocketClient {
         this.eventQueue = [];
         this.maxQueueSize = 100;
         
-        // Retry configuration
+        // Retry configuration - Match server settings
         this.retryAttempts = 0;
-        this.maxRetryAttempts = 3;
-        this.retryDelays = [1000, 2000, 4000]; // Exponential backoff
+        this.maxRetryAttempts = 5;  // Increased from 3 to 5 for better stability
+        this.retryDelays = [1000, 2000, 3000, 4000, 5000]; // Exponential backoff with 5 attempts
         this.pendingEmissions = new Map(); // Track pending emissions for retry
         
         // Health monitoring
@@ -98,12 +98,12 @@ class SocketClient {
             reconnection: true,
             reconnectionDelay: 1000,
             reconnectionDelayMax: 5000,
-            reconnectionAttempts: Infinity,  // Keep trying indefinitely
-            timeout: 20000,  // Increase connection timeout
+            reconnectionAttempts: 5,  // Try 5 times then stop (was Infinity which can cause issues)
+            timeout: 20000,  // Connection timeout
             forceNew: true,
             transports: ['websocket', 'polling'],
-            pingInterval: 25000,  // Match server setting
-            pingTimeout: 60000    // Match server setting
+            pingInterval: 45000,  // CRITICAL: Must match server's 45 seconds
+            pingTimeout: 20000    // CRITICAL: Must match server's 20 seconds
         });
 
         this.setupSocketHandlers();
@@ -143,17 +143,22 @@ class SocketClient {
         });
 
         this.socket.on('disconnect', (reason) => {
-            console.log('Disconnected from server:', reason);
+            // Enhanced logging for debugging disconnection issues
+            const disconnectInfo = {
+                reason: reason,
+                timestamp: new Date().toISOString(),
+                wasConnected: this.isConnected,
+                uptimeSeconds: this.lastConnectTime ? ((Date.now() - this.lastConnectTime) / 1000).toFixed(1) : 0,
+                lastPing: this.lastPingTime ? ((Date.now() - this.lastPingTime) / 1000).toFixed(1) + 's ago' : 'never',
+                lastPong: this.lastPongTime ? ((Date.now() - this.lastPongTime) / 1000).toFixed(1) + 's ago' : 'never'
+            };
+            
+            console.log('Disconnected from server:', disconnectInfo);
+            
             this.isConnected = false;
             this.isConnecting = false;
             this.disconnectTime = Date.now();
             
-            // Calculate uptime
-            if (this.lastConnectTime) {
-                const uptime = (Date.now() - this.lastConnectTime) / 1000;
-                console.log(`Connection uptime was ${uptime.toFixed(1)}s`);
-            }
-            
             this.notifyConnectionStatus(`Disconnected: ${reason}`, 'disconnected');
 
             // Emit disconnect callback
@@ -161,8 +166,21 @@ class SocketClient {
                 callback(reason)
             );
             
-            // Start auto-reconnect if it was an unexpected disconnect
-            if (reason === 'transport close' || reason === 'ping timeout') {
+            // Detailed reason analysis for auto-reconnect decision
+            const reconnectReasons = [
+                'transport close',      // Network issue
+                'ping timeout',         // Server not responding
+                'transport error',      // Connection error
+                'io server disconnect', // Server initiated disconnect (might be restart)
+            ];
+            
+            if (reconnectReasons.includes(reason)) {
+                console.log(`Auto-reconnect triggered for reason: ${reason}`);
+                this.scheduleReconnect();
+            } else if (reason === 'io client disconnect') {
+                console.log('Client-initiated disconnect, not auto-reconnecting');
+            } else {
+                console.log(`Unknown disconnect reason: ${reason}, attempting reconnect anyway`);
                 this.scheduleReconnect();
             }
         });
@@ -222,6 +240,12 @@ class SocketClient {
             });
         });
         
+        // Track pong responses from server
+        this.socket.on('pong', (data) => {
+            this.lastPongTime = Date.now();
+            // console.log('Received pong from server');
+        });
+        
         // Session and event handlers (legacy/fallback)
         this.socket.on('session.started', (data) => {
             this.addEvent({ type: 'session', subtype: 'started', timestamp: new Date().toISOString(), data });

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -170,11 +170,28 @@ class ConnectionManagerService:
                 # Publish to EventBus with topic format: hook.{event}
                 topic = f"hook.{event}"
                 self.event_bus.publish(topic, claude_event_data)
+
+                # Enhanced verification logging
                 if DEBUG:
                     print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
+                    # Get EventBus stats to verify publication
+                    if hasattr(self.event_bus, "get_stats"):
+                        stats = self.event_bus.get_stats()
+                        print(
+                            f"📊 EventBus stats after publish: {stats}", file=sys.stderr
+                        )
+                    # Log the number of data keys being published
+                    if isinstance(claude_event_data, dict):
+                        print(
+                            f"📦 Published data keys: {list(claude_event_data.keys())}",
+                            file=sys.stderr,
+                        )
             except Exception as e:
                 if DEBUG:
                     print(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+                    import traceback
+
+                    traceback.print_exc(file=sys.stderr)
 
         # Warn if neither method is available
         if not self.connection_pool and not self.event_bus and DEBUG:

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/services/event_bus/direct_relay.py

@@ -59,9 +59,30 @@ class DirectSocketIORelay:
 
         # Add debug logging for verification
         logger.info("[DirectRelay] Subscribed to hook.* events on EventBus")
+
+        # Check and log broadcaster availability
+        broadcaster_available = (
+            self.server
+            and hasattr(self.server, "broadcaster")
+            and self.server.broadcaster is not None
+        )
         logger.info(
-            f"[DirectRelay] Server broadcaster available: {self.server and self.server.broadcaster is not None}"
+            f"[DirectRelay] Server broadcaster available: {broadcaster_available}"
         )
+        if not broadcaster_available:
+            if not self.server:
+                logger.warning(
+                    "[DirectRelay] No server instance provided - events will not be relayed!"
+                )
+            elif not hasattr(self.server, "broadcaster"):
+                logger.warning(
+                    "[DirectRelay] Server has no broadcaster attribute - events will not be relayed!"
+                )
+            else:
+                logger.warning(
+                    "[DirectRelay] Server broadcaster is None - events will not be relayed!"
+                )
+
         logger.info(f"[DirectRelay] EventBus instance: {self.event_bus is not None}")
 
         # Mark as connected after successful subscription
@@ -76,9 +97,28 @@ class DirectSocketIORelay:
             data: The event data
         """
         try:
-            # Log the event reception
+            # Enhanced debug logging for troubleshooting
             if self.debug:
                 logger.debug(f"[DirectRelay] Received event: {event_type}")
+                logger.debug(f"[DirectRelay] Event data type: {type(data).__name__}")
+                logger.debug(
+                    f"[DirectRelay] Event data keys: {list(data.keys()) if isinstance(data, dict) else 'not-dict'}"
+                )
+                logger.debug(
+                    f"[DirectRelay] Relay state - enabled: {self.enabled}, connected: {self.connected}"
+                )
+                logger.debug(
+                    f"[DirectRelay] Server state - has_server: {self.server is not None}, has_broadcaster: {self.server and hasattr(self.server, 'broadcaster') and self.server.broadcaster is not None}"
+                )
+
+            # Always log reception of important events
+            if event_type in [
+                "hook.pre_tool",
+                "hook.post_tool",
+                "hook.user_prompt",
+                "hook.subagent_stop",
+            ]:
+                logger.info(f"[DirectRelay] Processing important event: {event_type}")
 
             # Only relay hook events
             if event_type.startswith("hook."):
@@ -143,9 +183,26 @@ class DirectSocketIORelay:
                             f"[DirectRelay] Broadcasted hook event: {event_type}"
                         )
                 else:
+                    # Enhanced logging when broadcaster is not available
                     logger.warning(
                         f"[DirectRelay] Server broadcaster not available for {event_type}"
                     )
+                    if self.server:
+                        logger.warning(
+                            f"[DirectRelay] Server exists but broadcaster is None"
+                        )
+                        logger.warning(
+                            f"[DirectRelay] Server type: {type(self.server).__name__}"
+                        )
+                        logger.warning(
+                            f"[DirectRelay] Server has broadcaster attr: {hasattr(self.server, 'broadcaster')}"
+                        )
+                        if hasattr(self.server, "broadcaster"):
+                            logger.warning(
+                                f"[DirectRelay] Broadcaster value: {self.server.broadcaster}"
+                            )
+                    else:
+                        logger.warning(f"[DirectRelay] Server is None")
                     self.stats["events_failed"] += 1
 
         except Exception as e:

{claude_mpm-4.1.6 → claude_mpm-4.1.7}/src/claude_mpm/services/socketio/handlers/connection_handler.py

@@ -177,7 +177,7 @@ class EnhancedConnectionEventHandler(BaseEventHandler):
         async def ping(sid):
             """Handle ping from client for health monitoring."""
             try:
-                # Update activity in connection manager
+                # Update activity in connection manager - CRITICAL for preventing stale connections
                 if self.server.connection_manager:
                     await self.server.connection_manager.update_activity(sid, "ping")
 
@@ -293,23 +293,8 @@ class EnhancedConnectionEventHandler(BaseEventHandler):
             except Exception as e:
                 self.logger.error(f"Error getting connection stats for {sid}: {e}")
 
-        @sio.event
-        async def heartbeat(sid):
-            """Handle client heartbeat for connection monitoring."""
-            try:
-                # Update activity
-                if self.server.connection_manager:
-                    await self.server.connection_manager.update_activity(sid, "event")
-
-                # Send heartbeat response
-                await sio.emit(
-                    "heartbeat_response",
-                    {"timestamp": datetime.now().isoformat(), "status": "alive"},
-                    room=sid,
-                )
-
-            except Exception as e:
-                self.logger.error(f"Error handling heartbeat from {sid}: {e}")
+        # Heartbeat handler removed - Using Socket.IO's built-in ping/pong instead
+        # This prevents conflicting heartbeat systems that can cause disconnections
 
         self.logger.info("Enhanced connection event handlers registered")