claude-mpm 4.20.3__py3-none-any.whl → 5.1.8__py3-none-any.whl

claude_mpm/core/interfaces.py

@@ -33,7 +33,62 @@ from pathlib import Path
 from typing import Any, Dict, Generic, List, Optional, Tuple, TypeVar
 
 # Re-export everything from the new location for backward compatibility
-from claude_mpm.services.core.interfaces import *
+from claude_mpm.services.core.interfaces import (  # noqa: F401
+    AgentCapabilitiesInterface,
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    CommandHandlerInterface,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    ICrashDetector,
+    IDeploymentStateManager,
+    IErrorHandler,
+    IEventBus,
+    IHealthCheck,
+    IHealthCheckManager,
+    IHealthMonitor,
+    ILocalProcessManager,
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IModelProvider,
+    IModelRouter,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IResourceMonitor,
+    IRestartManager,
+    IRestartPolicy,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryHookInterface,
+    MemoryServiceInterface,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+    ProjectAnalyzerInterface,
+    RunnerConfigurationInterface,
+    ServiceType,
+    SessionManagementInterface,
+    SocketIOServiceInterface,
+    SubprocessLauncherInterface,
+    SystemInstructionsInterface,
+    T,
+    TemplateRenderContext,
+    TicketManagerInterface,
+    UtilityServiceInterface,
+    VersionServiceInterface,
+)
 
 # Type variables for generic interfaces
 T = TypeVar("T")

claude_mpm/core/logger.py

