claude-mpm 5.0.2__py3-none-any.whl → 5.4.3__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/socketio_pool.py

@@ -55,8 +55,8 @@ class CircuitState(Enum):
 class ConnectionStats:
     """Connection statistics for monitoring."""
 
-    created_at: datetime = field(default_factory=datetime.now)
-    last_used: datetime = field(default_factory=datetime.now)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_used: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
     events_sent: int = 0
     errors: int = 0
     consecutive_errors: int = 0
@@ -70,7 +70,7 @@ class BatchEvent:
     namespace: str
     event: str
     data: Dict[str, Any]
-    timestamp: datetime = field(default_factory=datetime.now)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
 
 class CircuitBreaker:

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_agent_registry.py

@@ -84,6 +84,12 @@ class AgentMetadata:
     version: str = "1.0.0"
     author: str = ""
     tags: List[str] = None
+    # NEW: Collection-based identification fields
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repo
+    canonical_id: Optional[str] = (
+        None  # Format: collection_id:agent_id or legacy:filename
+    )
 
     def __post_init__(self):
         """Initialize default values for mutable fields."""
@@ -168,26 +174,16 @@ class UnifiedAgentRegistry:
         if project_path.exists():
             self.discovery_paths.append(project_path)
 
-        # Also check for local JSON templates in .claude-mpm/agents/
-        local_project_path = self.path_manager.project_root / ".claude-mpm" / "agents"
-        if (
-            local_project_path.exists()
-            and local_project_path not in self.discovery_paths
-        ):
-            self.discovery_paths.append(local_project_path)
-            logger.debug(f"Added local project templates path: {local_project_path}")
+        # NOTE: .claude-mpm/agents/ is deprecated in the simplified architecture
+        # Source agents come from ~/.claude-mpm/cache/remote-agents/
+        # Deployed agents go to .claude/agents/
 
-        # User-level agents
+        # User-level agents (deprecated in simplified architecture)
+        # Keeping for backward compatibility but not actively used
         user_path = self.path_manager.get_user_agents_dir()
         if user_path.exists():
             self.discovery_paths.append(user_path)
 
-        # Also check for user JSON templates in ~/.claude-mpm/agents/
-        local_user_path = Path.home() / ".claude-mpm" / "agents"
-        if local_user_path.exists() and local_user_path not in self.discovery_paths:
-            self.discovery_paths.append(local_user_path)
-            logger.debug(f"Added local user templates path: {local_user_path}")
-
         # System-level agents (includes templates as a subdirectory)
         system_path = self.path_manager.get_system_agents_dir()
         if system_path.exists():
@@ -690,6 +686,111 @@ class UnifiedAgentRegistry:
         """Get all memory-aware agents."""
         return self.list_agents(agent_type=AgentType.MEMORY_AWARE)
 
+    def get_agents_by_collection(self, collection_id: str) -> List[AgentMetadata]:
+        """Get all agents from a specific collection.
+
+        NEW: Enables collection-based agent selection.
+
+        Args:
+            collection_id: Collection identifier (e.g., "bobmatnyc/claude-mpm-agents")
+
+        Returns:
+            List of agents from the specified collection
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> agents = registry.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
+            >>> len(agents)
+            45
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        collection_agents = [
+            agent
+            for agent in self.registry.values()
+            if agent.collection_id == collection_id
+        ]
+
+        return sorted(collection_agents, key=lambda a: a.name)
+
+    def list_collections(self) -> List[Dict[str, Any]]:
+        """List all available collections with agent counts.
+
+        NEW: Provides overview of available collections.
+
+        Returns:
+            List of collection info dictionaries with:
+            - collection_id: Collection identifier
+            - agent_count: Number of agents in collection
+            - agents: List of agent names in collection
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> collections = registry.list_collections()
+            >>> collections
+            [
+                {
+                    "collection_id": "bobmatnyc/claude-mpm-agents",
+                    "agent_count": 45,
+                    "agents": ["pm", "engineer", "qa", ...]
+                }
+            ]
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        # Group agents by collection_id
+        collections_map: Dict[str, List[str]] = {}
+
+        for agent in self.registry.values():
+            if not agent.collection_id:
+                # Skip agents without collection (legacy or local)
+                continue
+
+            if agent.collection_id not in collections_map:
+                collections_map[agent.collection_id] = []
+
+            collections_map[agent.collection_id].append(agent.name)
+
+        # Convert to list format
+        collections = [
+            {
+                "collection_id": coll_id,
+                "agent_count": len(agent_names),
+                "agents": sorted(agent_names),
+            }
+            for coll_id, agent_names in collections_map.items()
+        ]
+
+        return sorted(collections, key=lambda c: c["collection_id"])
+
+    def get_agent_by_canonical_id(self, canonical_id: str) -> Optional[AgentMetadata]:
+        """Get agent by canonical ID (primary matching key).
+
+        NEW: Primary matching method using canonical_id.
+
+        Args:
+            canonical_id: Canonical identifier (e.g., "bobmatnyc/claude-mpm-agents:pm")
+
+        Returns:
+            AgentMetadata if found, None otherwise
+
+        Example:
+            >>> registry = get_agent_registry()
+            >>> agent = registry.get_agent_by_canonical_id("bobmatnyc/claude-mpm-agents:pm")
+            >>> agent.name
+            'Project Manager Agent'
+        """
+        if not self.registry:
+            self.discover_agents()
+
+        for agent in self.registry.values():
+            if agent.canonical_id == canonical_id:
+                return agent
+
+        return None
+
     def add_discovery_path(self, path: Union[str, Path]) -> None:
         """Add a new path for agent discovery."""
         path = Path(path)
