claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/core/system_context.py

@@ -0,0 +1,38 @@
+"""System context utilities for Claude runner.
+
+This module provides shared context creation functions that can be used
+across different modules without circular dependencies.
+"""
+
+
+def create_simple_context() -> str:
+    """Create basic context for Claude.
+
+    This function is extracted to avoid circular imports between
+    claude_runner.py and interactive_session.py.
+
+    Returns:
+        Basic system context string for Claude
+    """
+    return """You are Claude Code running in Claude MPM (Multi-Agent Project Manager).
+
+You have access to native subagents via the Task tool with subagent_type parameter:
+- engineer: For coding, implementation, and technical tasks
+- qa: For testing, validation, and quality assurance
+- documentation: For docs, guides, and explanations
+- research: For investigation and analysis
+- security: For security-related tasks
+- ops: For deployment and infrastructure
+- version-control: For git and version management
+- data-engineer: For data processing and APIs
+
+Use these agents by calling: Task(description="task description", subagent_type="agent_name")
+
+IMPORTANT: The Task tool accepts both naming formats:
+- Capitalized format: "Research", "Engineer", "QA", "Version Control", "Data Engineer"
+- Lowercase format: "research", "engineer", "qa", "version-control", "data-engineer"
+
+Both formats work correctly. When you see capitalized names (matching TodoWrite prefixes),
+automatically normalize them to lowercase-hyphenated format for the Task tool.
+
+Work efficiently and delegate appropriately to subagents when needed."""

claude_mpm/core/tool_access_control.py

@@ -1,47 +1,47 @@
 """Tool access control system for managing which tools agents can use."""
 
-from typing import Dict, List, Set, Optional
-import logging
+from typing import Dict, List, Set
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class ToolAccessControl:
     """
     Manages tool access permissions for different agent types.
-    
+
     This ensures that only authorized agents can access specific tools,
     particularly restricting TodoWrite to the PM (parent process) only.
     """
-    
+
     # Default tool sets for different contexts
     PM_TOOLS = {
-        "Task",           # For delegating to agents
-        "TodoWrite",      # For tracking tasks (PM ONLY)
-        "WebSearch",      # For understanding requirements
-        "WebFetch"        # For fetching external resources
+        "Task",  # For delegating to agents
+        "TodoWrite",  # For tracking tasks (PM ONLY)
+        "WebSearch",  # For understanding requirements
+        "WebFetch",  # For fetching external resources
     }
-    
+
     AGENT_TOOLS = {
-        "Read",           # Read files
-        "Write",          # Write files
-        "Edit",           # Edit files
-        "MultiEdit",      # Multiple edits
-        "Bash",           # Execute commands
-        "Grep",           # Search in files
-        "Glob",           # File pattern matching
-        "LS",             # List directory
-        "WebSearch",      # Search the web
-        "WebFetch",       # Fetch web content
-        "NotebookRead",   # Read Jupyter notebooks
-        "NotebookEdit"    # Edit Jupyter notebooks
+        "Read",  # Read files
+        "Write",  # Write files
+        "Edit",  # Edit files
+        "MultiEdit",  # Multiple edits
+        "Bash",  # Execute commands
+        "Grep",  # Search in files
+        "Glob",  # File pattern matching
+        "LS",  # List directory
+        "WebSearch",  # Search the web
+        "WebFetch",  # Fetch web content
+        "NotebookRead",  # Read Jupyter notebooks
+        "NotebookEdit",  # Edit Jupyter notebooks
     }
-    
+
     # Tool restrictions by agent type
     AGENT_RESTRICTIONS: Dict[str, Set[str]] = {
         # PM has very limited tools - delegation only
         "pm": PM_TOOLS,
-        
         # All other agents get standard tools WITHOUT TodoWrite
         "engineer": AGENT_TOOLS,
         "research": AGENT_TOOLS,
@@ -51,34 +51,34 @@ class ToolAccessControl:
         "ops": AGENT_TOOLS,
         "version_control": AGENT_TOOLS,
         "data_engineer": AGENT_TOOLS,
-        "architect": AGENT_TOOLS
+        "architect": AGENT_TOOLS,
     }
-    
+
     def __init__(self):
         """Initialize the tool access control system."""
         self.custom_restrictions: Dict[str, Set[str]] = {}
         logger.info("Tool access control system initialized")
-    
+
     def get_allowed_tools(self, agent_type: str, is_parent: bool = False) -> List[str]:
         """
         Get the list of allowed tools for an agent type.
-        
+
         Args:
             agent_type: The type of agent (pm, engineer, research, etc.)
             is_parent: Whether this is the parent process (PM)
-            
+
         Returns:
             List of allowed tool names
         """
         # Normalize agent type
         agent_type = agent_type.lower().replace(" ", "_").replace("-", "_")
-        
+
         # Parent process (PM) gets PM tools
         if is_parent or agent_type == "pm":
             allowed = self.PM_TOOLS.copy()
             logger.debug(f"PM/Parent process allowed tools: {allowed}")
