claude-mpm 3.5.4__py3-none-any.whl → 3.6.0__py3-none-any.whl

claude_mpm/core/config.py

@@ -7,8 +7,10 @@ and default values with proper validation and type conversion.
 
 import os
 from pathlib import Path
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional, Union, List, Tuple
 import logging
+import yaml
+import json
 
 from ..utils.config_manager import ConfigurationManager
 from .config_paths import ConfigPaths
@@ -49,14 +51,25 @@ class Config:
         if config:
             self._config.update(config)
 
+        # Track where configuration was loaded from
+        self._loaded_from = None
+        
         # Load from file if provided
         if config_file:
             self.load_file(config_file)
+            self._loaded_from = str(config_file)
         else:
             # Try to load from standard location: .claude-mpm/configuration.yaml
             default_config = Path.cwd() / ".claude-mpm" / "configuration.yaml"
             if default_config.exists():
                 self.load_file(default_config)
+                self._loaded_from = str(default_config)
+            else:
+                # Also try .yml extension
+                alt_config = Path.cwd() / ".claude-mpm" / "configuration.yml"
+                if alt_config.exists():
+                    self.load_file(alt_config)
+                    self._loaded_from = str(alt_config)
 
         # Load from environment variables (new and legacy prefixes)
         self._load_env_vars()
@@ -66,21 +79,64 @@ class Config:
         self._apply_defaults()
 
     def load_file(self, file_path: Union[str, Path]) -> None:
-        """Load configuration from file."""
+        """Load configuration from file with enhanced error handling.
+        
+        WHY: Configuration loading failures can cause silent issues. We need
+        to provide clear, actionable error messages to help users fix problems.
+        """
         file_path = Path(file_path)
 
         if not file_path.exists():
             logger.warning(f"Configuration file not found: {file_path}")
+            logger.info(f"TIP: Create a configuration file with: mkdir -p {file_path.parent} && touch {file_path}")
             return
 
         try:
+            # Check if file is readable
+            if not os.access(file_path, os.R_OK):
+                logger.error(f"Configuration file is not readable: {file_path}")
+                logger.info(f"TIP: Fix permissions with: chmod 644 {file_path}")
+                return
+                
+            # Check file size (warn if too large)
+            file_size = file_path.stat().st_size
+            if file_size > 1024 * 1024:  # 1MB
+                logger.warning(f"Configuration file is large ({file_size} bytes): {file_path}")
+                
+            # Try to load the configuration
             file_config = self._config_mgr.load_auto(file_path)
             if file_config:
                 self._config = self._config_mgr.merge_configs(self._config, file_config)
-                logger.info(f"Loaded configuration from {file_path}")
-
+                logger.info(f"✓ Successfully loaded configuration from {file_path}")
+                
+                # Log important configuration values for debugging
+                if logger.isEnabledFor(logging.DEBUG):
+                    response_logging = file_config.get('response_logging', {})
+                    if response_logging:
+                        logger.debug(f"Response logging enabled: {response_logging.get('enabled', False)}")
+                        logger.debug(f"Response logging format: {response_logging.get('format', 'json')}")
+
+        except yaml.YAMLError as e:
+            logger.error(f"YAML syntax error in {file_path}: {e}")
+            if hasattr(e, 'problem_mark'):
+                mark = e.problem_mark
+                logger.error(f"Error at line {mark.line + 1}, column {mark.column + 1}")
+            logger.info("TIP: Validate your YAML at https://www.yamllint.com/ or run: python scripts/validate_configuration.py")
+            logger.info("TIP: Common issue - YAML requires spaces, not tabs. Fix with: sed -i '' 's/\t/    /g' " + str(file_path))
+            # Store error for later retrieval
+            self._config['_load_error'] = str(e)
+            
+        except json.JSONDecodeError as e:
+            logger.error(f"JSON syntax error in {file_path}: {e}")
+            logger.error(f"Error at line {e.lineno}, column {e.colno}")
+            logger.info("TIP: Validate your JSON at https://jsonlint.com/")
+            self._config['_load_error'] = str(e)
+            
         except Exception as e:
             logger.error(f"Failed to load configuration from {file_path}: {e}")
+            logger.info("TIP: Check file permissions and format (YAML/JSON)")
+            logger.info("TIP: Run validation with: python scripts/validate_configuration.py")
+            self._config['_load_error'] = str(e)
 
     def _load_env_vars(self) -> None:
         """Load configuration from environment variables."""
@@ -323,6 +379,12 @@ class Config:
                         "emergency_stop": True
                     }
                 }
+            },
+            # Agent deployment configuration
+            "agent_deployment": {
+                "excluded_agents": [],              # List of agent IDs to exclude from deployment
+                "exclude_dependencies": False,      # Whether to exclude agent dependencies too
+                "case_sensitive": False            # Whether agent name matching is case-sensitive
             }
         }
 
