claude-mpm 3.3.2__py3-none-any.whl → 3.4.2__py3-none-any.whl

claude_mpm/core/base_service.py.bak

@@ -1,406 +0,0 @@
-"""
-Base service class for Claude PM Framework services.
-
-Provides common functionality including:
-- Lifecycle management (start, stop, health checks)
-- Configuration management
-- Logging
-- Metrics collection
-- Error handling and retry logic
-- Service discovery and registration
-"""
-
-import asyncio
-import logging
-import signal
-import sys
-import os
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any, Dict, List, Optional, Union
-from pathlib import Path
-import json
-
-from .config import Config
-from .logger import setup_logging
-from .mixins import LoggerMixin
-
-
-@dataclass
-class ServiceHealth:
-    """Service health status information."""
-
-    status: str  # healthy, degraded, unhealthy, unknown
-    message: str
-    timestamp: str
-    metrics: Dict[str, Any] = field(default_factory=dict)
-    checks: Dict[str, bool] = field(default_factory=dict)
-
-
-@dataclass
-class ServiceMetrics:
-    """Service metrics collection."""
-
-    requests_total: int = 0
-    requests_failed: int = 0
-    response_time_avg: float = 0.0
-    uptime_seconds: int = 0
-    memory_usage_mb: float = 0.0
-    custom_metrics: Dict[str, Any] = field(default_factory=dict)
-
-
-class BaseService(LoggerMixin, ABC):
-    """
-    Abstract base class for all Claude PM services.
-
-    Provides common infrastructure for service lifecycle management,
-    health monitoring, configuration, logging, and error handling.
-    """
-
-    def __init__(
-        self, name: str, config: Optional[Dict[str, Any]] = None, config_path: Optional[Path] = None
-    ):
-        """
-        Initialize the base service.
-
-        Args:
-            name: Service name for identification
-            config: Optional configuration dictionary
-            config_path: Optional path to configuration file
-        """
-        self.name = name
-        self.config = Config(config or {}, config_path)
-        
-        # Set custom logger name based on service name
-        self._logger_name = f"{self.__class__.__module__}.{self.__class__.__name__}.{name}"
-
-        # Service state
-        self._running = False
-        self._start_time: Optional[datetime] = None
-        self._stop_event = asyncio.Event()
-
-        # Health and metrics
-        self._health = ServiceHealth(
-            status="unknown", message="Service not started", timestamp=datetime.now().isoformat()
-        )
-        self._metrics = ServiceMetrics()
-
-        # Background tasks
-        self._background_tasks: List[asyncio.Task] = []
-
-        # Check for quiet mode environment variable
-        default_log_level = "INFO"
-        if os.getenv('CLAUDE_PM_QUIET_MODE') == 'true':
-            default_log_level = "WARNING"
-            # Set logger level if needed
-            self.logger.setLevel(logging.WARNING)
-        
-        # Only log if not in quiet mode
-        if not os.environ.get('CLAUDE_PM_QUIET_MODE', '').lower() == 'true':
-            self.logger.info(f"Initialized {self.name} service")
-
-    @property
-    def running(self) -> bool:
-        """Check if service is currently running."""
-        return self._running
-
-    @property
-    def uptime(self) -> Optional[float]:
-        """Get service uptime in seconds."""
-        if self._start_time and self._running:
-            return (datetime.now() - self._start_time).total_seconds()
-        return None
-
-    @property
-    def health(self) -> ServiceHealth:
-        """Get current service health status."""
-        return self._health
-
-    @property
-    def metrics(self) -> ServiceMetrics:
-        """Get current service metrics."""
-        if self.uptime:
-            self._metrics.uptime_seconds = int(self.uptime)
-        return self._metrics
-
-    async def start(self) -> None:
-        """Start the service."""
-        if self._running:
-            self.logger.warning(f"Service {self.name} is already running")
-            return
-
-        self.logger.info(f"Starting {self.name} service...")
-
-        try:
-            # Setup signal handlers
-            self._setup_signal_handlers()
-
-            # Initialize service
-            await self._initialize()
-
-            # Start background tasks
-            await self._start_background_tasks()
-
-            # Mark as running
-            self._running = True
-            self._start_time = datetime.now()
-
-            # Update health status
-            self._health = ServiceHealth(
-                status="healthy",
-                message="Service started successfully",
-                timestamp=datetime.now().isoformat(),
-                checks={"startup": True},
-            )
-
-            self.logger.info(f"Service {self.name} started successfully")
-
-        except Exception as e:
-            self.logger.error(f"Failed to start service {self.name}: {e}")
-            self._health = ServiceHealth(
-                status="unhealthy",
-                message=f"Startup failed: {str(e)}",
-                timestamp=datetime.now().isoformat(),
-                checks={"startup": False},
-            )
-            raise
-
-    async def stop(self) -> None:
-        """Stop the service gracefully."""
-        if not self._running:
-            self.logger.warning(f"Service {self.name} is not running")
-            return
-
-        self.logger.info(f"Stopping {self.name} service...")
-
-        try:
-            # Signal stop to background tasks
-            self._stop_event.set()
-
-            # Cancel background tasks
-            for task in self._background_tasks:
-                if not task.done():
-                    task.cancel()
-
-            # Wait for tasks to complete
-            if self._background_tasks:
-                await asyncio.gather(*self._background_tasks, return_exceptions=True)
-
-            # Cleanup service
-            await self._cleanup()
-
-            # Mark as stopped
-            self._running = False
-
-            # Update health status
-            self._health = ServiceHealth(
-                status="unknown",
-                message="Service stopped",
-                timestamp=datetime.now().isoformat(),
-                checks={"running": False},
-            )
-
-            self.logger.info(f"Service {self.name} stopped successfully")
-
-        except Exception as e:
-            self.logger.error(f"Error stopping service {self.name}: {e}")
-            raise
-
-    async def restart(self) -> None:
-        """Restart the service."""
-        self.logger.info(f"Restarting {self.name} service...")
-        await self.stop()
-        await self.start()
-
-    async def health_check(self) -> ServiceHealth:
-        """
-        Perform comprehensive health check.
-
-        Returns:
-            ServiceHealth object with current status
-        """
-        try:
-            checks = {}
-
-            # Basic running check
-            checks["running"] = self._running
-
-            # Custom health checks
-            custom_checks = await self._health_check()
-            checks.update(custom_checks)
-
-            # Determine overall status
-            if not checks["running"]:
-                status = "unhealthy"
-                message = "Service is not running"
-            elif all(checks.values()):
-                status = "healthy"
-                message = "All health checks passed"
-            elif any(checks.values()):
-                status = "degraded"
-                message = "Some health checks failed"
-            else:
-                status = "unhealthy"
-                message = "Multiple health checks failed"
-
-            # Update health status
-            self._health = ServiceHealth(
-                status=status,
-                message=message,
-                timestamp=datetime.now().isoformat(),
-                checks=checks,
-                metrics={
-                    "uptime": self.uptime,
-                    "requests_total": self._metrics.requests_total,
-                    "requests_failed": self._metrics.requests_failed,
-                },
-            )
-
-            return self._health
-
-        except Exception as e:
-            self.logger.error(f"Health check failed for {self.name}: {e}")
-            self._health = ServiceHealth(
-                status="unhealthy",
-                message=f"Health check error: {str(e)}",
-                timestamp=datetime.now().isoformat(),
-                checks={"health_check_error": True},
-            )
-            return self._health
-
-    def update_metrics(self, **kwargs) -> None:
-        """Update service metrics."""
-        for key, value in kwargs.items():
-            if hasattr(self._metrics, key):
-                setattr(self._metrics, key, value)
-            else:
-                self._metrics.custom_metrics[key] = value
-
-    def get_config(self, key: str, default: Any = None) -> Any:
-        """Get configuration value."""
-        return self.config.get(key, default)
-
-    def _setup_signal_handlers(self) -> None:
-        """Setup signal handlers for graceful shutdown."""
-
-        def signal_handler(signum, frame):
-            self.logger.info(f"Received signal {signum}, initiating graceful shutdown...")
-            asyncio.create_task(self.stop())
-
-        signal.signal(signal.SIGINT, signal_handler)
-        signal.signal(signal.SIGTERM, signal_handler)
-
-    async def _start_background_tasks(self) -> None:
-        """Start background tasks."""
-        # Health check task
-        if self.get_config("enable_health_monitoring", True):
-            interval = self.get_config("health_check_interval", 30)
-            task = asyncio.create_task(self._health_monitor_task(interval))
-            self._background_tasks.append(task)
-
-        # Metrics collection task
-        if self.get_config("enable_metrics", True):
-            interval = self.get_config("metrics_interval", 60)
-            task = asyncio.create_task(self._metrics_task(interval))
-            self._background_tasks.append(task)
-
-        # Custom background tasks
-        custom_tasks = await self._start_custom_tasks()
-        if custom_tasks:
-            self._background_tasks.extend(custom_tasks)
-
-    async def _health_monitor_task(self, interval: int) -> None:
-        """Background task for periodic health monitoring."""
-        while not self._stop_event.is_set():
-            try:
-                await self.health_check()
-                await asyncio.sleep(interval)
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                self.logger.error(f"Health monitor task error: {e}")
-                await asyncio.sleep(interval)
-
-    async def _metrics_task(self, interval: int) -> None:
-        """Background task for metrics collection."""
-        while not self._stop_event.is_set():
-            try:
-                await self._collect_metrics()
-                await asyncio.sleep(interval)
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                self.logger.error(f"Metrics task error: {e}")
-                await asyncio.sleep(interval)
-
-    async def _collect_metrics(self) -> None:
-        """Collect service metrics."""
-        try:
-            # Update uptime
-            if self.uptime:
-                self._metrics.uptime_seconds = int(self.uptime)
-
-            # Memory usage (basic implementation)
-            import psutil
-
-            process = psutil.Process()
-            self._metrics.memory_usage_mb = process.memory_info().rss / 1024 / 1024
-
-            # Custom metrics collection
-            await self._collect_custom_metrics()
-
-        except Exception as e:
-            self.logger.warning(f"Failed to collect metrics: {e}")
-
-    # Abstract methods to be implemented by subclasses
-
-    @abstractmethod
-    async def _initialize(self) -> None:
-        """Initialize the service. Must be implemented by subclasses."""
-        pass
-
-    @abstractmethod
-    async def _cleanup(self) -> None:
-        """Cleanup service resources. Must be implemented by subclasses."""
-        pass
-
-    async def _health_check(self) -> Dict[str, bool]:
-        """
-        Perform custom health checks. Override in subclasses.
-
-        Returns:
-            Dictionary of check name -> success boolean
-        """
-        return {}
-
-    async def _start_custom_tasks(self) -> Optional[List[asyncio.Task]]:
-        """
-        Start custom background tasks. Override in subclasses.
-
-        Returns:
-            List of asyncio tasks or None
-        """
-        return None
-
-    async def _collect_custom_metrics(self) -> None:
-        """Collect custom metrics. Override in subclasses."""
-        pass
-
-    # Utility methods
-
-    async def run_forever(self) -> None:
-        """Run the service until stopped."""
-        await self.start()
-        try:
-            # Wait for stop signal
-            while self._running:
-                await asyncio.sleep(1)
-        except KeyboardInterrupt:
-            self.logger.info("Received keyboard interrupt")
-        finally:
-            await self.stop()
-
-    def __repr__(self) -> str:
-        """String representation of the service."""
-        return f"<{self.__class__.__name__}(name='{self.name}', running={self._running})>"