-            return sorted(list(allowed))
-        
+            return sorted(allowed)
+
         # Check custom restrictions first
         if agent_type in self.custom_restrictions:
             allowed = self.custom_restrictions[agent_type]
@@ -86,81 +86,88 @@ class ToolAccessControl:
             allowed = self.AGENT_RESTRICTIONS[agent_type]
         else:
             # Default to agent tools for unknown types
-            logger.warning(f"Unknown agent type '{agent_type}', using default agent tools")
+            logger.warning(
+                f"Unknown agent type '{agent_type}', using default agent tools"
+            )
             allowed = self.AGENT_TOOLS.copy()
-        
+
         # Ensure TodoWrite is NEVER in child agent tools
         allowed = allowed - {"TodoWrite"}
-        
+
         logger.debug(f"Agent '{agent_type}' allowed tools: {allowed}")
-        return sorted(list(allowed))
-    
+        return sorted(allowed)
+
     def format_allowed_tools_arg(self, agent_type: str, is_parent: bool = False) -> str:
         """
         Format the allowed tools as a comma-separated string for --allowedTools argument.
-        
+
         Args:
             agent_type: The type of agent
             is_parent: Whether this is the parent process
-            
+
         Returns:
             Comma-separated string of allowed tools
         """
         allowed_tools = self.get_allowed_tools(agent_type, is_parent)
         return ",".join(allowed_tools)
-    
+
     def set_custom_restrictions(self, agent_type: str, allowed_tools: Set[str]):
         """
         Set custom tool restrictions for a specific agent type.
-        
+
         Args:
             agent_type: The agent type to customize
             allowed_tools: Set of allowed tool names
         """
         agent_type = agent_type.lower().replace(" ", "_").replace("-", "_")
-        
+
         # Ensure TodoWrite is not in custom restrictions for non-PM agents
         if agent_type != "pm" and "TodoWrite" in allowed_tools:
-            logger.warning(f"Removing TodoWrite from custom restrictions for {agent_type}")
+            logger.warning(
+                f"Removing TodoWrite from custom restrictions for {agent_type}"
+            )
             allowed_tools = allowed_tools - {"TodoWrite"}
-        
+
         self.custom_restrictions[agent_type] = allowed_tools
         logger.info(f"Set custom tool restrictions for {agent_type}: {allowed_tools}")
-    
-    def validate_tool_usage(self, agent_type: str, tool_name: str, is_parent: bool = False) -> bool:
+
+    def validate_tool_usage(
+        self, agent_type: str, tool_name: str, is_parent: bool = False
+    ) -> bool:
         """
         Validate if an agent is allowed to use a specific tool.
-        
+
         Args:
             agent_type: The type of agent
             tool_name: The name of the tool
             is_parent: Whether this is the parent process
-            
+
         Returns:
             True if allowed, False otherwise
         """
         allowed_tools = self.get_allowed_tools(agent_type, is_parent)
         is_allowed = tool_name in allowed_tools
-        
+
         if not is_allowed:
-            logger.warning(f"Agent '{agent_type}' attempted to use forbidden tool '{tool_name}'")
-        
+            logger.warning(
+                f"Agent '{agent_type}' attempted to use forbidden tool '{tool_name}'"
+            )
+
         return is_allowed
-    
+
     def get_todo_guidance(self, agent_type: str) -> str:
         """
         Get guidance text for agents on how to handle TODOs.
-        
+
         Args:
             agent_type: The type of agent
-            
+
         Returns:
             Guidance text for handling TODOs
         """
         if agent_type.lower() == "pm":
             return """You have access to the TodoWrite tool for tracking tasks. Always prefix todos with [Agent] to indicate delegation target."""
-        else:
-            return """You do NOT have access to TodoWrite. Instead, when you identify tasks that need tracking:
+        return """You do NOT have access to TodoWrite. Instead, when you identify tasks that need tracking:
 1. Include them in your response with clear markers like "TODO:" or "TASK:"
 2. Format them as a structured list with priority and description
 3. The PM will extract and track these in the central todo list
@@ -170,4 +177,4 @@ class ToolAccessControl:
 
 
 # Global instance for easy access
-tool_access_control = ToolAccessControl()
+tool_access_control = ToolAccessControl()

claude_mpm/core/types.py