@@ -515,6 +577,101 @@ class Config:
         
         return base_config
 
+    def validate_configuration(self) -> Tuple[bool, List[str], List[str]]:
+        """Validate the loaded configuration programmatically.
+        
+        WHY: Provide a programmatic way to validate configuration that can be
+        used by other components to check configuration health.
+        
+        Returns:
+            Tuple of (is_valid, errors, warnings)
+        """
+        errors = []
+        warnings = []
+        
+        # Check if there was a load error
+        if '_load_error' in self._config:
+            errors.append(f"Configuration load error: {self._config['_load_error']}")
+            
+        # Validate response_logging configuration
+        response_logging = self.get('response_logging', {})
+        if response_logging:
+            # Check enabled field
+            if 'enabled' in response_logging and not isinstance(response_logging['enabled'], bool):
+                errors.append(
+                    f"response_logging.enabled must be boolean, got {type(response_logging['enabled']).__name__}"
+                )
+                
+            # Check format field
+            if 'format' in response_logging:
+                valid_formats = ['json', 'syslog', 'journald']
+                if response_logging['format'] not in valid_formats:
+                    errors.append(
+                        f"response_logging.format must be one of {valid_formats}, "
+                        f"got '{response_logging['format']}'"
+                    )
+                    
+            # Check session_directory
+            if 'session_directory' in response_logging:
+                session_dir = Path(response_logging['session_directory'])
+                if session_dir.is_absolute() and not session_dir.parent.exists():
+                    warnings.append(
+                        f"Parent directory for session_directory does not exist: {session_dir.parent}"
+                    )
+                    
+        # Validate memory configuration
+        memory_config = self.get('memory', {})
+        if memory_config:
+            if 'enabled' in memory_config and not isinstance(memory_config['enabled'], bool):
+                errors.append(f"memory.enabled must be boolean")
+                
+            # Check limits
+            limits = memory_config.get('limits', {})
+            for field in ['default_size_kb', 'max_sections', 'max_items_per_section']:
+                if field in limits:
+                    value = limits[field]
+                    if not isinstance(value, int) or value <= 0:
+                        errors.append(f"memory.limits.{field} must be positive integer, got {value}")
+                        
+        # Validate health thresholds
+        health_thresholds = self.get('health_thresholds', {})
+        if health_thresholds:
+            cpu = health_thresholds.get('cpu_percent')
+            if cpu is not None and (not isinstance(cpu, (int, float)) or cpu < 0 or cpu > 100):
+                errors.append(f"health_thresholds.cpu_percent must be 0-100, got {cpu}")
+                
+            mem = health_thresholds.get('memory_mb')
+            if mem is not None and (not isinstance(mem, (int, float)) or mem <= 0):
+                errors.append(f"health_thresholds.memory_mb must be positive, got {mem}")
+                
+        is_valid = len(errors) == 0
+        return is_valid, errors, warnings
+        
+    def get_configuration_status(self) -> Dict[str, Any]:
+        """Get detailed configuration status for debugging.
+        
+        WHY: Provide a comprehensive view of configuration state for
+        troubleshooting and health checks.
+        
+        Returns:
+            Dictionary with configuration status information
+        """
+        is_valid, errors, warnings = self.validate_configuration()
+        
+        status = {
+            'valid': is_valid,
+            'errors': errors,
+            'warnings': warnings,
+            'loaded_from': getattr(self, '_loaded_from', 'defaults'),
+            'key_count': len(self._config),
+            'has_response_logging': 'response_logging' in self._config,
+            'has_memory_config': 'memory' in self._config,
+            'response_logging_enabled': self.get('response_logging.enabled', False),
+            'memory_enabled': self.get('memory.enabled', False)
+        }
+        
+        return status
+
     def __repr__(self) -> str:
         """String representation of configuration."""
         return f"<Config({len(self._config)} keys)>"

claude_mpm/core/config_paths.py

@@ -35,7 +35,6 @@ class ConfigPaths:
     RESPONSES_DIR = "responses"
     
     # Agent subdirectories
-    AGENT_PROJECT_SPECIFIC = "project-specific"
     AGENT_USER_AGENTS = "user-agents"
     AGENT_USER_DEFINED = "user-defined"
     AGENT_SYSTEM = "templates"

claude_mpm/core/factories.py

@@ -57,14 +57,20 @@ class AgentServiceFactory(ServiceFactory):
         config = container.resolve(Config)
         
         # Get directories from config if not provided
+        import os
+        
         if framework_dir is None:
             framework_dir = Path(config.get('framework.dir', 'framework'))
             
         if project_dir is None:
