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

claude_mpm/cli/parser.py

@@ -14,7 +14,7 @@ import argparse
 from pathlib import Path
 from typing import Optional, List
 
-from ..constants import CLICommands, CLIPrefix, AgentCommands, MemoryCommands, MonitorCommands, LogLevel
+from ..constants import CLICommands, CLIPrefix, AgentCommands, MemoryCommands, MonitorCommands, LogLevel, ConfigCommands, AggregateCommands
 
 
 def add_common_arguments(parser: argparse.ArgumentParser, version: str = None) -> None:
@@ -127,6 +127,30 @@ def add_run_arguments(parser: argparse.ArgumentParser) -> None:
         help="Resume a session (last session if no ID specified, or specific session ID)"
     )
     
+    # Dependency checking options
+    dep_group = parser.add_argument_group('dependency options')
+    dep_group.add_argument(
+        "--no-check-dependencies",
+        action="store_false",
+        dest="check_dependencies",
+        help="Skip agent dependency checking at startup"
+    )
+    dep_group.add_argument(
+        "--force-check-dependencies",
+        action="store_true",
+        help="Force dependency checking even if cached results exist"
+    )
+    dep_group.add_argument(
+        "--no-prompt",
+        action="store_true",
+        help="Never prompt for dependency installation (non-interactive mode)"
+    )
+    dep_group.add_argument(
+        "--force-prompt",
+        action="store_true",
+        help="Force interactive prompting even in non-TTY environments (use with caution)"
+    )
+    
     # Input/output options
     io_group = parser.add_argument_group('input/output options')
     io_group.add_argument(
@@ -229,6 +253,30 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         help="Resume a session (last session if no ID specified, or specific session ID)"
     )
     
+    # Dependency checking options (for backward compatibility at top level)
+    dep_group_top = parser.add_argument_group('dependency options (when no command specified)')
+    dep_group_top.add_argument(
+        "--no-check-dependencies",
+        action="store_false",
+        dest="check_dependencies",
+        help="Skip agent dependency checking at startup"
+    )
+    dep_group_top.add_argument(
+        "--force-check-dependencies",
+        action="store_true",
+        help="Force dependency checking even if cached results exist"
+    )
+    dep_group_top.add_argument(
+        "--no-prompt",
+        action="store_true",
+        help="Never prompt for dependency installation (non-interactive mode)"
+    )
+    dep_group_top.add_argument(
+        "--force-prompt",
+        action="store_true",
+        help="Force interactive prompting even in non-TTY environments (use with caution)"
+    )
+    
     # Input/output options
     io_group = parser.add_argument_group('input/output options (when no command specified)')
     io_group.add_argument(
@@ -353,6 +401,11 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         type=Path,
         help="Target directory (default: .claude/agents/)"
     )
+    deploy_agents_parser.add_argument(
+        "--include-all",
+        action="store_true",
+        help="Include all agents, overriding exclusion configuration"
+    )
     
     # Force deploy agents
     force_deploy_parser = agents_subparsers.add_parser(
@@ -364,6 +417,11 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         type=Path,
         help="Target directory (default: .claude/agents/)"
     )
+    force_deploy_parser.add_argument(
+        "--include-all",
+        action="store_true",
+        help="Include all agents, overriding exclusion configuration"
+    )
     
     # Clean agents
     clean_agents_parser = agents_subparsers.add_parser(
@@ -504,6 +562,119 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         help="Output raw memory content in JSON format for programmatic processing"
     )
     
