claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/validation/frontmatter_validator.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 """
 Claude Code Frontmatter Validator
 
@@ -6,216 +8,235 @@ Critical for ensuring agents work correctly with Claude Desktop.
 """
 
 import re
-from pathlib import Path
 from typing import Dict, List, Optional, Tuple
+
 import yaml
 
 
 class FrontmatterValidator:
     """Validates agent frontmatter against Claude Code specification."""
-    
+
     # Claude Code name pattern: lowercase letters, numbers, hyphens only
     # NO UNDERSCORES, NO UPPERCASE, NO SPECIAL CHARACTERS
-    NAME_PATTERN = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
-    
+    NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
     # Valid tool names (from Claude Code spec)
     VALID_TOOLS = {
-        'Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Grep', 'Glob', 'LS',
-        'WebSearch', 'WebFetch', 'TodoWrite', 'BashOutput', 'KillBash',
-        'NotebookEdit', 'Task', 'ExitPlanMode'
+        "Read",
+        "Write",
+        "Edit",
+        "MultiEdit",
+        "Bash",
+        "Grep",
+        "Glob",
+        "LS",
+        "WebSearch",
+        "WebFetch",
+        "TodoWrite",
+        "BashOutput",
+        "KillBash",
+        "NotebookEdit",
+        "Task",
+        "ExitPlanMode",
     }
-    
+
     # Valid model tiers
-    VALID_MODELS = {'opus', 'sonnet', 'haiku'}
-    
+    VALID_MODELS = {"opus", "sonnet", "haiku"}
+
     # Required fields in frontmatter
-    REQUIRED_FIELDS = {'name', 'description', 'tools'}
-    
+    REQUIRED_FIELDS = {"name", "description", "tools"}
+
     @classmethod
     def validate_name(cls, name: str) -> Tuple[bool, Optional[str]]:
         """
         Validate agent name field against Claude Code spec.
-        
+
         Args:
             name: Agent name to validate
-            
+
         Returns:
             (is_valid, error_message)
         """
         if not name:
             return False, "Name field is required"
-        
+
         if not cls.NAME_PATTERN.match(name):
             return False, (
                 f"Invalid name '{name}'. Must match pattern ^[a-z0-9]+(-[a-z0-9]+)*$ "
                 "(lowercase letters, numbers, and hyphens only - NO underscores!)"
             )
-        
+
         if len(name) > 50:
             return False, f"Name '{name}' too long (max 50 characters)"
-        
+
         return True, None
-    
+
     @classmethod
     def validate_tools(cls, tools: str) -> Tuple[bool, Optional[str]]:
         """
         Validate tools field format and content.
-        
+
         CRITICAL: Tools must be comma-separated WITHOUT spaces!
-        
+
         Args:
             tools: Tools string to validate
-            
+
         Returns:
             (is_valid, error_message)
         """
         if not tools:
             return False, "Tools field is required"
-        
+
         # Check for spaces after commas (CRITICAL ERROR)
-        if ', ' in tools:
+        if ", " in tools:
             return False, (
                 f"CRITICAL: Tools contain spaces after commas! '{tools}' "
                 "Must be comma-separated WITHOUT spaces (e.g., 'Read,Write,Edit')"
             )
-        
+
         # Validate individual tools
-        tool_list = tools.split(',')
+        tool_list = tools.split(",")
         invalid_tools = [t for t in tool_list if t not in cls.VALID_TOOLS]
-        
+
         if invalid_tools:
-            return False, f"Invalid tools: {', '.join(invalid_tools)}. Valid tools: {', '.join(sorted(cls.VALID_TOOLS))}"
-        
+            return (
+                False,
+                f"Invalid tools: {', '.join(invalid_tools)}. Valid tools: {', '.join(sorted(cls.VALID_TOOLS))}",
+            )
+
         return True, None
-    
+
     @classmethod
     def validate_model(cls, model: str) -> Tuple[bool, Optional[str]]:
         """
         Validate model field.
-        
+
         Args:
             model: Model tier to validate
-            
+
         Returns:
             (is_valid, error_message)
         """
         if model and model not in cls.VALID_MODELS:
-            return False, f"Invalid model '{model}'. Must be one of: {', '.join(cls.VALID_MODELS)}"
-        
+            return (
+                False,
+                f"Invalid model '{model}'. Must be one of: {', '.join(cls.VALID_MODELS)}",
+            )
+
         return True, None
-    
+
     @classmethod
     def validate_frontmatter(cls, frontmatter: Dict) -> List[str]:
         """
         Validate complete frontmatter structure.
-        
+
         Args:
             frontmatter: Parsed frontmatter dictionary
-            
+
         Returns:
             List of validation errors (empty if valid)
         """
         errors = []
-        
+
         # Check required fields
         missing = cls.REQUIRED_FIELDS - set(frontmatter.keys())
         if missing:
             errors.append(f"Missing required fields: {', '.join(missing)}")
-        
+
         # Validate name
-        if 'name' in frontmatter:
-            valid, error = cls.validate_name(frontmatter['name'])
+        if "name" in frontmatter:
+            valid, error = cls.validate_name(frontmatter["name"])
             if not valid:
                 errors.append(error)
-        
+
         # Validate tools
-        if 'tools' in frontmatter:
-            valid, error = cls.validate_tools(frontmatter['tools'])
+        if "tools" in frontmatter:
+            valid, error = cls.validate_tools(frontmatter["tools"])
             if not valid:
                 errors.append(error)
-        
+
         # Validate model
-        if 'model' in frontmatter:
-            valid, error = cls.validate_model(frontmatter['model'])
+        if "model" in frontmatter:
+            valid, error = cls.validate_model(frontmatter["model"])
             if not valid:
                 errors.append(error)
-        
+
         # Validate description
-        if 'description' in frontmatter:
-            desc = frontmatter['description']
+        if "description" in frontmatter:
+            desc = frontmatter["description"]
             if len(desc) < 10:
                 errors.append(f"Description too short ({len(desc)} chars, min 10)")
             if len(desc) > 200:
                 errors.append(f"Description too long ({len(desc)} chars, max 200)")
-        
+
         return errors
-    
+
     @classmethod
     def validate_agent_file(cls, file_path: Path) -> List[str]:
         """
         Validate an agent markdown file.
-        
+
         Args:
             file_path: Path to agent .md file
-            
+
         Returns:
             List of validation errors (empty if valid)
         """
         errors = []
-        
+
         try:
-            with open(file_path, 'r') as f:
+            with open(file_path, "r") as f:
                 content = f.read()
-            
+
             # Check for frontmatter markers
-            if not content.startswith('---\n'):
+            if not content.startswith("---\n"):
                 errors.append("File must start with '---' frontmatter marker")
                 return errors
-            
+
             # Extract frontmatter
-            end_marker = content.find('\n---\n', 4)
+            end_marker = content.find("\n---\n", 4)
             if end_marker == -1:
                 errors.append("Missing closing '---' frontmatter marker")
                 return errors
-            
+
             frontmatter_text = content[4:end_marker]
-            
+
             # Parse YAML
             try:
                 frontmatter = yaml.safe_load(frontmatter_text)
             except yaml.YAMLError as e:
                 errors.append(f"Invalid YAML in frontmatter: {e}")
                 return errors
-            
+
             # Validate frontmatter content
             validation_errors = cls.validate_frontmatter(frontmatter)
             errors.extend(validation_errors)
-            
+
         except Exception as e:
             errors.append(f"Error reading file: {e}")
-        
+
         return errors
 
 
 def main():
     """Command-line validation tool."""
     import sys
-    
+
     if len(sys.argv) < 2:
         print("Usage: python frontmatter_validator.py <agent.md> [agent2.md ...]")
         sys.exit(1)
-    
+
     all_valid = True
-    
+
     for file_path in sys.argv[1:]:
         path = Path(file_path)
         if not path.exists():
             print(f"❌ {file_path}: File not found")
             all_valid = False
             continue
-        
+
         errors = FrontmatterValidator.validate_agent_file(path)
-        
+
         if errors:
             print(f"❌ {file_path}:")
             for error in errors:
@@ -223,9 +244,9 @@ def main():
             all_valid = False
         else:
             print(f"✅ {file_path}: Valid")