claude_mpm/hooks/README.md

@@ -1,97 +0,0 @@
-# Claude Code Hooks System
-
-This directory contains the Claude Code hook integration for claude-mpm.
-
-## Overview
-
-The hook system allows claude-mpm to intercept and handle commands typed in Claude Code, particularly the `/mpm` commands.
-
-## Structure
-
-```
-hooks/
-├── claude_hooks/              # Claude Code hook implementation
-│   ├── hook_handler.py       # Main Python handler that processes events
-│   └── hook_wrapper.sh       # Shell wrapper script (this is what gets installed in ~/.claude/settings.json)
-└── builtin/                  # Legacy internal hooks (deprecated)
-```
-
-## Claude Code Hooks
-
-The Claude Code hooks are the primary integration point between claude-mpm and Claude Code. They allow:
-
-- Intercepting `/mpm` commands before they reach the LLM
-- Providing custom responses and actions
-- Blocking LLM processing when appropriate
-
-### Installation
-
-To install the Claude Code hooks:
-
-```bash
-python scripts/install_hooks.py
-```
-
-This will:
-1. Create/update `~/.claude/settings.json` with hook configuration
-2. Point to the `hook_wrapper.sh` script
-3. Copy any custom commands to `~/.claude/commands/`
-
-### How It Works
-
-1. When you type in Claude Code, it triggers hook events
-2. Claude Code calls `hook_wrapper.sh` (the path in `~/.claude/settings.json`)
-3. The wrapper script:
-   - Detects if it's running from a local dev environment, npm, or PyPI installation
-   - Activates the appropriate Python environment
-   - Runs `hook_handler.py` with the event data
-4. The handler processes various event types:
-   - **UserPromptSubmit**: Checks if the prompt starts with `/mpm` and handles commands
-   - **PreToolUse**: Logs tool usage before execution
-   - **PostToolUse**: Logs tool results after execution
-   - **Stop**: Logs when a session or task stops
-   - **SubagentStop**: Logs when a subagent completes with agent type and ID
-5. For `/mpm` commands, it returns exit code 2 to block LLM processing
-6. All events are logged to project-specific log files in `.claude-mpm/logs/`
-
-### Available Commands
-
-- `/mpm` - Show help and available commands
-- `/mpm status` - Show claude-mpm status and environment
-- `/mpm help` - Show detailed help
-
-### Debugging
-
-To enable debug logging for hooks:
-
-```bash
-export CLAUDE_MPM_LOG_LEVEL=DEBUG
-```
-
-Then run Claude Code from that terminal. Hook events will be logged to `~/.claude-mpm/logs/`.
-
-## Legacy Hook System (Deprecated)
-
-The `builtin/` directory contains the old internal hook system that was designed for JSON-RPC based hooks. This system is deprecated and will be removed in a future version. All hook functionality is now handled through the Claude Code hooks.
-
-## Development
-
-To add new `/mpm` commands:
-
-1. Edit `hook_handler.py` to handle the new command
-2. Update the help text in the `handle_mpm_help()` function
-3. Test by running Claude Code with the new command
-
-## Exit Codes
-
-The hook system uses specific exit codes:
-
-- `0` - Success, continue normal processing
-- `2` - Block LLM processing (command was handled)
-- Other - Error occurred
-
-## Environment Variables
-
-- `CLAUDE_MPM_LOG_LEVEL` - Set to DEBUG for detailed logging
-- `HOOK_EVENT_TYPE` - Set by Claude Code (UserPromptSubmit, PreToolUse, PostToolUse)
-- `HOOK_DATA` - JSON data from Claude Code with event details