@@ -809,6 +910,21 @@ def get_registry_stats() -> Dict[str, Any]:
     return get_agent_registry().get_registry_stats()
 
 
+def get_agents_by_collection(collection_id: str) -> List[AgentMetadata]:
+    """Get all agents from a specific collection."""
+    return get_agent_registry().get_agents_by_collection(collection_id)
+
+
+def list_collections() -> List[Dict[str, Any]]:
+    """List all available collections."""
+    return get_agent_registry().list_collections()
+
+
+def get_agent_by_canonical_id(canonical_id: str) -> Optional[AgentMetadata]:
+    """Get agent by canonical ID."""
+    return get_agent_registry().get_agent_by_canonical_id(canonical_id)
+
+
 # Legacy function names for backward compatibility
 def listAgents() -> List[str]:
     """Legacy function: Get list of agent names."""
@@ -838,14 +954,16 @@ __all__ = [
     "discover_agents",
     "discover_agents_sync",
     "get_agent",
+    "get_agent_by_canonical_id",
     "get_agent_names",
     "get_agent_registry",
+    "get_agents_by_collection",
     "get_core_agents",
     "get_project_agents",
     "get_registry_stats",
     "get_specialized_agents",
-    # Legacy compatibility
     "listAgents",
     "list_agents",
     "list_agents_all",
+    "list_collections",
 ]

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/hooks/claude_hooks/correlation_manager.py

@@ -0,0 +1,60 @@
+"""Cross-process correlation storage using .claude-mpm directory."""
+
+import json
+import time
+from pathlib import Path
+
+
+def get_correlation_dir() -> Path:
+    """Get correlation directory in project's .claude-mpm folder."""
+    # Use CWD's .claude-mpm directory (where hooks run from)
+    cwd = Path.cwd()
+    return cwd / ".claude-mpm" / "correlations"
+
+
+TTL_SECONDS = 3600  # 1 hour
+
+
+class CorrelationManager:
+    """Manages correlation IDs across separate hook processes."""
+
+    @staticmethod
+    def store(session_id: str, tool_call_id: str, tool_name: str) -> None:
+        """Store correlation data for later retrieval by post_tool."""
+        correlation_dir = get_correlation_dir()
+        correlation_dir.mkdir(parents=True, exist_ok=True)
+        filepath = correlation_dir / f"correlation_{session_id}.json"
+        data = {
+            "tool_call_id": tool_call_id,
+            "tool_name": tool_name,
+            "timestamp": time.time(),
+        }
+        filepath.write_text(json.dumps(data))
+
+    @staticmethod
+    def retrieve(session_id: str) -> str | None:
+        """Retrieve and delete correlation data from temp file."""
+        correlation_dir = get_correlation_dir()
+        filepath = correlation_dir / f"correlation_{session_id}.json"
+        if not filepath.exists():
+            return None
+        try:
+            data = json.loads(filepath.read_text())
+            filepath.unlink()  # Delete after reading
+            return data.get("tool_call_id")
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    @staticmethod
+    def cleanup_old() -> None:
+        """Remove correlation files older than TTL."""
+        correlation_dir = get_correlation_dir()
+        if not correlation_dir.exists():
+            return
+        now = time.time()
+        for filepath in correlation_dir.glob("correlation_*.json"):
+            try:
+                if now - filepath.stat().st_mtime > TTL_SECONDS:
+                    filepath.unlink()
+            except OSError:
+                pass