-            project_dir = Path(config.get('project.dir', '.'))
+            # Check for user working directory from environment
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path(config.get('project.dir', '.'))
             
-        # Create service with dependencies
-        service = AgentDeploymentService()
+        # Create service with proper working directory
+        service = AgentDeploymentService(working_directory=project_dir)
         
         # Inject any required dependencies
         if hasattr(service, 'set_directories'):

claude_mpm/core/framework_loader.py

@@ -274,6 +274,13 @@ class FrameworkLoader:
                 if self.framework_last_modified:
                     content["instructions_last_modified"] = self.framework_last_modified
         
+        # Load BASE_PM.md for core framework requirements
+        base_pm_path = self.framework_path / "src" / "claude_mpm" / "agents" / "BASE_PM.md"
+        if base_pm_path.exists():
+            base_pm_content = self._try_load_file(base_pm_path, "BASE_PM framework requirements")
+            if base_pm_content:
+                content["base_pm_instructions"] = base_pm_content
+        
         # Discover agent directories
         agents_dir, templates_dir, main_dir = self._discover_framework_paths()
         
@@ -308,6 +315,17 @@ class FrameworkLoader:
             if self.framework_content["working_claude_md"]:
                 instructions += f"\n\n## Working Directory Instructions\n{self.framework_content['working_claude_md']}\n"
             
+            # Add dynamic agent capabilities section
+            instructions += self._generate_agent_capabilities_section()
+            
+            # Add current date for temporal awareness
+            instructions += f"\n\n## Temporal Context\n**Today's Date**: {datetime.now().strftime('%Y-%m-%d')}\n"
+            instructions += "Apply date awareness to all time-sensitive tasks and decisions.\n"
+            
+            # Add BASE_PM.md framework requirements AFTER INSTRUCTIONS.md
+            if self.framework_content.get("base_pm_instructions"):
+                instructions += f"\n\n{self.framework_content['base_pm_instructions']}\n"
+            
             return instructions
         
         # Otherwise fall back to generating framework
@@ -413,6 +431,69 @@ Extract tickets from these patterns:
         
         return instructions
     