@@ -0,0 +1,307 @@
+from pathlib import Path
+
+"""
+Central type definitions for Claude MPM.
+
+This module provides shared type definitions to prevent circular import
+dependencies. By centralizing commonly used types, we avoid the need for
+cross-module imports that can create circular dependency chains.
+
+WHY: Circular imports were causing ImportError exceptions throughout the
+codebase. By extracting shared types to this central location, modules
+can import types without creating dependency cycles.
+
+DESIGN DECISION: Only include types that are shared across multiple modules.
+Module-specific types should remain in their respective modules.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from .enums import HealthStatus
+
+
+# Service operation results
+@dataclass
+class ServiceResult:
+    """Standard result type for service operations."""
+
+    success: bool
+    message: str
+    data: Optional[Dict[str, Any]] = None
+    errors: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "success": self.success,
+            "message": self.message,
+            "data": self.data,
+            "errors": self.errors,
+        }
+
+
+# Deployment-related types
+@dataclass
+class DeploymentResult:
+    """Result of an agent deployment operation."""
+
+    deployed: List[str]
+    updated: List[str]
+    failed: List[str]
+    skipped: List[str]
+    errors: Dict[str, str]
+    metadata: Dict[str, Any]
+
+    @property
+    def total_processed(self) -> int:
+        """Get total number of agents processed."""
+        return (
+            len(self.deployed)
+            + len(self.updated)
+            + len(self.failed)
+            + len(self.skipped)
+        )
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate deployment success rate."""
+        if self.total_processed == 0:
+            return 0.0
+        successful = len(self.deployed) + len(self.updated)
+        return successful / self.total_processed
+
+
+# Agent-related types
+class AgentTier(Enum):
+    """Agent tier levels for precedence."""
+
+    PROJECT = "PROJECT"  # Highest precedence - project-specific agents
+    USER = "USER"  # User-level agents
+    SYSTEM = "SYSTEM"  # Lowest precedence - system agents
+
+    @classmethod
+    def from_string(cls, value: str) -> "AgentTier":
+        """Convert string to AgentTier enum."""
+        value_upper = value.upper()
+        for tier in cls:
+            if tier.value == value_upper:
+                return tier
+        raise ValueError(f"Invalid agent tier: {value}")
+
+
+@dataclass
+class AgentInfo:
+    """Basic agent information."""
+
+    agent_id: str
+    name: str
+    tier: AgentTier
+    path: Path
+    version: Optional[str] = None
+    description: Optional[str] = None
+    capabilities: Optional[List[str]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.capabilities is None:
+            self.capabilities = []
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Memory-related types
+@dataclass
+class MemoryEntry:
+    """Single memory entry for an agent."""
+
+    timestamp: datetime
+    content: str
+    category: str
+    agent_id: str
+    session_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Hook-related types
+class HookType(Enum):
+    """Types of hooks in the system."""
+
+    PRE_DELEGATION = "pre_delegation"
+    POST_DELEGATION = "post_delegation"
+    PRE_RESPONSE = "pre_response"
+    POST_RESPONSE = "post_response"
+    ERROR = "error"
+    SHUTDOWN = "shutdown"
+
+
+@dataclass
+class HookContext:
+    """Context passed to hook handlers."""
+
+    event_type: str
+    data: Dict[str, Any]
+    timestamp: datetime
+    source: Optional[str] = None
+    session_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Configuration types
+@dataclass
+class ConfigSection:
+    """Configuration section with validation."""
+
+    name: str
+    values: Dict[str, Any]
+    schema: Optional[Dict[str, Any]] = None
+    is_valid: bool = True
+    validation_errors: Optional[List[str]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.validation_errors is None:
+            self.validation_errors = []
+
+
+# Task/Ticket types
+class TaskStatus(Enum):
+    """Task/ticket status values."""
+
+    TODO = "todo"
+    IN_PROGRESS = "in_progress"
+    BLOCKED = "blocked"
+    REVIEW = "review"
+    DONE = "done"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class TaskInfo:
+    """Basic task/ticket information."""
+
+    task_id: str
+    title: str
+    status: TaskStatus
+    description: Optional[str] = None
+    assignee: Optional[str] = None
+    priority: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+        if self.created_at is None:
+            self.created_at = datetime.now(timezone.utc)
+        if self.updated_at is None:
+            self.updated_at = self.created_at
+
+
+# WebSocket/SocketIO types
+@dataclass
+class SocketMessage:
+    """WebSocket/SocketIO message."""
+
+    event: str
+    data: Any
+    room: Optional[str] = None
+    namespace: Optional[str] = None
+    sid: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Health monitoring types
+@dataclass
+class HealthCheck:
+    """Health check result."""
+
+    service_name: str
+    status: HealthStatus
+    message: str
+    timestamp: datetime
+    metrics: Optional[Dict[str, Any]] = None
+    checks: Optional[Dict[str, bool]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metrics is None:
+            self.metrics = {}
+        if self.checks is None:
+            self.checks = {}
+
+
+# Project analysis types
+@dataclass
+class ProjectCharacteristics:
+    """Analyzed project characteristics."""
+
+    path: Path
+    name: str
+    type: str  # e.g., "python", "node", "mixed"
+    technologies: List[str]
+    entry_points: List[Path]
+    structure: Dict[str, Any]
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Error types
+class ErrorSeverity(Enum):
+    """Error severity levels."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class ErrorContext:
+    """Context for error handling."""
+
+    error: Exception
+    severity: ErrorSeverity
+    component: str
+    operation: str
+    timestamp: datetime
+    traceback: Optional[str] = None
+    recovery_attempted: bool = False
+    metadata: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Initialize default values."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+# Type aliases for common patterns
+ConfigDict = Dict[str, Any]
+ErrorDict = Dict[str, str]
+MetricsDict = Dict[str, Union[int, float, str]]
+ValidationResult = Tuple[bool, Optional[List[str]]]