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

claude_mpm/core/framework/loaders/file_loader.py

@@ -66,6 +66,53 @@ class FileLoader:
             if "INSTRUCTIONS.md" in str(file_path):
                 self.framework_last_modified = timestamp
 
+    def _load_tier_file(
+        self,
+        filename: str,
+        current_dir: Path,
+        framework_path: Optional[Path] = None,
+        include_system: bool = False,
+    ) -> tuple[Optional[str], Optional[str]]:
+        """Load file with tier precedence: project → user → system.
+
+        Args:
+            filename: Name of file to load (e.g., "INSTRUCTIONS.md")
+            current_dir: Current working directory for project-level
+            framework_path: Path to framework installation for system-level
+            include_system: Whether to check system-level path
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        # Check project-level (highest priority)
+        project_path = current_dir / ".claude-mpm" / filename
+        if project_path.exists():
+            loaded_content = self.try_load_file(
+                project_path, f"project-specific {filename}"
+            )
+            if loaded_content:
+                self.logger.info(f"Using project-specific {filename} from .claude-mpm/")
+                return loaded_content, "project"
+
+        # Check user-level (medium priority)
+        user_path = Path.home() / ".claude-mpm" / filename
+        if user_path.exists():
+            loaded_content = self.try_load_file(user_path, f"user-specific {filename}")
+            if loaded_content:
+                self.logger.info(f"Using user-specific {filename} from ~/.claude-mpm/")
+                return loaded_content, "user"
+
+        # Check system-level (lowest priority)
+        if include_system and framework_path and framework_path != Path("__PACKAGED__"):
+            system_path = framework_path / "src" / "claude_mpm" / "agents" / filename
+            if system_path.exists():
+                loaded_content = self.try_load_file(system_path, f"system {filename}")
+                if loaded_content:
+                    self.logger.info(f"Using system {filename}")
+                    return loaded_content, "system"
+
+        return None, None
+
     def load_instructions_file(
         self, current_dir: Path
     ) -> tuple[Optional[str], Optional[str]]:
@@ -82,31 +129,7 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', or None
         """
