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

claude_mpm/services/subprocess_launcher_service.py

@@ -0,0 +1,322 @@
+"""Subprocess launcher service for launching Claude as a subprocess with PTY.
+
+This service handles:
+1. PTY (pseudo-terminal) creation and management
+2. Subprocess launching with proper I/O handling
+3. Terminal state management and restoration
+4. Signal handling for graceful shutdown
+5. WebSocket integration for status updates
+
+Extracted from ClaudeRunner to follow Single Responsibility Principle.
+"""
+
+import contextlib
+import os
+import pty
+import select
+import signal
+import subprocess
+import sys
+import termios
+import tty
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult, ServiceState
+from claude_mpm.services.core.interfaces import SubprocessLauncherInterface
+
+
+class SubprocessLauncherService(BaseService, SubprocessLauncherInterface):
+    """Service for launching Claude as a subprocess with PTY support."""
+
+    def __init__(self, project_logger=None, websocket_server=None):
+        """Initialize the subprocess launcher service.
+
+        Args:
+            project_logger: Optional logger for system events
+            websocket_server: Optional WebSocket server for status updates
+        """
+        super().__init__(name="subprocess_launcher_service")
+        self.project_logger = project_logger
+        self.websocket_server = websocket_server
+
+    async def _initialize(self) -> None:
+        """Initialize the service. No special initialization needed."""
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources. No cleanup needed."""
+
+    # Implementation of abstract methods from SubprocessLauncherInterface
+
+    def launch_subprocess(self, command: List[str], **kwargs) -> Dict[str, Any]:
+        """Launch a subprocess with PTY support.
+
+        Args:
+            command: Command and arguments to execute
+            **kwargs: Additional subprocess options
+
+        Returns:
+            Dictionary with subprocess information and handles
+        """
+        # For now, delegate to the existing interactive method
+        # In a full implementation, this would return process info
+        try:
+            env = kwargs.get("env", self.prepare_subprocess_environment())
+            self.launch_subprocess_interactive(command, env)
+            return {
+                "status": OperationResult.SUCCESS,
+                "command": command,
+                "method": "interactive",
+            }
+        except Exception as e:
+            return {
+                "status": OperationResult.FAILED,
+                "error": str(e),
+                "command": command,
+            }
+
+    async def launch_subprocess_async(
+        self, command: List[str], **kwargs
+    ) -> Dict[str, Any]:
+        """Launch a subprocess asynchronously with PTY support.
+
+        Args:
+            command: Command and arguments to execute
+            **kwargs: Additional subprocess options
+
+        Returns:
+            Dictionary with subprocess information and handles
+        """
+        # For async version, we'd use asyncio subprocess
+        # For now, delegate to sync version
+        return self.launch_subprocess(command, **kwargs)
+
+    def terminate_subprocess(self, process_id: str) -> bool:
+        """Terminate a running subprocess.
+
+        Args:
+            process_id: ID of the process to terminate
+
+        Returns:
+            True if termination successful
+        """
+        # This would need process tracking to be implemented
+        # For now, return False as we don't track processes
+        self.logger.warning(f"Process termination not implemented for ID: {process_id}")
+        return False
+
+    def get_subprocess_status(self, process_id: str) -> Dict[str, Any]:
+        """Get status of a running subprocess.
+
+        Args:
+            process_id: ID of the process
+
+        Returns:
+            Dictionary with process status information
+        """
+        # This would need process tracking to be implemented
+        # For now, return unknown status
+        return {
+            "process_id": process_id,
+            "status": OperationResult.UNKNOWN,
+            "message": "Process tracking not implemented",
+        }
+
+    def launch_subprocess_interactive(
+        self, cmd: List[str], env: Dict[str, str]
+    ) -> None:
+        """Launch Claude as a subprocess with PTY for interactive mode.
+
+        This method launches Claude as a subprocess when explicitly requested
+        (via --launch-method subprocess). Subprocess mode maintains the parent process,
+        which can be useful for:
+        1. Maintaining WebSocket connections and monitoring
+        2. Providing proper cleanup and error handling
+        3. Debugging and development scenarios
+
+        Uses PTY (pseudo-terminal) to maintain full interactive capabilities.
+        Response logging is handled through the hook system, not I/O interception,
+        for better performance and compatibility.
+
+        Args:
+            cmd: Command list to execute
+            env: Environment variables for the subprocess
+        """
+        # Save original terminal settings
+        original_tty = None
+        if sys.stdin.isatty():
+            original_tty = termios.tcgetattr(sys.stdin)
+
+        # Create PTY
+        master_fd, slave_fd = pty.openpty()
+
+        try:
+            # Start Claude process
+            process = subprocess.Popen(
+                cmd, stdin=slave_fd, stdout=slave_fd, stderr=slave_fd, env=env
+            )
+
+            # Close slave in parent
+            os.close(slave_fd)
+
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Claude subprocess started with PID {process.pid}",
+                    level="INFO",
+                    component="subprocess",
+                )
+
+            # Notify WebSocket clients
+            if self.websocket_server:
+                self.websocket_server.claude_status_changed(
+                    status=ServiceState.RUNNING,
+                    pid=process.pid,
+                    message="Claude subprocess started",
+                )
+
+            # Set terminal to raw mode for proper interaction
+            if sys.stdin.isatty():
+                tty.setraw(sys.stdin)
+
+            # Handle Ctrl+C gracefully
+            def signal_handler(signum, frame):
+                if process.poll() is None:
+                    process.terminate()
+                raise KeyboardInterrupt()
+
+            signal.signal(signal.SIGINT, signal_handler)
+
+            # I/O loop
+            self._handle_subprocess_io(master_fd, process)
+
+            # Wait for process to complete
+            process.wait()
+
+            # Note: Response logging is handled through the hook system
+
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Claude subprocess exited with code {process.returncode}",
+                    level="INFO",
+                    component="subprocess",
+                )
+
+            # Notify WebSocket clients
+            if self.websocket_server:
+                self.websocket_server.claude_status_changed(
+                    status=ServiceState.STOPPED,
+                    message=f"Claude subprocess exited with code {process.returncode}",
+                )
+
+        finally:
+            # Restore terminal
+            if original_tty and sys.stdin.isatty():
+                termios.tcsetattr(sys.stdin, termios.TCSADRAIN, original_tty)
+
+            # Close PTY
+            with contextlib.suppress(Exception):
+                os.close(master_fd)
+
+            # Ensure process is terminated
+            if "process" in locals() and process.poll() is None:
+                process.terminate()
+                try:
+                    process.wait(timeout=2)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait()
+
+            # End WebSocket session if in subprocess mode
+            if self.websocket_server:
+                self.websocket_server.session_ended()
+
+    def _handle_subprocess_io(self, master_fd: int, process: subprocess.Popen) -> None:
+        """Handle I/O between the subprocess and the terminal.
+
+        Args:
+            master_fd: Master file descriptor for the PTY
+            process: The subprocess instance
+        """
+        while True:
+            # Check if process is still running
+            if process.poll() is not None:
+                break
+
+            # Check for data from Claude or stdin
+            r, _, _ = select.select([master_fd, sys.stdin], [], [], 0)
+
+            if master_fd in r:
+                try:
+                    data = os.read(master_fd, 4096)
+                    if data:
+                        os.write(sys.stdout.fileno(), data)
+                        # Broadcast output to WebSocket clients
+                        if self.websocket_server:
+                            try:
+                                # Decode and send
+                                output = data.decode("utf-8", errors="replace")
+                                self.websocket_server.claude_output(output, "stdout")
+                            except Exception as e:
+                                self.logger.debug(f"Failed to broadcast output: {e}")
+                    else:
+                        break  # EOF
+                except OSError:
+                    break
+
+            if sys.stdin in r:
+                try:
+                    data = os.read(sys.stdin.fileno(), 4096)
+                    if data:
+                        os.write(master_fd, data)
+                except OSError:
+                    break
+
+    def is_subprocess_mode_available(self) -> bool:
+        """Check if subprocess mode is available on this platform.
+
+        Returns:
+            True if subprocess mode with PTY is available
+        """
+        import importlib.util
+
+        # Check if we can import required modules
+        required = ["pty", "select", "termios", "tty"]
+        return all(importlib.util.find_spec(mod) is not None for mod in required)
+
+    def create_subprocess_command(
+        self, base_cmd: List[str], additional_args: Optional[List[str]] = None
+    ) -> List[str]:
+        """Create a subprocess command with proper arguments.
+
+        Args:
+            base_cmd: Base command to execute
+            additional_args: Additional arguments to append
+
+        Returns:
+            Complete command list for subprocess execution
+        """
+        cmd = base_cmd.copy()
+        if additional_args:
+            cmd.extend(additional_args)
+        return cmd
+
+    def prepare_subprocess_environment(
+        self, base_env: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Prepare environment variables for subprocess execution.
+
+        Args:
+            base_env: Base environment variables to extend
+
+        Returns:
+            Complete environment dictionary for subprocess
+        """
+        env = os.environ.copy()
+        if base_env:
+            env.update(base_env)
+
+        # Disable telemetry for Claude Code subprocesses
+        # This ensures Claude Code doesn't send telemetry data during runtime
+        env["DISABLE_TELEMETRY"] = "1"
+
+        return env

