claude-mpm 5.0.2__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/core/oneshot_session.py

@@ -2,6 +2,11 @@
 
 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
@@ -11,11 +16,18 @@ 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.
@@ -27,13 +39,13 @@ 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

claude_mpm/core/output_style_manager.py

@@ -5,6 +5,7 @@ This module handles:
 2. Output style extraction from framework instructions
 3. One-time deployment to Claude Code >= 1.0.83 at startup
 4. Fallback injection for older versions
+5. Support for multiple output styles (professional and teaching modes)
 
 The output style is set once at startup and not monitored or enforced after that.
 Users can change it if they want, and the system will respect their choice.
@@ -14,7 +15,7 @@ import json
 import re
 import subprocess
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Any, Dict, Literal, Optional, TypedDict, cast
 
 from ..utils.imports import safe_import
 
@@ -25,22 +26,56 @@ get_logger = safe_import("claude_mpm.core.logger", "core.logger", ["get_logger"]
 _CACHED_CLAUDE_VERSION: Optional[str] = None
 _VERSION_DETECTED: bool = False
 
+# Output style types
+OutputStyleType = Literal["professional", "teaching"]
+
+
+class StyleConfig(TypedDict):
+    """Configuration for an output style."""
+
+    source: Path
+    target: Path
+    name: str
+
 
 class OutputStyleManager:
-    """Manages output style deployment and version-based handling."""
+    """Manages output style deployment and version-based handling.
+
+    Supports two output styles:
+    - professional: Default Claude MPM style (claude-mpm.md)
+    - teaching: Adaptive teaching mode (claude-mpm-teach.md)
+    """
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize the output style manager."""
-        self.logger = get_logger("output_style_manager")
+        self.logger = get_logger("output_style_manager")  # type: ignore[misc]
         self.claude_version = self._detect_claude_version()
-        self.output_style_dir = Path.home() / ".claude" / "output-styles"
-        self.output_style_path = self.output_style_dir / "claude-mpm.md"
+
+        # Deploy to ~/.claude/styles/ directory (NOT output-styles/)
+        self.output_style_dir = Path.home() / ".claude" / "styles"
         self.settings_file = Path.home() / ".claude" / "settings.json"
 
-        # Cache the output style content path
-        self.mpm_output_style_path = (
-            Path(__file__).parent.parent / "agents" / "OUTPUT_STYLE.md"
-        )
+        # Style definitions
+        self.styles: Dict[str, StyleConfig] = {
+            "professional": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm.md",
+                name="claude-mpm",
+            ),
+            "teaching": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-teach.md",
+                name="claude-mpm-teach",
+            ),
+        }
+
+        # Default style path (for backward compatibility)
+        self.output_style_path = self.styles["professional"]["target"]
+        self.mpm_output_style_path = self.styles["professional"]["source"]
 
     def _detect_claude_version(self) -> Optional[str]:
         """
@@ -158,56 +193,77 @@ class OutputStyleManager:
         """
         return not self.supports_output_styles()
 
-    def extract_output_style_content(self, framework_loader=None) -> str:
+    def extract_output_style_content(
+        self, framework_loader: Any = None, style: OutputStyleType = "professional"
+    ) -> str:
         """
-        Read output style content from OUTPUT_STYLE.md.
+        Read output style content from style source file.
 
         Args:
             framework_loader: Optional framework loader (kept for compatibility, not used)
+            style: Style type to extract ("professional" or "teaching")
 
         Returns:
             Complete output style content from file
         """
-        # Always read from the complete OUTPUT_STYLE.md file
-        if self.mpm_output_style_path.exists():
-            content = self.mpm_output_style_path.read_text()
-            self.logger.info(f"Read OUTPUT_STYLE.md directly ({len(content)} chars)")
+        style_config = self.styles[style]
+        source_path = style_config["source"]
+
+        if source_path.exists():
+            content = source_path.read_text()
+            self.logger.info(
+                f"Read {style} style from {source_path.name} ({len(content)} chars)"
+            )
             return content
+
         # Fallback error
-        error_msg = f"OUTPUT_STYLE.md not found at {self.mpm_output_style_path}"
+        error_msg = f"{style} style not found at {source_path}"
         self.logger.error(error_msg)
         raise FileNotFoundError(error_msg)
 
-    def save_output_style(self, content: str) -> Path:
+    def save_output_style(
+        self, content: str, style: OutputStyleType = "professional"
+    ) -> Path:
         """
-        Save output style content to OUTPUT_STYLE.md.
+        Save output style content to source file.
 
         Args:
             content: The formatted output style content
+            style: Style type to save ("professional" or "teaching")
 
         Returns:
             Path to the saved file
         """
         try:
+            style_config = self.styles[style]
+            source_path = style_config["source"]
+
             # Ensure the parent directory exists
-            self.mpm_output_style_path.parent.mkdir(parents=True, exist_ok=True)
+            source_path.parent.mkdir(parents=True, exist_ok=True)
 
             # Write the content
-            self.mpm_output_style_path.write_text(content, encoding="utf-8")
-            self.logger.info(f"Saved output style to {self.mpm_output_style_path}")
+            source_path.write_text(content, encoding="utf-8")
+            self.logger.info(f"Saved {style} style to {source_path}")
 
-            return self.mpm_output_style_path
+            return source_path
         except Exception as e:
-            self.logger.error(f"Failed to save output style: {e}")
+            self.logger.error(f"Failed to save {style} style: {e}")
             raise
 
-    def deploy_output_style(self, content: str) -> bool:
+    def deploy_output_style(
+        self,
+        content: Optional[str] = None,
+        style: OutputStyleType = "professional",
+        activate: bool = True,
+    ) -> bool:
         """
         Deploy output style to Claude Code if version >= 1.0.83.
-        Deploys the style file and activates it once.
+        Deploys the style file and optionally activates it.
 
         Args:
-            content: The output style content to deploy
+            content: The output style content to deploy (if None, reads from source)
+            style: Style type to deploy ("professional" or "teaching")
+            activate: Whether to activate the style after deployment
 
         Returns:
             True if deployed successfully, False otherwise
@@ -219,26 +275,37 @@ class OutputStyleManager:
             return False
 
         try:
-            # Ensure output-styles directory exists
+            style_config = self.styles[style]
+            target_path = style_config["target"]
+            style_name = style_config["name"]
+
+            # If content not provided, read from source
+            if content is None:
+                content = self.extract_output_style_content(style=style)
+
+            # Ensure styles directory exists
             self.output_style_dir.mkdir(parents=True, exist_ok=True)
 
             # Write the output style file
-            self.output_style_path.write_text(content, encoding="utf-8")
-            self.logger.info(f"Deployed output style to {self.output_style_path}")
+            target_path.write_text(content, encoding="utf-8")
+            self.logger.info(f"Deployed {style} style to {target_path}")
 
-            # Activate the claude-mpm style
-            self._activate_output_style()
+            # Activate the style if requested
+            if activate:
+                self._activate_output_style(style_name)
 
             return True
 
         except Exception as e:
-            self.logger.error(f"Failed to deploy output style: {e}")
+            self.logger.error(f"Failed to deploy {style} style: {e}")
             return False
 
-    def _activate_output_style(self) -> bool:
+    def _activate_output_style(self, style_name: str = "claude-mpm") -> bool:
         """
-        Update Claude Code settings to activate the claude-mpm output style.
-        Sets activeOutputStyle to "claude-mpm" once at startup.
+        Update Claude Code settings to activate a specific output style.
+
+        Args:
+            style_name: Name of the style to activate (e.g., "claude-mpm", "claude-mpm-teach")
 
         Returns:
             True if activated successfully, False otherwise
@@ -257,9 +324,9 @@ class OutputStyleManager:
             # Check current active style
             current_style = settings.get("activeOutputStyle")
 
-            # Update active output style to claude-mpm if not already set
-            if current_style != "claude-mpm":
-                settings["activeOutputStyle"] = "claude-mpm"
+            # Update active output style if different
+            if current_style != style_name:
+                settings["activeOutputStyle"] = style_name
 
                 # Ensure settings directory exists
                 self.settings_file.parent.mkdir(parents=True, exist_ok=True)
@@ -270,10 +337,10 @@ class OutputStyleManager:
                 )
 
                 self.logger.info(
-                    f"✅ Activated claude-mpm output style (was: {current_style or 'none'})"
+                    f"✅ Activated {style_name} output style (was: {current_style or 'none'})"
                 )
             else:
-                self.logger.debug("Claude MPM output style already active")
+                self.logger.debug(f"{style_name} output style already active")
 
             return True
 
@@ -319,7 +386,9 @@ class OutputStyleManager:
 
         return status
 
-    def get_injectable_content(self, framework_loader=None) -> str:
+    def get_injectable_content(
+        self, framework_loader: Any = None, style: OutputStyleType = "professional"
+    ) -> str:
         """
         Get output style content for injection into instructions (for Claude < 1.0.83).
 
@@ -328,12 +397,13 @@ class OutputStyleManager:
 
         Args:
             framework_loader: Optional FrameworkLoader instance to reuse loaded content
+            style: Style type to extract ("professional" or "teaching")
 
         Returns:
             Simplified output style content for injection
         """
         # Extract the same content but without YAML frontmatter
-        full_content = self.extract_output_style_content(framework_loader)
+        full_content = self.extract_output_style_content(framework_loader, style=style)
 
         # Remove YAML frontmatter
         lines = full_content.split("\n")
@@ -351,3 +421,63 @@ class OutputStyleManager:
 
         # If no frontmatter found, return as-is
         return full_content
+
+    def deploy_all_styles(self, activate_default: bool = True) -> Dict[str, bool]:
+        """
+        Deploy all available output styles to Claude Code.
+
+        Args:
+            activate_default: Whether to activate the professional style after deployment
+
+        Returns:
+            Dictionary mapping style names to deployment success status
+        """
+        results: Dict[str, bool] = {}
+
+        for style_type_key in self.styles:
+            # Deploy without activation
+            # Cast is safe because we know self.styles keys are OutputStyleType
+            style_type = cast("OutputStyleType", style_type_key)
+            success = self.deploy_output_style(style=style_type, activate=False)
+            results[style_type] = success
+
+        # Activate the default style if requested
+        if activate_default and results.get("professional", False):
+            self._activate_output_style("claude-mpm")
+
+        return results
+
+    def deploy_teaching_style(self, activate: bool = False) -> bool:
+        """
+        Deploy the teaching style specifically.
+
+        Args:
+            activate: Whether to activate the teaching style after deployment
+
+        Returns:
+            True if deployed successfully, False otherwise
+        """
+        return self.deploy_output_style(style="teaching", activate=activate)
+
+    def list_available_styles(self) -> Dict[str, Dict[str, str]]:
+        """
+        List all available output styles with their metadata.
+
+        Returns:
+            Dictionary mapping style types to their configuration
+        """
+        available_styles = {}
+
+        for style_type, config in self.styles.items():
+            source_exists = config["source"].exists()
+            target_exists = config["target"].exists()
+
+            available_styles[style_type] = {
+                "name": config["name"],
+                "source_path": str(config["source"]),
+                "target_path": str(config["target"]),
+                "source_exists": str(source_exists),
+                "deployed": str(target_exists),
+            }
+
+        return available_styles

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]