claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

claude_mpm/core/protocols/runner_protocol.py

@@ -0,0 +1,103 @@
+"""Protocol definitions for ClaudeRunner dependencies.
+
+These protocols use Python's typing.Protocol for structural subtyping,
+allowing dependency injection without circular imports.
+"""
+
+from pathlib import Path
+from typing import Any, Optional, Protocol
+
+
+class SystemPromptProvider(Protocol):
+    """Protocol for providing system prompts without circular dependency.
+
+    This protocol allows InteractiveSession to get system prompts without
+    directly importing ClaudeRunner, breaking the circular dependency.
+    """
+
+    def _create_system_prompt(self) -> str:
+        """Create the complete system prompt including instructions.
+
+        Returns:
+            Complete system prompt as string
+        """
+        ...
+
+
+class ClaudeRunnerProtocol(Protocol):
+    """Protocol defining the interface InteractiveSession needs from ClaudeRunner.
+
+    This protocol breaks the circular dependency between InteractiveSession
+    and ClaudeRunner by defining only the methods that InteractiveSession
+    actually uses, without requiring the full ClaudeRunner import.
+
+    Design Decision: Uses Protocol instead of ABC to allow structural subtyping.
+    This means ClaudeRunner doesn't need to explicitly inherit from this protocol,
+    it just needs to implement these methods with matching signatures.
+    """
+
+    # Configuration attributes
+    enable_websocket: bool
+    enable_tickets: bool
+    log_level: str
+    claude_args: Optional[list]
+    launch_method: str
+    websocket_port: int
+    use_native_agents: bool
+    config: Any
+    session_log_file: Optional[Path]
+
+    # Service references
+    project_logger: Any
+    websocket_server: Any
+    command_handler_service: Any
+    subprocess_launcher_service: Any
+
+    def setup_agents(self) -> bool:
+        """Deploy native agents to .claude/agents/.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def deploy_project_agents_to_claude(self) -> bool:
+        """Deploy project agents from .claude-mpm/agents/ to .claude/agents/.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def _create_system_prompt(self) -> str:
+        """Create the complete system prompt including instructions.
+
+        Returns:
+            Complete system prompt as string
+        """
+        ...
+
+    def _get_version(self) -> str:
+        """Get version string.
+
+        Returns:
+            Version string
+        """
+        ...
+
+    def _log_session_event(self, event_data: dict) -> None:
+        """Log an event to the session log file.
+
+        Args:
+            event_data: Event data to log
+        """
+        ...
+
+    def _launch_subprocess_interactive(self, cmd: list, env: dict) -> None:
+        """Launch Claude as a subprocess with PTY for interactive mode.
+
+        Args:
+            cmd: Command to execute
+            env: Environment variables
+        """
+        ...

claude_mpm/core/protocols/session_protocol.py