@@ -225,7 +225,9 @@ def setup_logging(
 
             # Use rotating file handler
             file_handler = logging.handlers.RotatingFileHandler(
-                log_file, maxBytes=10 * 1024 * 1024, backupCount=5  # 10 MB
+                log_file,
+                maxBytes=10 * 1024 * 1024,
+                backupCount=5,  # 10 MB
             )
         else:
             # Use default log directory

claude_mpm/core/oneshot_session.py

@@ -2,19 +2,32 @@
 
 This module encapsulates the logic for running one-time Claude commands,
 breaking down the monolithic run_oneshot method into focused, testable components.
+
+DEPENDENCY INJECTION:
+This module uses protocol-based dependency injection to break circular imports.
+Instead of importing ClaudeRunner directly, it uses ClaudeRunnerProtocol which
+defines the interface it needs.
 """
 
 import contextlib
 import os
 import subprocess
+import tempfile
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 from claude_mpm.core.enums import OperationResult, ServiceState
 from claude_mpm.core.logger import get_logger
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class OneshotSession:
     """Manages a single oneshot Claude execution session.
@@ -26,17 +39,18 @@ class OneshotSession:
     complexity < 10 and lines < 80, making the code easier to test and modify.
     """
 
-    def __init__(self, runner):
+    def __init__(self, runner: "ClaudeRunnerProtocol"):
         """Initialize the oneshot session with a reference to the runner.
 
         Args:
-            runner: The ClaudeRunner instance that owns this session
+            runner: The ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
         """
-        self.runner = runner
+        self.runner: ClaudeRunnerProtocol = runner
         self.logger = get_logger("oneshot_session")
         self.start_time = None
         self.session_id = None
         self.original_cwd = None
+        self.temp_system_prompt_file = None
 
     def initialize_session(self, prompt: str) -> Tuple[bool, Optional[str]]:
         """Initialize the oneshot session.
@@ -134,7 +148,13 @@ class OneshotSession:
     def _build_final_command(
         self, prompt: str, context: Optional[str], infrastructure: Dict[str, Any]
     ) -> list:
-        """Build the final command with prompt and system instructions."""
+        """Build the final command with prompt and system instructions.
+
+        Uses file-based caching to avoid Linux ARG_MAX limits:
+        - Linux MAX_ARG_STRLEN: 128 KB per argument
+        - System prompt size: ~138.7 KB (exceeds limit by 7.7 KB)
+        - Solution: Write to temp file, pass file path (~60 bytes)
+        """
         full_prompt = f"{context}\n\n{prompt}" if context else prompt
         cmd = infrastructure["cmd"] + ["--print", full_prompt]
 
@@ -148,9 +168,38 @@ class OneshotSession:
                 self.logger.warning("System prompt contains Python code references!")
 
         if system_prompt and system_prompt != self._get_simple_context():
-            # The problem might be with insert positioning
-            # Let's add system prompt differently
-            cmd.extend(["--append-system-prompt", system_prompt])
+            # Use file-based loading to avoid ARG_MAX limits (1M-485)
+            # Create temp file for system prompt
+            try:
+                # Create temp file in system temp directory
+                temp_fd, temp_path = tempfile.mkstemp(
+                    suffix=".md", prefix="claude_mpm_system_prompt_"
+                )
+
+                # Write system prompt to temp file
+                with os.fdopen(temp_fd, "w", encoding="utf-8") as f:
+                    f.write(system_prompt)
+
+                # Store temp file path for cleanup
+                self.temp_system_prompt_file = temp_path
+
+                # Use --system-prompt-file flag (matches interactive mode pattern)
+                cmd.extend(["--system-prompt-file", temp_path])
+
+                # User-visible notification
+                print(f"📄 Reading system prompt from: {temp_path}")
+
+                self.logger.info(
+                    f"Using file-based system prompt loading: {temp_path} "
+                    f"({len(system_prompt) / 1024:.1f} KB)"
+                )
+
+            except Exception as e:
+                # Fallback to inline if file creation fails
+                self.logger.warning(
+                    f"Failed to create temp file for system prompt, using inline: {e}"
+                )
+                cmd.extend(["--append-system-prompt", system_prompt])
 
         return cmd
 
@@ -203,6 +252,20 @@ class OneshotSession:
 
     def cleanup_session(self) -> None:
         """Clean up the session and restore state."""
+        # Clean up temp system prompt file
+        if self.temp_system_prompt_file:
+            try:
+                temp_file_path = Path(self.temp_system_prompt_file)
+                if temp_file_path.exists():
+                    temp_file_path.unlink()
+                    self.logger.debug(
+                        f"Cleaned up temp system prompt file: {self.temp_system_prompt_file}"
+                    )
+            except Exception as e:
+                self.logger.warning(f"Failed to clean up temp system prompt file: {e}")
+            finally:
+                self.temp_system_prompt_file = None
+
         # Restore original working directory
         if self.original_cwd:
             with contextlib.suppress(Exception):
@@ -268,8 +331,47 @@ class OneshotSession:
         if self.runner.claude_args:
             cmd.extend(self.runner.claude_args)
 
+        # Add --agents flag if native agents mode is enabled
+        if getattr(self.runner, "use_native_agents", False):
+            agents_flag = self._build_agents_flag()
+            if agents_flag:
+                cmd.extend(agents_flag)
+                self.logger.info("✓ Native agents mode: Using --agents CLI flag")
+
         return cmd
 
+    def _build_agents_flag(self) -> Optional[list]:
+        """Build --agents flag with all MPM agents.
+
+        Returns:
+            List with ["--agents", "<json>"] or None if conversion fails
+        """
+        try:
+            from claude_mpm.services.native_agent_converter import NativeAgentConverter
+
+            converter = NativeAgentConverter()
+            agents = converter.load_agents_from_templates()
+
+            if not agents:
+                self.logger.warning("No agents loaded for native mode")
+                return None
+
+            # Generate JSON for --agents flag
+            agents_json = converter.generate_agents_json(agents)
+            summary = converter.get_conversion_summary(agents)
+
+            self.logger.info(
+                f"Native agents: {summary['total_agents']} agents, "
+                f"{summary['json_size_kb']} KB JSON"
+            )
+
+            # Return as list: ["--agents", "<json>"]
+            return ["--agents", agents_json]
+
+        except Exception as e:
+            self.logger.error(f"Failed to build --agents flag: {e}", exc_info=True)
+            return None
+
     def _handle_successful_response(self, response: str, prompt: str) -> None:
         """Process a successful Claude response."""
         print(response)

claude_mpm/core/protocols/__init__.py

@@ -0,0 +1,23 @@
+"""Protocol interfaces for dependency injection.
+
+This module defines Protocol interfaces to break circular dependencies
+using Python's typing.Protocol feature for structural subtyping.
+"""
+
+from claude_mpm.core.protocols.runner_protocol import (
+    ClaudeRunnerProtocol,
+    SystemPromptProvider,
+)
+from claude_mpm.core.protocols.session_protocol import (
+    InteractiveSessionProtocol,
+    OneshotSessionProtocol,
+    SessionManagementProtocol,
+)
+
+__all__ = [
+    "ClaudeRunnerProtocol",
+    "InteractiveSessionProtocol",
+    "OneshotSessionProtocol",
+    "SessionManagementProtocol",
+    "SystemPromptProvider",
+]

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/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/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/unified_config.py

@@ -218,6 +218,27 @@ class DevelopmentConfig(BaseModel):
     )
 
 
+class DocumentationConfig(BaseModel):
+    """Documentation routing and management configuration."""
+
+    docs_path: str = Field(
+        default="docs/research/",
+        description="Default path for session documentation (relative to project root)",
+    )
+    attach_to_tickets: bool = Field(
+        default=True,
+        description="Attach work products to tickets when ticket context exists",
+    )
+    backup_locally: bool = Field(
+        default=True,
+        description="Always create local backup copies of documentation",
+    )
+    enable_ticket_detection: bool = Field(
+        default=True,
+        description="Enable automatic ticket context detection from user messages",
+    )
+
+
 class UnifiedConfig(BaseSettings):
     """
     Unified configuration model for Claude MPM.
@@ -242,6 +263,7 @@ class UnifiedConfig(BaseSettings):
     performance: PerformanceConfig = Field(default_factory=PerformanceConfig)
     sessions: SessionConfig = Field(default_factory=SessionConfig)
     development: DevelopmentConfig = Field(default_factory=DevelopmentConfig)
+    documentation: DocumentationConfig = Field(default_factory=DocumentationConfig)
 
     # Path configuration
     base_path: Optional[Path] = Field(