claude_mpm/orchestration/SUBPROCESS_DESIGN.md

@@ -1,66 +0,0 @@
-# Subprocess Orchestration Design
-
-## Problem
-Claude's `--print` mode times out when generating code or using tools, making subprocess orchestration in non-interactive mode impractical.
-
-## Findings
-
-### Interactive Mode (Working)
-- Claude uses built-in Task tool
-- Creates real subprocesses with ~11.4k tokens each
-- Runs in parallel with independent timing
-- Each subprocess gets framework context
-
-### Non-Interactive Mode Issues
-- `claude --print` works for simple queries (e.g., "What is 2+2?" in ~4s)
-- Times out for any code generation or complex tasks
-- Debug shows Claude is working but tool usage adds overhead
-- Requires `--dangerously-skip-permissions` flag to run
-
-## Alternative Approaches
-
-### 1. Use Claude's Conversation API
-Instead of `--print`, use conversation management:
-```bash
-# Start conversation
-claude --model opus -c "conversation_id" < prompt.txt
-
-# Continue conversation
-claude --continue conversation_id < next_prompt.txt
-```
-
-### 2. Use Interactive Mode with Expect
-Use expect/pexpect to control interactive Claude sessions programmatically.
-
-### 3. Mock Subprocess Mode
-For testing/development:
-- Detect delegations in PM response
-- Show subprocess-like output
-- But don't actually create subprocesses
-
-### 4. Direct API Integration
-Skip CLI entirely and use Claude's API directly (if available).
-
-## Implementation Status
-
-### Completed
-1. ✅ SubprocessOrchestrator class with full functionality
-2. ✅ Delegation detection for multiple formats
-3. ✅ Parallel subprocess execution framework
-4. ✅ Agent-specific prompt generation
-5. ✅ CLI integration via `--subprocess` flag
-6. ✅ Fixed command flags for permissions
-
-### Current Status
-- Implementation is complete but blocked by Claude CLI limitations
-- Use interactive mode for real subprocess orchestration
-- Keep implementation for future when Claude print mode improves
-
-## Delegation Detection Patterns
-
-The PM uses these formats:
-- `**Engineer Agent**: Create a function...`
-- `**QA**: Write tests for...`
-- `I'll delegate this to the Engineer agent...`
-
-We can parse these and show subprocess-style output even without real subprocesses.