@@ -0,0 +1,131 @@
+"""Protocol definitions for session management dependencies.
+
+These protocols use Python's typing.Protocol for structural subtyping,
+allowing dependency injection without circular imports.
+"""
+
+from typing import Any, Dict, Optional, Protocol, Tuple
+
+
+class InteractiveSessionProtocol(Protocol):
+    """Protocol for interactive session orchestration.
+
+    This protocol defines the interface that SessionManagementService
+    needs from InteractiveSession without requiring a full import.
+    """
+
+    def initialize_interactive_session(self) -> Tuple[bool, Optional[str]]:
+        """Initialize the interactive session environment.
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        ...
+
+    def setup_interactive_environment(self) -> Tuple[bool, Dict[str, Any]]:
+        """Set up the interactive environment including agents and commands.
+
+        Returns:
+            Tuple of (success, environment_dict)
+        """
+        ...
+
+    def handle_interactive_input(self, environment: Dict[str, Any]) -> bool:
+        """Handle the interactive input/output loop.
+
+        Args:
+            environment: Dictionary with command, env vars, and session info
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def cleanup_interactive_session(self) -> None:
+        """Clean up resources after interactive session ends."""
+        ...
+
+
+class OneshotSessionProtocol(Protocol):
+    """Protocol for oneshot session orchestration.
+
+    This protocol defines the interface that SessionManagementService
+    needs from OneshotSession without requiring a full import.
+    """
+
+    def initialize_session(self, prompt: str) -> Tuple[bool, Optional[str]]:
+        """Initialize the oneshot session.
+
+        Args:
+            prompt: The command or prompt to execute
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        ...
+
+    def deploy_agents(self) -> bool:
+        """Deploy agents for the session.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def setup_infrastructure(self) -> Dict[str, Any]:
+        """Set up session infrastructure.
+
+        Returns:
+            Dictionary with infrastructure configuration
+        """
+        ...
+
+    def execute_command(
+        self, prompt: str, context: Optional[str], infrastructure: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """Execute the command with given context and infrastructure.
+
+        Args:
+            prompt: Command to execute
+            context: Optional context
+            infrastructure: Infrastructure configuration
+
+        Returns:
+            Tuple of (success, response)
+        """
+        ...
+
+    def cleanup_session(self) -> None:
+        """Clean up session resources."""
+        ...
+
+
+class SessionManagementProtocol(Protocol):
+    """Protocol for session management service.
+
+    This protocol defines the interface that ClaudeRunner needs from
+    SessionManagementService without requiring a full import.
+    """
+
+    def run_interactive_session(self, initial_context: Optional[str] = None) -> bool:
+        """Run Claude in interactive mode.
+
+        Args:
+            initial_context: Optional initial context to pass to Claude
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    def run_oneshot_session(self, prompt: str, context: Optional[str] = None) -> bool:
+        """Run Claude with a single prompt.
+
+        Args:
+            prompt: The command or prompt to execute
+            context: Optional context to prepend to the prompt
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...

claude_mpm/core/service_registry.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union
 from .base_service import BaseService
 from .config import Config
 from .container import DIContainer, ServiceLifetime, get_container
+from .enums import OperationResult
 from .logger import get_logger
 from .shared.config_loader import ConfigLoader
 
@@ -160,10 +161,10 @@ class ServiceRegistry:
             try:
                 # Use the enhanced container's named resolution
                 return self.container.get(BaseService, name=service_type)
-            except:
+            except Exception as e:
                 # Fall back to looking up class and resolving
                 if service_type not in self._services:
-                    raise KeyError(f"Service '{service_type}' not registered")
+                    raise KeyError(f"Service '{service_type}' not registered") from e
                 service_class = self._services[service_type]
                 return self.container.get(service_class)
         else:
@@ -249,7 +250,10 @@ class ServiceRegistry:
                                 "metrics": health.metrics,
                             }
                 except Exception as e:
-                    health_status[name] = {"status": "error", "message": str(e)}
+                    health_status[name] = {
+                        "status": OperationResult.ERROR,
+                        "message": str(e),
+                    }
 
             return health_status
 

claude_mpm/core/session_manager.py

@@ -4,7 +4,7 @@ import gzip
 import json
 import shutil
 import uuid
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -41,8 +41,8 @@ class SessionManager:
         self.active_sessions[session_id] = {
             "id": session_id,
             "context": context,
-            "created_at": datetime.now().isoformat(),
-            "last_used": datetime.now().isoformat(),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "last_used": datetime.now(timezone.utc).isoformat(),
             "use_count": 0,
             "agents_run": [],
         }
@@ -65,7 +65,7 @@ class SessionManager:
             Session ID
         """
         # Look for existing session in context
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         max_age = timedelta(minutes=max_age_minutes)
 
         for session_id, session_data in self.active_sessions.items():
@@ -95,10 +95,12 @@ class SessionManager:
                 {
                     "agent": agent,
                     "task": task[:100],  # Truncate long tasks
-                    "timestamp": datetime.now().isoformat(),
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
                 }
             )
-            self.active_sessions[session_id]["last_used"] = datetime.now().isoformat()
+            self.active_sessions[session_id]["last_used"] = datetime.now(
+                timezone.utc
+            ).isoformat()
             self._save_sessions()
 
     def cleanup_old_sessions(self, max_age_hours: int = 24, archive: bool = True):
@@ -111,7 +113,7 @@ class SessionManager:
             max_age_hours: Maximum age in hours
             archive: Whether to archive sessions before removing
         """
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         max_age = timedelta(hours=max_age_hours)
 
         expired = []
@@ -185,7 +187,7 @@ class SessionManager:
         """Save sessions to disk."""
         session_file = self.session_dir / "active_sessions.json"
         try:
-            with open(session_file, "w") as f:
+            with session_file.open("w") as f:
                 json.dump(self.active_sessions, f, indent=2)
         except Exception as e:
             logger.error(f"Failed to save sessions: {e}")
@@ -195,7 +197,7 @@ class SessionManager:
         session_file = self.session_dir / "active_sessions.json"
         if session_file.exists():
             try:
-                with open(session_file) as f:
+                with session_file.open() as f:
                     self.active_sessions = json.load(f)
 
                 # Clean up old sessions on load (archive by default)
@@ -223,7 +225,7 @@ class SessionManager:
         archive_dir.mkdir(parents=True, exist_ok=True)
 
         # Create timestamped archive file
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
         archive_name = f"sessions_archive_{timestamp}.json.gz"
         archive_path = archive_dir / archive_name
 