+    def _generate_agent_capabilities_section(self) -> str:
+        """Generate dynamic agent capabilities section from deployed agents."""
+        try:
+            # Try to get agents from agent_loader
+            from claude_mpm.agents.agent_loader import list_available_agents
+            agents = list_available_agents()
+            
+            if not agents:
+                return ""
+            
+            # Build capabilities section
+            section = "\n\n## Available Agent Capabilities\n\n"
+            section += "You have the following specialized agents available for delegation:\n\n"
+            
+            # Group agents by category
+            categories = {}
+            for agent_id, info in agents.items():
+                category = info.get('category', 'general')
+                if category not in categories:
+                    categories[category] = []
+                categories[category].append((agent_id, info))
+            
+            # List agents by category
+            for category in sorted(categories.keys()):
+                section += f"\n### {category.title()} Agents\n"
+                for agent_id, info in sorted(categories[category]):
+                    name = info.get('name', agent_id)
+                    desc = info.get('description', 'Specialized agent')
+                    tools = info.get('tools', [])
+                    section += f"- **{name}** (`{agent_id}`): {desc}\n"
+                    if tools:
+                        section += f"  - Tools: {', '.join(tools[:5])}"
+                        if len(tools) > 5:
+                            section += f" (+{len(tools)-5} more)"
+                        section += "\n"
+            
+            # Add summary
+            section += f"\n**Total Available Agents**: {len(agents)}\n"
+            section += "Use the agent ID in parentheses when delegating tasks via the Task tool.\n"
+            
+            return section
+            
+        except Exception as e:
+            self.logger.warning(f"Could not generate dynamic agent capabilities: {e}")
+            # Return static fallback
+            return """
+
+## Available Agent Capabilities
+
+You have the following specialized agents available for delegation:
+
+- **Engineer Agent**: Code implementation and development
+- **Research Agent**: Investigation and analysis
+- **QA Agent**: Testing and quality assurance
+- **Documentation Agent**: Documentation creation and maintenance
+- **Security Agent**: Security analysis and protection
+- **Data Engineer Agent**: Data management and pipelines
+- **Ops Agent**: Deployment and operations
+- **Version Control Agent**: Git operations and version management
+
+Use these agents to delegate specialized work via the Task tool.
+"""
+    
     def _format_minimal_framework(self) -> str:
         """Format minimal framework instructions when full framework not available."""
         return """

claude_mpm/dashboard/.claude-mpm/memories/README.md

@@ -0,0 +1,36 @@
+# Agent Memory System
+
+## Purpose
+Each agent maintains project-specific knowledge in these files. Agents read their memory file before tasks and update it when they learn something new.
+
+## Manual Editing
+Feel free to edit these files to:
+- Add project-specific guidelines
+- Remove outdated information  
+- Reorganize for better clarity
+- Add domain-specific knowledge
+
+## Memory Limits
+- Max file size: 8KB (~2000 tokens)
+- Max sections: 10
+- Max items per section: 15
+- Files auto-truncate when limits exceeded
+
+## File Format
+Standard markdown with structured sections. Agents expect:
+- Project Architecture
+- Implementation Guidelines
+- Common Mistakes to Avoid
+- Current Technical Context
+
+## How It Works
+1. Agents read their memory file before starting tasks
+2. Agents add learnings during or after task completion
+3. Files automatically enforce size limits
+4. Developers can manually edit for accuracy
+
+## Memory File Lifecycle
+- Created automatically when agent first runs
+- Updated through hook system after delegations
+- Manually editable by developers
+- Version controlled with project

claude_mpm/dashboard/README.md

@@ -0,0 +1,121 @@
+# Claude MPM Web Dashboard
+
+This directory contains the modular web dashboard for Claude MPM monitoring and management.
+
+## Structure
+
+```
+src/claude_mpm/dashboard/
+├── static/
+│   ├── css/
+│   │   └── dashboard.css          # Main stylesheet
+│   └── js/
+│       ├── socket-client.js       # Socket.IO connection management
+│       ├── dashboard.js          # Main dashboard application
+│       └── components/
+│           ├── event-viewer.js    # Event display and filtering
+│           ├── module-viewer.js   # Event detail viewer
+│           └── session-manager.js # Session management
+├── templates/
+│   └── index.html               # Main dashboard HTML
+├── index.html                   # Root index with redirect
+├── test_dashboard.html          # Test version for verification
+└── README.md                    # This file
+```
+
+## Components
+
+### SocketClient (`socket-client.js`)
+- Manages WebSocket connections to the Claude MPM server
+- Handles event reception and processing
+- Provides callbacks for connection state changes
+- Maintains event history and session tracking
+
+### EventViewer (`components/event-viewer.js`)
+- Displays events in a filterable list
+- Supports search, type filtering, and session filtering
+- Handles event selection and keyboard navigation
+- Updates metrics display (total events, events per minute, etc.)
+
+### ModuleViewer (`components/module-viewer.js`)
+- Shows detailed information about selected events
+- Provides structured views for different event types
+- Displays raw JSON data for debugging
+- Organizes events by class/category
+
+### SessionManager (`components/session-manager.js`)
+- Manages session selection and filtering
+- Updates session dropdown with available sessions
+- Tracks current active session
+- Updates footer information
+
+### Dashboard (`dashboard.js`)
+- Main application coordinator
+- Handles tab switching between Events, Agents, Tools, and Files
+- Manages component interactions
+- Provides global functions for backward compatibility
+
+## Features
+
+### File-Centric Files Tab
+The Files tab now shows a file-centric view where:
+- Each file appears only once in the list
+- Files show read/write icons based on operations performed
+- Most recently accessed files appear at the bottom
+- Clicking a file shows all operations performed on it with timestamps and agent information
+
+### Tab Organization
+- **Events**: All events with filtering and search
+- **Agents**: Agent-specific events and operations
+- **Tools**: Tool usage and parameters
+- **Files**: File operations organized by file path
+
+### Enhanced Event Details
+- Structured views for different event types
+- Todo checklists with status indicators
+- Agent and tool information
+- Session tracking and filtering
+
+## Usage
+
+### Development
+For development and testing, use `test_dashboard.html` which includes module verification.
+
+### Production
+Use `templates/dashboard.html` as the main template, ensuring all static files are served correctly.
+
+### Integration
+The dashboard can be integrated into a Flask/FastAPI application by serving the static files and using the template.
+
+## Migration from Original
+
+The original monolithic `claude_mpm_socketio_dashboard.html` has been replaced with a modular structure:
+
+1. **CSS**: Extracted to `static/css/dashboard.css`
+2. **JavaScript**: Split into logical modules in `static/js/`
+3. **HTML**: Clean template in `templates/dashboard.html`
+
+All original functionality has been preserved while improving:
+- Code organization and maintainability
+- Module reusability
+- Easier debugging and development
+- Better separation of concerns
+
+## Backward Compatibility
+
+Global functions are maintained for compatibility:
+- `connectSocket()`
+- `disconnectSocket()`
+- `clearEvents()`
+- `exportEvents()`
+- `clearSelection()`
+- `switchTab(tabName)`
+
+## Browser Support
+
+Requires modern browsers with support for:
+- ES6 Classes
+- Fetch API
+- Custom Events
+- CSS Grid/Flexbox
+- Socket.IO 4.x