-        # Check for project-specific INSTRUCTIONS.md first
-        project_instructions_path = current_dir / ".claude-mpm" / "INSTRUCTIONS.md"
-        if project_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                project_instructions_path, "project-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific INSTRUCTIONS.md
-        user_instructions_path = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
-        if user_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                user_instructions_path, "user-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "user"
-
-        return None, None
+        return self._load_tier_file("INSTRUCTIONS.md", current_dir)
 
     def load_workflow_file(
         self, current_dir: Path, framework_path: Path
@@ -126,44 +149,9 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific WORKFLOW.md first (highest priority)
-        project_workflow_path = current_dir / ".claude-mpm" / "WORKFLOW.md"
-        if project_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                project_workflow_path, "project-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific WORKFLOW.md (medium priority)
-        user_workflow_path = Path.home() / ".claude-mpm" / "WORKFLOW.md"
-        if user_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                user_workflow_path, "user-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system workflow (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_workflow_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "WORKFLOW.md"
-            )
-            if system_workflow_path.exists():
-                loaded_content = self.try_load_file(
-                    system_workflow_path, "system WORKFLOW.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system workflow instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "WORKFLOW.md", current_dir, framework_path, include_system=True
+        )
 
     def load_memory_file(
         self, current_dir: Path, framework_path: Path
@@ -183,41 +171,6 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific MEMORY.md first (highest priority)
-        project_memory_path = current_dir / ".claude-mpm" / "MEMORY.md"
-        if project_memory_path.exists():
-            loaded_content = self.try_load_file(
-                project_memory_path, "project-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific memory instructions from .claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific MEMORY.md (medium priority)
-        user_memory_path = Path.home() / ".claude-mpm" / "MEMORY.md"
-        if user_memory_path.exists():
-            loaded_content = self.try_load_file(
-                user_memory_path, "user-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system memory instructions (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_memory_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "MEMORY.md"
-            )
-            if system_memory_path.exists():
-                loaded_content = self.try_load_file(
-                    system_memory_path, "system MEMORY.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system memory instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "MEMORY.md", current_dir, framework_path, include_system=True
+        )

claude_mpm/core/framework/loaders/instruction_loader.py

@@ -91,10 +91,28 @@ class InstructionLoader:
     def _load_filesystem_framework_instructions(self, content: Dict[str, Any]) -> None:
         """Load framework instructions from filesystem.
 
+        Priority order:
+        1. Deployed compiled file: .claude-mpm/PM_INSTRUCTIONS_DEPLOYED.md (HIGHEST PRIORITY)
+        2. Source file (development): src/claude_mpm/agents/PM_INSTRUCTIONS.md
+        3. Legacy file (backward compat): src/claude_mpm/agents/INSTRUCTIONS.md
+
         Args:
             content: Dictionary to update with framework instructions
         """
-        # Try new consolidated PM_INSTRUCTIONS.md first, fall back to INSTRUCTIONS.md
+        # PRIORITY 1: Check for compiled/deployed version in .claude-mpm/
+        # This is the merged PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md
+        deployed_path = self.current_dir / ".claude-mpm" / "PM_INSTRUCTIONS_DEPLOYED.md"
+        if deployed_path.exists():
+            loaded_content = self.file_loader.try_load_file(
+                deployed_path, "deployed PM_INSTRUCTIONS_DEPLOYED.md"
+            )
+            if loaded_content:
+                content["framework_instructions"] = loaded_content
+                content["loaded"] = True
+                self.logger.info("Loaded PM_INSTRUCTIONS_DEPLOYED.md from .claude-mpm/")
+                return  # Stop here - deployed version takes precedence
+
+        # PRIORITY 2: Development mode - load from source PM_INSTRUCTIONS.md
         pm_instructions_path = (
             self.framework_path / "src" / "claude_mpm" / "agents" / "PM_INSTRUCTIONS.md"
         )
@@ -102,16 +120,18 @@ class InstructionLoader:
             self.framework_path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md"
         )
 
-        # Try loading new consolidated file first
+        # Try loading new consolidated file
         if pm_instructions_path.exists():
             loaded_content = self.file_loader.try_load_file(
-                pm_instructions_path, "consolidated PM_INSTRUCTIONS.md"
+                pm_instructions_path, "source PM_INSTRUCTIONS.md (development mode)"
             )
             if loaded_content:
                 content["framework_instructions"] = loaded_content
                 content["loaded"] = True
-                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md")
-        # Fall back to legacy file for backward compatibility
+                self.logger.warning(
+                    "Using source PM_INSTRUCTIONS.md - deployed version not found"
+                )
+        # PRIORITY 3: Fall back to legacy file for backward compatibility
         elif framework_instructions_path.exists():
             loaded_content = self.file_loader.try_load_file(
                 framework_instructions_path, "framework INSTRUCTIONS.md (legacy)"

claude_mpm/core/interactive_session.py

@@ -2,6 +2,12 @@
 
 This module provides the InteractiveSession class that manages Claude's interactive mode
 with proper separation of concerns and reduced complexity.
+
+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. This allows ClaudeRunner to create instances
+of InteractiveSession without circular dependency issues.
 """
 
 import contextlib
@@ -9,11 +15,18 @@ import os
 import subprocess
 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 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 InteractiveSession:
     """
@@ -28,13 +41,14 @@ class InteractiveSession:
     and makes testing easier while preserving all original functionality.
     """
 
-    def __init__(self, runner):
+    def __init__(self, runner: "ClaudeRunnerProtocol"):
         """Initialize interactive session handler.
 
         Args:
-            runner: ClaudeRunner instance with all necessary services
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
+                    with all necessary services
         """
-        self.runner = runner
+        self.runner: ClaudeRunnerProtocol = runner
         self.logger = get_logger("interactive_session")
         self.session_id = None
         self.original_cwd = Path.cwd()
@@ -396,12 +410,74 @@ class InteractiveSession:
                 cmd.extend(agents_flag)
                 self.logger.info("✓ Native agents mode: Using --agents CLI flag")
 
-        # Add system instructions
-        from claude_mpm.core.claude_runner import create_simple_context
+        # Add system instructions with file-based caching
+        from claude_mpm.core.system_context import create_simple_context
+        from claude_mpm.services.instructions.instruction_cache_service import (
+            InstructionCacheService,
+        )
 
         system_prompt = self.runner._create_system_prompt()
         if system_prompt and system_prompt != create_simple_context():
-            cmd.extend(["--append-system-prompt", system_prompt])
+            # Try to use cached instruction file for better performance
+            try:
+                # Initialize cache service with project root
+                if "CLAUDE_MPM_USER_PWD" in os.environ:
+                    project_root = Path(os.environ["CLAUDE_MPM_USER_PWD"])
+                else:
+                    project_root = Path.cwd()
+
+                # Instruction Caching (1M-446)
+                # Cache assembled instructions to file to avoid ARG_MAX limits on Linux/Windows.
+                # - Linux: 128 KB limit, instructions are ~152 KB (exceeds by 19.1%)
+                # - Windows: 32 KB limit (exceeds by 476%)
+                # Cache updates only when content hash changes (hash-based invalidation).
+                # Fallback to inline instruction if cache fails (graceful degradation).
+                cache_service = InstructionCacheService(project_root=project_root)
+
+                # Update cache with assembled instruction content
+                cache_result = cache_service.update_cache(
+                    instruction_content=system_prompt
+                )
+
+                # Use cache file if available
+                if (
+                    cache_result.get("updated")
+                    or cache_service.get_cache_path().exists()
+                ):
+                    cache_file = cache_service.get_cache_path()
+
+                    # Log cache operation
+                    if cache_result.get("updated"):
+                        self.logger.info(
+                            f"Instruction cache updated: {cache_result.get('reason', 'unknown')}"
+                        )
+                        self.logger.debug(
+                            f"Cache hash: {cache_result.get('content_hash', 'N/A')[:8]}..."
+                        )
+                        self.logger.debug(
+                            f"Cache size: {cache_result.get('content_size_kb', 'N/A')} KB"
+                        )
+                    else:
+                        self.logger.debug(
+                            f"Using cached instructions: {cache_result.get('reason', 'unknown')}"
+                        )
+
+                    # Use file-based loading for better performance
+                    cmd.extend(["--system-prompt-file", str(cache_file)])
+                    self.logger.info(
+                        f"✓ Using file-based instruction loading: {cache_file}"
+                    )
+                else:
+                    # Fallback to inline if cache file doesn't exist
+                    self.logger.warning(
+                        "Cache file not available, falling back to inline instruction"
+                    )
+                    cmd.extend(["--append-system-prompt", system_prompt])
+
+            except Exception as e:
+                # Graceful fallback - cache failures don't break deployment
+                self.logger.warning(f"Failed to cache instructions, using inline: {e}")
+                cmd.extend(["--append-system-prompt", system_prompt])
 
         # Final command verification
         # self.logger.info(f"Final Claude command built: {' '.join(cmd)}")

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):

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
+        """
+        ...