@@ -279,12 +281,12 @@ class SessionManager:
             archive_dir = Path.home() / ".claude-mpm" / "archives"
             archive_dir.mkdir(parents=True, exist_ok=True)
 
-            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
             backup_name = f"claude_json_backup_{timestamp}.json.gz"
             backup_path = archive_dir / backup_name
 
             # Compress and backup current file
-            with open(claude_json_path, "rb") as f_in:
+            with claude_json_path.open("rb") as f_in:
                 with gzip.open(backup_path, "wb") as f_out:
                     shutil.copyfileobj(f_in, f_out)
 

claude_mpm/core/shared/config_loader.py

@@ -228,7 +228,7 @@ class ConfigLoader:
         try:
             import yaml
 
-            with open(config_file) as f:
+            with config_file.open() as f:
                 if config_file.suffix.lower() in (".yaml", ".yml"):
                     return yaml.safe_load(f) or {}
                 # Try JSON as fallback

claude_mpm/core/shared/singleton_manager.py

@@ -16,11 +16,14 @@ class SingletonManager:
 
     Reduces duplication by providing thread-safe singleton patterns
     that can be used across different classes.
+
+    Uses RLock (reentrant locks) to support recursive calls from
+    SingletonMixin.__new__ and @singleton decorator patterns.
     """
 
     _instances: Dict[Type, Any] = {}
-    _locks: Dict[Type, threading.Lock] = {}
-    _global_lock = threading.Lock()
+    _locks: Dict[Type, threading.RLock] = {}
+    _global_lock = threading.RLock()
 
     @classmethod
     def get_instance(
@@ -42,7 +45,7 @@ class SingletonManager:
         if singleton_class not in cls._locks:
             with cls._global_lock:
                 if singleton_class not in cls._locks:
-                    cls._locks[singleton_class] = threading.Lock()
+                    cls._locks[singleton_class] = threading.RLock()
 
         # Get instance with class-specific lock
         with cls._locks[singleton_class]:
@@ -50,9 +53,13 @@ class SingletonManager:
                 logger = get_logger("singleton_manager")
                 logger.debug(f"Creating singleton instance: {singleton_class.__name__}")
 
-                instance = singleton_class(*args, **kwargs)
+                # Use object.__new__ to bypass SingletonMixin.__new__ and avoid recursion
+                instance = object.__new__(singleton_class)
                 cls._instances[singleton_class] = instance
 
+                # Now call __init__ explicitly with the stored instance
+                instance.__init__(*args, **kwargs)
+
                 return instance
 
             return cls._instances[singleton_class]

claude_mpm/core/socketio_pool.py

@@ -17,7 +17,7 @@ import threading
 import time
 from collections import defaultdict, deque
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from enum import Enum
 from typing import Any, Deque, Dict, List, Optional
 
@@ -97,11 +97,9 @@ class CircuitBreaker:
             return True
         if self.state == CircuitState.OPEN:
             # Check if recovery timeout has passed
-            if (
-                self.last_failure_time
-                and datetime.now() - self.last_failure_time
-                > timedelta(seconds=self.recovery_timeout)
-            ):
+            if self.last_failure_time and datetime.now(
+                timezone.utc
+            ) - self.last_failure_time > timedelta(seconds=self.recovery_timeout):
                 self.state = CircuitState.HALF_OPEN
                 self.logger.info(
                     "Circuit breaker transitioning to HALF_OPEN for testing"
@@ -127,7 +125,7 @@ class CircuitBreaker:
     def record_failure(self):
         """Record failed execution."""
         self.failure_count += 1
-        self.last_failure_time = datetime.now()
+        self.last_failure_time = datetime.now(timezone.utc)
 
         if self.state == CircuitState.HALF_OPEN:
             # Test failed, go back to OPEN
@@ -184,7 +182,7 @@ class SocketIOConnectionPool:
         # Health monitoring
         self.health_thread = None
         self.health_running = False
-        self.last_health_check = datetime.now()
+        self.last_health_check = datetime.now(timezone.utc)
 
         # Server configuration
         self.server_url = None
@@ -311,7 +309,7 @@ class SocketIOConnectionPool:
                         self.server_url = f"http://localhost:{port}"
                         self.logger.debug(f"Detected Socket.IO server on port {port}")
                         return
-            except:
+            except Exception:
                 continue
 
         # Fall back to default
@@ -375,7 +373,7 @@ class SocketIOConnectionPool:
                 # Check if connection is still valid
                 for conn_id, stats in self.connection_stats.items():
                     if stats.is_connected:
-                        stats.last_used = datetime.now()
+                        stats.last_used = datetime.now(timezone.utc)
                         return client
 
             # Create new connection if under limit
@@ -581,7 +579,7 @@ class SocketIOConnectionPool:
                     loop.stop()
                     loop.run_until_complete(loop.shutdown_asyncgens())
                     loop.close()
-                except:
+                except Exception:
                     pass
 
     async def _connect_client(self, client: socketio.AsyncClient):
@@ -596,9 +594,9 @@ class SocketIOConnectionPool:
                 timeout=2.0,
             )
 
-        except asyncio.TimeoutError:
+        except asyncio.TimeoutError as e:
             self.logger.debug("Socket.IO connection timeout")
-            raise TimeoutError("Socket.IO connection timeout")
+            raise TimeoutError("Socket.IO connection timeout") from e
         except Exception as e:
             self.logger.debug(f"Client connection failed: {e}")
             raise
@@ -623,7 +621,7 @@ class SocketIOConnectionPool:
                 self._check_connections_health()
 
                 # Update last health check time
-                self.last_health_check = datetime.now()
+                self.last_health_check = datetime.now(timezone.utc)
 
             except Exception as e:
                 self.logger.error(f"Health monitor error: {e}")
@@ -655,7 +653,9 @@ class SocketIOConnectionPool:
                     continue
 
                 # 3. Connection idle for too long (>5 minutes)
-                idle_time = (datetime.now() - stats.last_used).total_seconds()
+                idle_time = (
+                    datetime.now(timezone.utc) - stats.last_used
+                ).total_seconds()
                 if idle_time > 300 and conn_id not in [
                     id for id, _ in enumerate(self.available_connections)
                 ]:

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,9 +1,10 @@
 """Tool access control system for managing which tools agents can use."""
 
-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:

claude_mpm/core/types.py

@@ -16,10 +16,12 @@ Module-specific types should remain in their respective modules.
 """
 
 from dataclasses import dataclass
