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

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(

claude_mpm/experimental/cli_enhancements.py

@@ -31,11 +31,7 @@ import click
 
 from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.hooks.validation_hooks import ValidationHooks
-from claude_mpm.utils.error_handler import (
-    ErrorContext,
-    MPMError,
-    handle_errors,
-)
+from claude_mpm.utils.error_handler import ErrorContext, MPMError, handle_errors
 from claude_mpm.validation import AgentValidator, ValidationResult
 
 logger = get_logger(__name__)

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -5,8 +5,19 @@ This module provides utilities for integrating with the memory system,
 including pre and post delegation hooks.
 """
 
-import os
+import logging
 import sys
+
+# Reconfigure logging to INFO level BEFORE kuzu-memory imports
+# This overrides kuzu-memory's WARNING-level basicConfig (fixes 1M-445)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    force=True,  # Python 3.8+ - reconfigures root logger
+    stream=sys.stderr,
+)
+
+import os
 from datetime import datetime, timezone
 from typing import Optional
 

claude_mpm/hooks/failure_learning/__init__.py

@@ -35,14 +35,8 @@ Usage:
     hook_service.register_hook(get_learning_extraction_hook())
 """
 
-from .failure_detection_hook import (
-    FailureDetectionHook,
-    get_failure_detection_hook,
-)
-from .fix_detection_hook import (
-    FixDetectionHook,
-    get_fix_detection_hook,
-)
+from .failure_detection_hook import FailureDetectionHook, get_failure_detection_hook
+from .fix_detection_hook import FixDetectionHook, get_fix_detection_hook
 from .learning_extraction_hook import (
     LearningExtractionHook,
     get_learning_extraction_hook,

claude_mpm/hooks/failure_learning/failure_detection_hook.py

@@ -21,12 +21,7 @@ Integration points:
 import logging
 from typing import Any, Dict
 
-from claude_mpm.hooks.base_hook import (
-    BaseHook,
-    HookContext,
-    HookResult,
-    HookType,
-)
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookResult, HookType
 from claude_mpm.services.memory.failure_tracker import get_failure_tracker
 
 logger = logging.getLogger(__name__)

claude_mpm/hooks/failure_learning/fix_detection_hook.py

@@ -23,12 +23,7 @@ Integration points:
 import logging
 from typing import Any, Dict
 
-from claude_mpm.hooks.base_hook import (
-    BaseHook,
-    HookContext,
-    HookResult,
-    HookType,
-)
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookResult, HookType
 from claude_mpm.services.memory.failure_tracker import get_failure_tracker
 
 logger = logging.getLogger(__name__)

claude_mpm/hooks/failure_learning/learning_extraction_hook.py

@@ -23,12 +23,7 @@ Integration points:
 import logging
 from typing import Any
 
-from claude_mpm.hooks.base_hook import (
-    BaseHook,
-    HookContext,
-    HookResult,
-    HookType,
-)
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookResult, HookType
 from claude_mpm.services.memory.failure_tracker import get_failure_tracker
 
 logger = logging.getLogger(__name__)

claude_mpm/hooks/kuzu_response_hook.py

@@ -20,11 +20,7 @@ DESIGN DECISIONS:
 import logging
 from typing import Any, Optional
 
-from claude_mpm.hooks.base_hook import (
-    HookContext,
-    HookResult,
-    PostDelegationHook,
-)
+from claude_mpm.hooks.base_hook import HookContext, HookResult, PostDelegationHook
 from claude_mpm.hooks.kuzu_memory_hook import get_kuzu_memory_hook
 
 logger = logging.getLogger(__name__)

claude_mpm/models/git_repository.py

@@ -0,0 +1,198 @@
+"""Git repository model for agent sources."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+
+@dataclass
+class GitRepository:
+    """Represents a Git repository configuration for agent sources.
+
+    This model tracks Git repositories that contain agent markdown files.
+    Repositories are cached locally and synced using ETag-based HTTP caching.
+
+    Attributes:
+        url: Full GitHub repository URL (e.g., https://github.com/owner/repo)
+        subdirectory: Optional subdirectory within repository (e.g., "agents/backend")
+        enabled: Whether this repository should be synced
+        priority: Priority for agent resolution (lower = higher precedence)
+        last_synced: Timestamp of last successful sync
+        etag: HTTP ETag from last sync for incremental updates
+    """
+
+    url: str
+    subdirectory: Optional[str] = None
+    enabled: bool = True
+    priority: int = 100
+    last_synced: Optional[datetime] = None
+    etag: Optional[str] = None
+
+    @property
+    def cache_path(self) -> Path:
+        """Return cache directory path for this repository.
+
+        Cache structure: ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/{subdirectory}/
+
+        Returns:
+            Absolute path to cache directory for this repository
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/bobmatnyc/claude-mpm-agents",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.cache_path
+            Path('/Users/user/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents')
+        """
+        home = Path.home()
+        base_cache = home / ".claude-mpm" / "cache" / "remote-agents"
+
+        # Extract owner and repo from URL
+        owner, repo = self._parse_github_url(self.url)
+
+        # Build cache path: base/owner/repo/subdirectory
+        cache_path = base_cache / owner / repo
+
+        if self.subdirectory:
+            # Normalize subdirectory path (remove leading/trailing slashes)
+            normalized_subdir = self.subdirectory.strip("/")
+            cache_path = cache_path / normalized_subdir
+
+        return cache_path
+
+    @property
+    def identifier(self) -> str:
+        """Return unique identifier for this repository.
+
+        Format: {owner}/{repo}/{subdirectory} or {owner}/{repo}
+
+        Returns:
+            Unique identifier string
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/owner/repo",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.identifier
+            'owner/repo/agents'
+        """
+        owner, repo = self._parse_github_url(self.url)
+        base_id = f"{owner}/{repo}"
+
+        if self.subdirectory:
+            normalized_subdir = self.subdirectory.strip("/")
+            return f"{base_id}/{normalized_subdir}"
+
+        return base_id
+
+    def validate(self) -> list[str]:
+        """Validate repository configuration.
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        Validation checks:
+            - URL is not empty
+            - URL is valid HTTP/HTTPS format
+            - URL is a GitHub repository URL
+            - Priority is non-negative
+            - Priority is reasonable (<= 1000, warning only)
+            - Subdirectory is relative path (not absolute)
+        """
+        errors = []
+
+        # Validate URL
+        if not self.url or not self.url.strip():
+            errors.append("URL cannot be empty")
+            return errors  # Can't continue validation without URL
+
+        # Check URL format
+        try:
+            parsed = urlparse(self.url)
+
+            # Must be HTTP or HTTPS
+            if parsed.scheme not in ("http", "https"):
+                errors.append(
+                    f"URL must use http:// or https:// protocol, got: {parsed.scheme}"
+                )
+
+            # Must be GitHub (for now)
+            if not parsed.netloc.endswith("github.com"):
+                errors.append(f"URL must be a GitHub repository, got: {parsed.netloc}")
+
+            # Should have owner/repo path structure
+            path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+            if len(path_parts) < 2:
+                errors.append(f"URL must include owner/repo path, got: {parsed.path}")
+
+        except Exception as e:
+            errors.append(f"Invalid URL format: {e}")
+
+        # Validate priority
+        if self.priority < 0:
+            errors.append("Priority must be non-negative (0 or greater)")
+
+        if self.priority > 1000:
+            errors.append(
+                f"Priority {self.priority} is unusually high (recommended: 0-1000). "
+                "Lower priority numbers have higher precedence."
+            )
+
+        # Validate subdirectory
+        if self.subdirectory:
+            # Must be relative path
+            if Path(self.subdirectory).is_absolute():
+                errors.append(
+                    f"Subdirectory must be a relative path, got absolute: {self.subdirectory}"
+                )
+
+            # Should not start with slash
+            if self.subdirectory.startswith("/"):
+                errors.append(
+                    f"Subdirectory should not start with '/', got: {self.subdirectory}"
+                )
+
+        return errors
+
+    def _parse_github_url(self, url: str) -> tuple[str, str]:
+        """Parse GitHub URL to extract owner and repository name.
+
+        Args:
+            url: GitHub repository URL
+
+        Returns:
+            Tuple of (owner, repository_name)
+
+        Example:
+            >>> repo = GitRepository(url="https://github.com/owner/repo")
+            >>> repo._parse_github_url(repo.url)
+            ('owner', 'repo')
+        """
+        # Remove .git suffix if present
+        url = url.rstrip("/")
+        if url.endswith(".git"):
+            url = url[:-4]
+
+        # Parse URL
+        parsed = urlparse(url)
+        path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+
+        if len(path_parts) >= 2:
+            owner = path_parts[0]
+            repo = path_parts[1]
+            return owner, repo
+
+        # Fallback: Use URL as-is if parsing fails
+        # This will be caught by validation
+        return "unknown", "unknown"
+
+    def __repr__(self) -> str:
+        """Return string representation of repository."""
+        return (
+            f"GitRepository(identifier='{self.identifier}', "
+            f"priority={self.priority}, enabled={self.enabled})"
+        )

claude_mpm/services/agents/agent_builder.py

@@ -8,12 +8,13 @@ This service provides comprehensive agent lifecycle management including:
 - Integration with deployment services
 """
 
-import json
 import re
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, ClassVar, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.exceptions import AgentDeploymentError
 from claude_mpm.core.logging_config import get_logger
 
@@ -285,10 +286,15 @@ class AgentBuilderService:
         if not self.templates_dir.exists():
             return templates
 
-        for template_file in self.templates_dir.glob("*.json"):
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        for template_file in self.templates_dir.glob("*.md"):
             try:
-                with template_file.open() as f:
-                    config = json.load(f)
+                # Read markdown content and extract YAML frontmatter
+                content = template_file.read_text()
+                config = self._extract_yaml_frontmatter(content)
+                if not config:
+                    self.logger.warning(f"No YAML frontmatter in {template_file.name}")
+                    continue
 
                 # Use filename stem as ID if not specified in config
                 template_id = config.get("id") or template_file.stem
@@ -308,6 +314,30 @@ class AgentBuilderService:
 
         return templates
 
+    def _extract_yaml_frontmatter(self, content: str) -> Optional[Dict[str, Any]]:
+        """
+        Extract and parse YAML frontmatter from markdown content.
+
+        Args:
+            content: File content to parse
+
+        Returns:
+            Parsed YAML frontmatter as dict, or None if not found/invalid
+        """
+        if not content.strip().startswith("---"):
+            return None
+
+        # Split on --- delimiters
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return None
+
+        try:
+            return yaml.safe_load(parts[1])
+        except yaml.YAMLError as e:
+            self.logger.warning(f"Failed to parse YAML frontmatter: {e}")
+            return None
+
     def _validate_agent_id(self, agent_id: str) -> None:
         """Validate agent ID format.
 
@@ -371,16 +401,22 @@ class AgentBuilderService:
         if template_id in self._template_cache:
             return self._template_cache[template_id].copy()
 
-        template_file = self.templates_dir / f"{template_id}.json"
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        template_file = self.templates_dir / f"{template_id}.md"
 
         if not template_file.exists():
             raise AgentDeploymentError(f"Template '{template_id}' not found")
 
         try:
-            with template_file.open() as f:
-                config = json.load(f)
-                self._template_cache[template_id] = config
-                return config.copy()
+            # Read markdown content and extract YAML frontmatter
+            content = template_file.read_text()
+            config = self._extract_yaml_frontmatter(content)
+            if not config:
+                raise AgentDeploymentError(
+                    f"No YAML frontmatter in template '{template_id}'"
+                )
+            self._template_cache[template_id] = config
+            return config.copy()
         except Exception as e:
             raise AgentDeploymentError(
                 f"Failed to load template '{template_id}': {e}"