claude_mpm/services/system_instructions_service.py

@@ -0,0 +1,270 @@
+"""System instructions service for loading and processing system instructions.
+
+This service handles:
+1. Loading system instructions from multiple sources (project, framework)
+2. Processing template variables in instructions
+3. Stripping metadata comments
+4. Creating system prompts with fallbacks
+
+Extracted from ClaudeRunner to follow Single Responsibility Principle.
+"""
+
+import re
+from datetime import datetime, timezone
+from typing import List, Optional, Tuple
+
+from claude_mpm.config.paths import paths
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.services.core.interfaces import SystemInstructionsInterface
+
+
+class SystemInstructionsService(BaseService, SystemInstructionsInterface):
+    """Service for loading and processing system instructions."""
+
+    def __init__(self, agent_capabilities_service=None):
+        """Initialize the system instructions service.
+
+        Args:
+            agent_capabilities_service: Optional service for generating agent capabilities
+        """
+        super().__init__(name="system_instructions_service")
+        self.agent_capabilities_service = agent_capabilities_service
+        self._framework_loader = None  # Cache the framework loader instance
+        self._loaded_instructions = None  # Cache loaded instructions
+
+    async def _initialize(self) -> None:
+        """Initialize the service. No special initialization needed."""
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources. No cleanup needed."""
+
+    def load_system_instructions(self, instruction_type: str = "default") -> str:
+        """Load and process system instructions from agents/INSTRUCTIONS.md.
+
+        Args:
+            instruction_type: Type of instructions to load (currently only "default" supported)
+
+        Now uses the FrameworkLoader for comprehensive instruction loading including:
+        - INSTRUCTIONS.md
+        - WORKFLOW.md
+        - MEMORY.md
+        - Actual PM memories from .claude-mpm/memories/PM.md
+        - Agent capabilities
+        - BASE_PM.md
+
+        Returns:
+            Processed system instructions string
+        """
+        try:
+            # Return cached instructions if already loaded
+            if self._loaded_instructions is not None:
+                self.logger.debug("Returning cached system instructions")
+                return self._loaded_instructions
+
+            # Create FrameworkLoader only once
+            if self._framework_loader is None:
+                from claude_mpm.core.framework_loader import FrameworkLoader
+
+                self._framework_loader = FrameworkLoader()
+                self.logger.debug("Created new FrameworkLoader instance")
+
+            # Load instructions and cache them
+            instructions = self._framework_loader.get_framework_instructions()
+
+            if instructions:
+                self._loaded_instructions = instructions
+                self.logger.info(
+                    "Loaded and cached framework instructions via FrameworkLoader"
+                )
+                return instructions
+
+            # Fallback if FrameworkLoader returns empty
+            self.logger.warning(
+                "FrameworkLoader returned empty instructions, using fallback"
+            )
+            fallback = "# System Instructions\n\nNo specific system instructions found. Using default behavior."
+            self._loaded_instructions = fallback
+            return fallback
+
+        except Exception as e:
+            self.logger.error(f"Failed to load system instructions: {e}")
+            fallback = "# System Instructions\n\nError loading system instructions. Using default behavior."
+            self._loaded_instructions = fallback
+            return fallback
+
+    def process_base_pm_content(self, base_pm_content: str) -> str:
+        """Process BASE_PM.md content with dynamic injections.
+
+        This method replaces template variables in BASE_PM.md with:
+        - {{AGENT_CAPABILITIES}}: List of deployed agents from .claude/agents/
+        - {{VERSION}}: Current framework version
+        - {{CURRENT_DATE}}: Today's date for temporal context
+
+        Args:
+            base_pm_content: Raw BASE_PM.md content
+
+        Returns:
+            Processed content with variables replaced
+        """
+        try:
+            # Replace agent capabilities if service is available
+            if (
+                self.agent_capabilities_service
+                and "{{AGENT_CAPABILITIES}}" in base_pm_content
+            ):
+                capabilities = self.agent_capabilities_service.generate_deployed_agent_capabilities()
+                base_pm_content = base_pm_content.replace(
+                    "{{AGENT_CAPABILITIES}}", capabilities
+                )
+
+            # Replace version
+            if "{{VERSION}}" in base_pm_content:
+                version = self._get_version()
+                base_pm_content = base_pm_content.replace("{{VERSION}}", version)
+
+            # Replace current date
+            if "{{CURRENT_DATE}}" in base_pm_content:
+                current_date = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+                base_pm_content = base_pm_content.replace(
+                    "{{CURRENT_DATE}}", current_date
+                )
+
+        except Exception as e:
+            self.logger.warning(f"Error processing BASE_PM content: {e}")
+
+        return base_pm_content
+
+    def strip_metadata_comments(self, content: str) -> str:
+        """Strip HTML metadata comments from content.
+
+        Removes comments like:
+        <!-- FRAMEWORK_VERSION: 0010 -->
+        <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
+        <!-- metadata: {...} -->
+
+        Args:
+            content: Content with potential metadata comments
+
+        Returns:
+            Content with metadata comments removed
+        """
+        try:
+            # Remove HTML comments that contain metadata keywords
+            metadata_patterns = [
+                r"<!--\s*FRAMEWORK_VERSION:.*?-->",
+                r"<!--\s*LAST_MODIFIED:.*?-->",
+                r"<!--\s*metadata:.*?-->",
+                r"<!--\s*META:.*?-->",
+                r"<!--\s*VERSION:.*?-->",
+            ]
+
+            cleaned = content
+            for pattern in metadata_patterns:
+                cleaned = re.sub(pattern, "", cleaned, flags=re.DOTALL | re.IGNORECASE)
+
+            # Remove any remaining empty lines that might result from comment removal
+            lines = cleaned.split("\n")
+            cleaned_lines = []
+            prev_empty = False
+
+            for line in lines:
+                is_empty = not line.strip()
+                if not (is_empty and prev_empty):  # Avoid consecutive empty lines
+                    cleaned_lines.append(line)
+                prev_empty = is_empty
+
+            cleaned = "\n".join(cleaned_lines)
+
+            # Also remove any leading blank lines that might result
+            return cleaned.lstrip("\n")
+
+        except Exception as e:
+            self.logger.warning(f"Error stripping metadata comments: {e}")
+            return content
+
+    def create_system_prompt(self, system_instructions: Optional[str] = None) -> str:
+        """Create the complete system prompt including instructions.
+
+        Args:
+            system_instructions: Optional pre-loaded instructions, will load if None
+
+        Returns:
+            Complete system prompt
+        """
+        if system_instructions is None:
+            system_instructions = self.load_system_instructions()
+
+        return system_instructions
+
+    def _process_base_pm_content(self, base_pm_content: str) -> str:
+        """Internal method for processing BASE_PM content."""
+        return self.process_base_pm_content(base_pm_content)
+
+    def _strip_metadata_comments(self, content: str) -> str:
+        """Internal method for stripping metadata comments."""
+        return self.strip_metadata_comments(content)
+
+    def _get_version(self) -> str:
+        """Get the current framework version.
+
+        Returns:
+            Version string or 'unknown' if not found
+        """
+        try:
+            version_file = paths.project_root / "VERSION"
+            if version_file.exists():
+                return version_file.read_text().strip()
+
+            # Try to get version from package info
+            try:
+                import claude_mpm
+
+                if hasattr(claude_mpm, "__version__"):
+                    return claude_mpm.__version__
+            except ImportError:
+                pass
+
+            return "unknown"
+
+        except Exception as e:
+            self.logger.debug(f"Could not determine version: {e}")
+            return "unknown"
+
+    def get_available_instruction_types(self) -> List[str]:
+        """Get list of available instruction types.
+
+        Returns:
+            List of available instruction type names
+        """
+        # Currently only "default" type is supported
+        return ["default"]
+
+    def validate_instructions(self, instructions: str) -> Tuple[bool, List[str]]:
+        """Validate system instructions format and content.
+
+        Args:
+            instructions: Instructions content to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        errors = []
+
+        if not instructions or not instructions.strip():
+            errors.append("Instructions cannot be empty")
+            return False, errors
+
+        # Check for basic structure
+        if len(instructions.strip()) < 10:
+            errors.append("Instructions appear to be too short")
+
+        # Check for potentially problematic content
+        if "{{" in instructions and "}}" in instructions:
+            # Check if template variables are properly processed
+            unprocessed_vars = re.findall(r"\{\{([^}]+)\}\}", instructions)
+            if unprocessed_vars:
+                errors.append(
+                    f"Unprocessed template variables found: {', '.join(unprocessed_vars)}"
+                )
+
+        return len(errors) == 0, errors