claude_mpm/schemas/README_SECURITY.md

@@ -1,92 +0,0 @@
-# Agent Schema Security Guide
-
-## Critical Security Notice
-
-**This schema is a SECURITY BOUNDARY.** Any changes to agent_schema.json must be carefully reviewed for security implications.
-
-## Security Controls in agent_schema.json
-
-### 1. Field Validation
-- **agent_id**: Pattern `^[a-z][a-z0-9_]*$` prevents path traversal and command injection
-- **version fields**: Semantic versioning pattern prevents version injection
-- **enums**: All enums are allowlists preventing arbitrary values
-
-### 2. Size Limits
-- **instructions**: 8000 char max prevents memory exhaustion
-- **name**: 50 char max prevents UI breaking
-- **description**: 200 char max prevents storage abuse
-- **tags**: max 10 items prevents array bombing
-
-### 3. Resource Limits by Tier
-```
-intensive:    memory: 4096-8192MB, cpu: 60-100%, timeout: 600-3600s
-standard:     memory: 2048-4096MB, cpu: 30-60%,  timeout: 300-1200s  
-lightweight:  memory: 512-2048MB,  cpu: 10-30%,  timeout: 30-600s
-```
-
-### 4. Tool Security Matrix
-
-| Tool Combination | Risk Level | Security Impact |
-|-----------------|------------|-----------------|
-| Bash + Write | CRITICAL | Arbitrary code execution |
-| docker + kubectl | HIGH | Container escape potential |
-| aws + gcloud + azure | HIGH | Multi-cloud attack surface |
-| WebFetch + Write | MEDIUM | Data exfiltration risk |
-| Read + network_access | MEDIUM | Information disclosure |
-
-### 5. Required Security Reviews
-
-Any PR modifying agent_schema.json MUST include:
-1. Security impact assessment
-2. Validation that no new fields bypass security controls
-3. Test cases for new validation rules
-4. Update to this security guide if needed
-
-### 6. Security Checklist for Schema Changes
-
-- [ ] No new fields allow arbitrary string input without validation
-- [ ] All new arrays have maxItems limits
-- [ ] All new strings have maxLength limits
-- [ ] New enum values are reviewed for security impact
-- [ ] Resource limits maintain tier boundaries
-- [ ] No new fields can bypass additionalProperties: false
-- [ ] Pattern validations prevent injection attacks
-- [ ] Default values follow principle of least privilege
-
-## Common Security Mistakes to Avoid
-
-1. **Never** add fields that accept arbitrary file paths without validation
-2. **Never** increase resource limits without security review
-3. **Never** add tools that bypass the enum list
-4. **Never** remove pattern validation from ID fields
-5. **Never** set additionalProperties to true
-6. **Always** default network_access to false
-7. **Always** validate new tool combinations for security impact
-
-## Security Testing
-
-Run these tests after any schema change:
-```bash
-# Validate schema structure
-python scripts/validate_agent_schema.py
-
-# Test security boundaries
-python tests/test_agent_security_boundaries.py
-
-# Check for injection vulnerabilities
-python tests/test_agent_validation_security.py
-```
-
-## Incident Response
-
-If a security vulnerability is found in the schema:
-1. Immediately add validation in agent_validator.py as a hotfix
-2. Update schema to prevent the vulnerability
-3. Audit all existing agents for exploitation
-4. Document the vulnerability and fix in security log
-
-## Security Contacts
-
-- Security reviews: security-team@company.com
-- Vulnerability reports: security@company.com
-- Emergency response: security-oncall@company.com