+    # Add dependency management subcommands to agents
+    deps_check_parser = agents_subparsers.add_parser(
+        'deps-check',
+        help='Check dependencies for deployed agents'
+    )
+    deps_check_parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    deps_check_parser.add_argument(
+        '--agent',
+        type=str,
+        help='Check dependencies for a specific agent only'
+    )
+    
+    deps_install_parser = agents_subparsers.add_parser(
+        'deps-install',
+        help='Install missing dependencies for deployed agents'
+    )
+    deps_install_parser.add_argument(
+        '--agent',
+        type=str,
+        help='Install dependencies for a specific agent only'
+    )
+    deps_install_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Show what would be installed without actually installing'
+    )
+    
+    deps_list_parser = agents_subparsers.add_parser(
+        'deps-list',
+        help='List all dependencies from deployed agents'
+    )
+    deps_list_parser.add_argument(
+        '--format',
+        choices=['text', 'pip', 'json'],
+        default='text',
+        help='Output format for dependency list'
+    )
+    
+    # Config command with subcommands
+    config_parser = subparsers.add_parser(
+        CLICommands.CONFIG.value,
+        help="Validate and manage configuration"
+    )
+    add_common_arguments(config_parser)
+    
+    config_subparsers = config_parser.add_subparsers(
+        dest="config_command",
+        help="Config commands",
+        metavar="SUBCOMMAND"
+    )
+    
+    # Validate config
+    validate_config_parser = config_subparsers.add_parser(
+        ConfigCommands.VALIDATE.value,
+        help="Validate configuration file"
+    )
+    validate_config_parser.add_argument(
+        "--config-file",
+        type=Path,
+        help="Path to configuration file (default: .claude-mpm/configuration.yaml)"
+    )
+    validate_config_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors"
+    )
+    
+    # View config
+    view_config_parser = config_subparsers.add_parser(
+        ConfigCommands.VIEW.value,
+        help="View current configuration"
+    )
+    view_config_parser.add_argument(
+        "--config-file",
+        type=Path,
+        help="Path to configuration file"
+    )
+    view_config_parser.add_argument(
+        "--section",
+        help="View specific configuration section"
+    )
+    view_config_parser.add_argument(
+        "--format",
+        choices=["table", "json", "yaml"],
+        default="table",
+        help="Output format (default: table)"
+    )
+    
+    # Config status
+    status_config_parser = config_subparsers.add_parser(
+        ConfigCommands.STATUS.value,
+        help="Show configuration status and health"
+    )
+    status_config_parser.add_argument(
+        "--config-file",
+        type=Path,
+        help="Path to configuration file"
+    )
+    status_config_parser.add_argument(
+        "--check-response-logging",
+        action="store_true",
+        help="Show detailed response logging configuration"
+    )
+    status_config_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed errors and warnings"
+    )
+    
     # Monitor command with subcommands
     monitor_parser = subparsers.add_parser(
         CLICommands.MONITOR.value,
@@ -572,6 +743,10 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         help="Host to bind to (default: localhost)"
     )
     
+    # Import and add aggregate command parser
+    from .commands.aggregate import add_aggregate_parser
+    add_aggregate_parser(subparsers)
+    
     return parser
 
 

claude_mpm/cli/utils.py