claude_mpm/hooks/claude_hooks/event_handlers.py

@@ -9,6 +9,7 @@ import os
 import re
 import subprocess
 import sys
+import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -134,6 +135,9 @@ class EventHandlers:
         tool_name = event.get("tool_name", "")
         tool_input = event.get("tool_input", {})
 
+        # Generate unique tool call ID for correlation with post_tool event
+        tool_call_id = str(uuid.uuid4())
+
         # Extract key parameters based on tool type
         tool_params = extract_tool_parameters(tool_name, tool_input)
 
@@ -144,6 +148,8 @@ class EventHandlers:
         working_dir = event.get("cwd", "")
         git_branch = self._get_git_branch(working_dir) if working_dir else "Unknown"
 
+        timestamp = datetime.now(timezone.utc).isoformat()
+
         pre_tool_data = {
             "tool_name": tool_name,
             "operation_type": operation_type,
@@ -151,15 +157,27 @@ class EventHandlers:
             "session_id": event.get("session_id", ""),
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "timestamp": timestamp,
             "parameter_count": len(tool_input) if isinstance(tool_input, dict) else 0,
             "is_file_operation": tool_name
             in ["Write", "Edit", "MultiEdit", "Read", "LS", "Glob"],
             "is_execution": tool_name in ["Bash", "NotebookEdit"],
             "is_delegation": tool_name == "Task",
             "security_risk": assess_security_risk(tool_name, tool_input),
+            "correlation_id": tool_call_id,  # Add correlation_id for pre/post correlation
         }
 
+        # Store tool_call_id using CorrelationManager for cross-process retrieval
+        if session_id:
+            from .correlation_manager import CorrelationManager
+
+            CorrelationManager.store(session_id, tool_call_id, tool_name)
+            if DEBUG:
+                print(
+                    f"  - Generated tool_call_id: {tool_call_id[:8]}... for session {session_id[:8]}...",
+                    file=sys.stderr,
+                )
+
         # Add delegation-specific data if this is a Task tool
         if tool_name == "Task" and isinstance(tool_input, dict):
             self._handle_task_delegation(tool_input, pre_tool_data, session_id)
@@ -375,6 +393,7 @@ class EventHandlers:
         """
         tool_name = event.get("tool_name", "")
         exit_code = event.get("exit_code", 0)
+        session_id = event.get("session_id", "")
 
         # Extract result data
         result_data = extract_tool_results(event)
@@ -386,6 +405,16 @@ class EventHandlers:
         working_dir = event.get("cwd", "")
         git_branch = self._get_git_branch(working_dir) if working_dir else "Unknown"
 
+        # Retrieve tool_call_id using CorrelationManager for cross-process correlation
+        from .correlation_manager import CorrelationManager
+
+        tool_call_id = CorrelationManager.retrieve(session_id) if session_id else None
+        if DEBUG and tool_call_id:
+            print(
+                f"  - Retrieved tool_call_id: {tool_call_id[:8]}... for session {session_id[:8]}...",
+                file=sys.stderr,
+            )
+
         post_tool_data = {
             "tool_name": tool_name,
             "exit_code": exit_code,
@@ -399,7 +428,7 @@ class EventHandlers:
             ),
             "duration_ms": duration,
             "result_summary": result_data,
-            "session_id": event.get("session_id", ""),
+            "session_id": session_id,
             "working_directory": working_dir,
             "git_branch": git_branch,
             "timestamp": datetime.now(timezone.utc).isoformat(),
@@ -412,6 +441,10 @@ class EventHandlers:
             ),
         }
 
+        # Add correlation_id if available for correlation with pre_tool
+        if tool_call_id:
+            post_tool_data["correlation_id"] = tool_call_id
+
         # Handle Task delegation completion for memory hooks and response tracking
         if tool_name == "Task":
             session_id = event.get("session_id", "")

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -304,6 +304,10 @@ class ClaudeHookHandler:
             # Perform periodic cleanup if needed
             if self.state_manager.increment_events_processed():
                 self.state_manager.cleanup_old_entries()
+                # Also cleanup old correlation files
+                from .correlation_manager import CorrelationManager
+
+                CorrelationManager.cleanup_old()
                 if DEBUG:
                     print(
                         f"🧹 Performed cleanup after {self.state_manager.events_processed} events",

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