-from datetime import datetime
+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
@@ -206,7 +208,7 @@ class TaskInfo:
         if self.metadata is None:
             self.metadata = {}
         if self.created_at is None:
-            self.created_at = datetime.now()
+            self.created_at = datetime.now(timezone.utc)
         if self.updated_at is None:
             self.updated_at = self.created_at
 
@@ -230,15 +232,6 @@ class SocketMessage:
 
 
 # Health monitoring types
-class HealthStatus(Enum):
-    """Service health status levels."""
-
-    HEALTHY = "healthy"
-    DEGRADED = "degraded"
-    UNHEALTHY = "unhealthy"
-    UNKNOWN = "unknown"
-
-
 @dataclass
 class HealthCheck:
     """Health check result."""

claude_mpm/core/typing_utils.py

@@ -32,6 +32,8 @@ from typing import (
 
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
+from claude_mpm.core.enums import OperationResult, ServiceState
+
 # Generic type variables
 T = TypeVar("T")
 TSession = TypeVar("TSession")  # Generic session type
@@ -42,15 +44,14 @@ TService = TypeVar("TService")  # Generic service type
 PathLike: TypeAlias = Union[str, Path]
 JSONValue: TypeAlias = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]
 JSONDict: TypeAlias = Dict[str, JSONValue]
+
 Headers: TypeAlias = Dict[str, str]
 ErrorCode: TypeAlias = Union[int, str]
 LogLevel: TypeAlias = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 # Session types
 SessionId: TypeAlias = str
-SessionStatus: TypeAlias = Literal[
-    "initializing", "running", "stopped", "error", "completed"
-]
+SessionStatus: TypeAlias = ServiceState  # Replaced Literal with ServiceState enum
 LaunchMethod: TypeAlias = Literal["exec", "subprocess", "oneshot"]
 
 
@@ -152,7 +153,7 @@ class WebSocketMessage(TypedDict):
 class ClaudeStatus(TypedDict):
     """Claude process status."""
 
-    status: Literal["starting", "running", "stopped", "error"]
+    status: ServiceState  # Replaced Literal with ServiceState enum
     message: str
     timestamp: NotRequired[datetime]
     pid: NotRequired[int]
@@ -163,7 +164,7 @@ class DelegationInfo(TypedDict):
 
     agent: AgentId
     task: str
-    status: Literal["detected", "started", "completed", "failed"]
+    status: OperationResult  # Replaced Literal with OperationResult enum
     timestamp: NotRequired[datetime]
     result: NotRequired[str]
 
@@ -194,7 +195,7 @@ class HookContext(TypedDict):
 
 # Service types
 ServiceName: TypeAlias = str
-ServiceStatus: TypeAlias = Literal["idle", "running", "stopped", "error"]
+ServiceStatus: TypeAlias = ServiceState  # Replaced Literal with ServiceState enum
 
 
 class ServiceConfig(TypedDict):