@@ -61,7 +61,15 @@ def get_agent_versions_display() -> Optional[str]:
     """
     try:
         from ..services import AgentDeploymentService
-        deployment_service = AgentDeploymentService()
+        import os
+        from pathlib import Path
+        
+        # Determine the user's working directory from environment
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        
+        deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         
         # Get deployed agents
         verification = deployment_service.verify_deployment()

claude_mpm/cli_module/refactoring_guide.md

@@ -0,0 +1,253 @@
+# CLI Refactoring Guide
+
+This guide shows how to refactor the main() function in `/src/claude_mpm/cli.py` to reduce complexity from 16 to under 10.
+
+## Current Issues
+
+1. **High Cyclomatic Complexity (16)**
+   - Multiple nested conditionals
+   - Duplicate argument definitions
+   - Mixed concerns in one function
+
+2. **Code Duplication**
+   - Arguments defined twice (global level + run subcommand)
+   - Similar patterns repeated for each command
+
+3. **Poor Maintainability**
+   - Adding new commands requires multiple changes
+   - Hard to test individual components
+
+## Refactoring Steps
+
+### Step 1: Update imports in cli.py
+
+```python
+# Add to imports
+from .cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+```
+
+### Step 2: Replace main() function
+
+Replace the entire `main()` function with:
+
+```python
+def main(argv: Optional[list] = None):
+    """Main CLI entry point with reduced complexity."""
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        description=f"Claude Multi-Agent Project Manager v{__version__}",
+        epilog="By default, runs an orchestrated Claude session."
+    )
+    
+    # Store version for ArgumentRegistry
+    parser._version = f"claude-mpm {__version__}"
+    
+    # Apply global arguments
+    arg_registry.apply_arguments(parser, groups=['global'])
+    
+    # Apply run arguments at top level (for default behavior)
+    arg_registry.apply_arguments(parser, groups=['run'], exclude=['no_hooks'])
+    
+    # Set up subcommands
+    cmd_registry.setup_subcommands(parser)
+    
+    # Parse arguments
+    args = parser.parse_args(argv)
+    
+    # Set up logging
+    _setup_logging(args)
+    
+    # Initialize hook service
+    hook_manager = _initialize_hook_service(args)
+    
+    try:
+        # Execute command
+        result = cmd_registry.execute_command(args, hook_manager=hook_manager)
+        if result is None and not args.command:
+            parser.print_help()
+            return 1
+        return result or 0
+        
+    except KeyboardInterrupt:
+        get_logger("cli").info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger = get_logger("cli")
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        if hook_manager:
+            hook_manager.stop_service()
+```
+
+### Step 3: Extract helper functions
+
+Add these helper functions after main():
+
+```python
+def _setup_logging(args):
+    """Set up logging based on arguments."""
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        from .config.hook_config import HookConfig
+        
+        if not HookConfig.is_hooks_enabled():
+            get_logger("cli").info("Hooks disabled via configuration")
+            return None
+            
+        hook_manager = HookServiceManager(log_dir=args.log_dir)
+        if hook_manager.start_service():
+            logger = get_logger("cli")
+            logger.info(f"Hook service started on port {hook_manager.port}")
+            print(f"Hook service started on port {hook_manager.port}")
+            return hook_manager
+        else:
+            logger = get_logger("cli")
+            logger.warning("Failed to start hook service")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service init failed: {e}")
+        return None
+```
+
+### Step 4: Update command handler signatures
+
+Ensure all command handlers accept `**kwargs`:
+
+```python
+def run_session(args, hook_manager=None, **kwargs):
+    """Run an orchestrated Claude session."""
+    # ... existing implementation
+
+def list_tickets(args, **kwargs):
+    """List recent tickets."""
+    # ... existing implementation
+
+def show_info(args, hook_manager=None, **kwargs):
+    """Show framework and configuration information."""
+    # ... existing implementation
+```
+
+## Benefits Achieved
+
+### Complexity Reduction
+- **Before**: Cyclomatic complexity of 16
+- **After**: Cyclomatic complexity of ~8
+
+### Code Organization
+- Centralized argument definitions
+- No duplicate argument definitions
+- Clear separation of concerns
+- Easier to add new commands
+
+### Maintainability
+- New commands can be added with a single `register()` call
+- Arguments are defined once and reused
+- Helper functions are testable in isolation
+- Registry pattern allows for extension
+
+## Adding New Commands
+
+With the registry system, adding a new command is simple:
+
+```python
+# In your code or plugin
+def my_command(args, **kwargs):
+    """Implementation of your command."""
+    print(f"Running my command with args: {args}")
+    return 0
+
+# Register it
+cmd_registry.register(
+    name='mycommand',
+    help_text='Description of my command',
+    handler=my_command,
+    argument_groups=['framework'],  # Reuse existing argument groups
+    extra_args={
+        'custom_arg': {
+            'flags': ['--custom'],
+            'type': str,
+            'help': 'A custom argument for this command'
+        }
+    }
+)
+```
+
+## Testing
+
+The refactored code is easier to test:
+
+```python
+# Test argument registry
+def test_argument_registry():
+    registry = ArgumentRegistry()
+    parser = argparse.ArgumentParser()
+    registry.apply_arguments(parser, groups=['logging'])
+    
+    # Verify logging arguments were added
+    args = parser.parse_args(['--logging', 'DEBUG'])
+    assert args.logging == 'DEBUG'
+
+# Test command registry
+def test_command_registry():
+    arg_reg = ArgumentRegistry()
+    cmd_reg = CommandRegistry(arg_reg)
+    
+    called = False
+    def test_handler(args, **kwargs):
+        nonlocal called
+        called = True
+        return 0
+    
+    cmd_reg.register('test', 'Test command', test_handler)
+    
+    parser = argparse.ArgumentParser()
+    cmd_reg.setup_subcommands(parser)
+    
+    args = parser.parse_args(['test'])
+    result = cmd_reg.execute_command(args)
+    
+    assert called
+    assert result == 0
+```
+
+## Migration Checklist
+
+- [ ] Create `/src/claude_mpm/cli/` directory
+- [ ] Create `args.py` with ArgumentRegistry
+- [ ] Create `commands.py` with CommandRegistry
+- [ ] Create `__init__.py` to export classes
+- [ ] Update imports in `cli.py`
+- [ ] Replace main() function
+- [ ] Add helper functions
+- [ ] Update command handler signatures
+- [ ] Test the refactored CLI
+- [ ] Verify complexity is reduced to ≤10

claude_mpm/config/async_logging_config.yaml

@@ -0,0 +1,145 @@
+# Async Logging Configuration
+# Optimized logging configuration for high-performance scenarios
+
+logging:
+  # Enable async logging for improved performance
+  async:
+    enabled: true
+    
+    # Log format options: json, syslog, journald
+    format: json
+    
+    # Maximum queue size for async writes
+    max_queue_size: 10000
+    
+    # Enable compression for JSON logs (reduces disk usage)
+    compression: false
+    
+    # Worker threads for async processing
+    worker_threads: 4
+    
+    # Flush timeout in seconds
+    flush_timeout: 5.0
+  
+  # Session logger settings
+  session:
+    # Base directory for logs
+    base_dir: ".claude-mpm/responses"
+    
+    # Use timestamp-based filenames (eliminates race conditions)
+    timestamp_filenames: true
+    
+    # Include microseconds in timestamps for uniqueness
+    microsecond_precision: true
+    
+    # Filename format with available variables:
+    # {agent} - Agent name
+    # {timestamp} - ISO timestamp
+    # {microseconds} - Microsecond component
+    # {session} - Session ID
+    filename_format: "{agent}_{timestamp}_{microseconds}.json"
+  
+  # OS-native logging options (for extreme performance)
+  syslog:
+    # Syslog address (auto-detected by default)
+    # address: /var/run/syslog  # macOS
+    # address: /dev/log         # Linux
+    # address: ["localhost", 514]  # Network
+    
+    # Syslog facility
+    facility: local0
+    
+    # Include structured data
+    structured_data: true
+  
+  # Performance tuning
+  performance:
+    # Fire-and-forget mode (don't wait for write confirmation)
+    fire_and_forget: true
+    
+    # Drop logs if queue is full (prevents blocking)
+    drop_on_full: true
+    
+    # Batch writes for efficiency
+    batch_writes: true
+    batch_size: 10
+    batch_timeout_ms: 100
+
+# Hook system optimization
+hooks:
+  # Enable hook system
+  enabled: true
+  
+  # Optimization settings
+  optimization:
+    # Cache hook configurations at startup
+    cache_configs: true
+    
+    # Lazy load hook implementations
+    lazy_loading: true
+    
+    # Use singleton pattern for hook service
+    singleton: true
+    
+    # Enable async hook execution
+    async_execution: true
+    
+    # Maximum workers for parallel hook execution
+    max_workers: 4
+  
+  # Pre-delegation hooks
+  pre_delegation:
+    enabled: true
+    
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - memory_context_hook
+      - validation_hook
+      - auth_hook
+  
+  # Post-delegation hooks
+  post_delegation:
+    enabled: true
+    
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - logging_hook
+      - metrics_hook
+      - cleanup_hook
+  
+  # Registered hooks with lazy loading
+  registered:
+    # NOTE: The builtin hooks have been deprecated and removed
+    # These references are kept commented for historical reference
+    # memory_context_hook:
+    #   module: claude_mpm.hooks.builtin.memory_hooks
+    #   class: MemoryContextHook
+    #   priority: 10
+    #   enabled: true
+    #   params:
+    #     cache_size: 1000
+    # 
+    # response_logger_hook:
+    #   module: claude_mpm.hooks.builtin.logging_hooks
+    #   class: ResponseLoggerHook
+    #   priority: 90
+    #   enabled: true
+    #   params:
+    #     async: true
+    # 
+    # metrics_hook:
+    #   module: claude_mpm.hooks.builtin.metrics_hooks
+    #   class: MetricsCollectorHook
+    #   priority: 95
+    #   enabled: true
+    #   params:
+    #     buffer_size: 100
+
+# Environment variable overrides
+# These can override any setting above:
+#
+# CLAUDE_USE_ASYNC_LOG=true        # Enable async logging
+# CLAUDE_LOG_FORMAT=syslog         # Use syslog format
+# CLAUDE_LOG_SYNC=true             # Disable async (for debugging)
+# CLAUDE_HOOKS_CACHE=true          # Enable hook caching
+# CLAUDE_HOOKS_ASYNC=true          # Enable async hooks

claude_mpm/constants.py

@@ -28,6 +28,8 @@ class CLICommands(str, Enum):
     AGENTS = "agents"
     MEMORY = "memory"
     MONITOR = "monitor"
+    CONFIG = "config"
+    AGGREGATE = "aggregate"
     
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -80,6 +82,23 @@ class MonitorCommands(str, Enum):
     PORT = "port"
 
 
+class ConfigCommands(str, Enum):
+    """Config subcommand constants."""
+    VALIDATE = "validate"
+    VIEW = "view"
+    STATUS = "status"
+
+
+class AggregateCommands(str, Enum):
+    """Event aggregator subcommand constants."""
+    START = "start"
+    STOP = "stop"
+    STATUS = "status"
+    SESSIONS = "sessions"
+    VIEW = "view"
+    EXPORT = "export"
+
+
 class CLIFlags(str, Enum):
     """CLI flag constants (without prefix)."""
     # Logging flags