-    
+
     sys.exit(0 if all_valid else 1)
 
 
 if __name__ == "__main__":
-    main()
+    main()

{claude_mpm-3.9.9.dist-info → claude_mpm-4.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.9.9
+Version: 4.0.3
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -38,6 +38,7 @@ Requires-Dist: python-frontmatter>=1.0.0
 Requires-Dist: mistune>=3.0.0
 Requires-Dist: aiofiles>=23.0.0
 Requires-Dist: mcp>=0.1.0
+Requires-Dist: ijson>=3.2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
@@ -45,6 +46,7 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
@@ -110,6 +112,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 - 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- 🛡️ **Memory Guardian (Experimental)**: Automatic memory monitoring and intelligent restarts to prevent crashes
 - 📁 **Multi-Project Support**: Per-session working directories
 - 🔍 **Git Integration**: View diffs and track changes across projects
 - 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
@@ -130,6 +133,9 @@ claude-mpm
 
 # Start with monitoring dashboard
 claude-mpm run --monitor
+
+# Start with memory protection (prevents crashes from large conversations)
+claude-mpm run-guarded
 ```
 
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
@@ -149,10 +155,25 @@ The PM agent automatically delegates work to specialized agents including Resear
 ### Agent Memory System
 Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
 
+### Memory Guardian System (Experimental)
+**⚠️ Beta Feature** - Prevents memory-related crashes through intelligent monitoring and automatic restarts with state preservation.
+
+```bash
+# Start with memory protection (recommended for long sessions)
+claude-mpm run-guarded --accept-experimental
+
+# Custom memory threshold for your system
+claude-mpm run-guarded --memory-threshold 16000 --accept-experimental  # 16GB
+```
+
+**Why Memory Guardian?** Large conversation histories can consume 2GB+ of memory, causing system instability. The Memory Guardian monitors memory usage and performs controlled restarts while preserving your conversation context and work progress.
+
+**Note:** This is an experimental feature in beta. Use `--accept-experimental` to suppress warnings.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 
-See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
+See [docs/MEMORY.md](docs/MEMORY.md), [docs/USER_GUIDE_MEMORY_GUARDIAN.md](docs/USER_GUIDE_MEMORY_GUARDIAN.md), and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
 ## Documentation
@@ -162,12 +183,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **[Installation Guide](docs/user/installation.md)** - Complete installation options
 - **[User Guide](docs/user/)** - Detailed usage documentation
 - **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Memory Guardian Guide](docs/USER_GUIDE_MEMORY_GUARDIAN.md)** - Comprehensive memory protection documentation
 - **[Troubleshooting](docs/user/troubleshooting.md)** - Common issues and solutions
 
 ### Developer Documentation
 - **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
 - **[API Reference](docs/api/)** - Complete API documentation with Sphinx
 - **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
+- **[Memory Guardian Technical](docs/MEMORY_GUARDIAN_TECHNICAL.md)** - Technical architecture and implementation details
+- **[Memory Guardian Configuration](docs/MEMORY_GUARDIAN_CONFIG.md)** - Complete configuration reference
 - **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
 - **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
 - **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
@@ -187,9 +211,34 @@ See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/M
 
 ## Development
 
+### Quick Development Setup
+```bash
+# Complete development setup with code formatting and quality tools
+make dev-complete
+
+# Or step by step:
+make setup-dev          # Install in development mode
+make setup-pre-commit    # Set up automated code formatting
+```
+
+### Code Quality & Formatting
+The project uses automated code formatting and quality checks:
+- **Black** for code formatting
+- **isort** for import sorting
+- **flake8** for linting
+- **mypy** for type checking
+- **Pre-commit hooks** for automatic enforcement
+
+See [docs/developer/CODE_FORMATTING.md](docs/developer/CODE_FORMATTING.md) for details.
+
 ### Contributing
 Contributions are welcome! Please see our [project structure guide](docs/STRUCTURE.md) and follow the established patterns.
 
+**Development Workflow**:
+1. Run `make dev-complete` to set up your environment
+2. Code formatting happens automatically on commit
+3. All code must pass quality checks before merging
+
 ### Project Structure
 See [docs/STRUCTURE.md](docs/STRUCTURE.md) for codebase organization.