claude-mpm 4.1.5__py3-none-any.whl → 4.1.6__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/connection_manager_http.py

@@ -0,0 +1,190 @@
+"""HTTP-based connection management service for Claude hook handler.
+
+This service manages:
+- HTTP POST event emission for ephemeral hook processes
+- EventBus initialization (optional)
+- Event emission through both channels
+
+DESIGN DECISION: Use stateless HTTP POST instead of persistent SocketIO
+connections because hook handlers are ephemeral processes (< 1 second lifetime).
+This eliminates disconnection issues and matches the process lifecycle.
+"""
+
+import os
+import sys
+from datetime import datetime
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Import requests for HTTP POST communication
+try:
+    import requests
+
+    REQUESTS_AVAILABLE = True
+except ImportError:
+    REQUESTS_AVAILABLE = False
+    requests = None
+
+# Import EventNormalizer for consistent event formatting
+try:
+    from claude_mpm.services.socketio.event_normalizer import EventNormalizer
+except ImportError:
+    # Create a simple fallback EventNormalizer if import fails
+    class EventNormalizer:
+        def normalize(self, event_data, source="hook"):
+            """Simple fallback normalizer that returns event as-is."""
+            return type(
+                "NormalizedEvent",
+                (),
+                {
+                    "to_dict": lambda: {
+                        "event": "claude_event",
+                        "type": event_data.get("type", "unknown"),
+                        "subtype": event_data.get("subtype", "generic"),
+                        "timestamp": event_data.get(
+                            "timestamp", datetime.now().isoformat()
+                        ),
+                        "data": event_data.get("data", event_data),
+                    }
+                },
+            )
+
+
+# Import EventBus for decoupled event distribution
+try:
+    from claude_mpm.services.event_bus import EventBus
+
+    EVENTBUS_AVAILABLE = True
+except ImportError:
+    EVENTBUS_AVAILABLE = False
+    EventBus = None
+
+
+class ConnectionManagerService:
+    """Manages connections for the Claude hook handler using HTTP POST."""
+
+    def __init__(self):
+        """Initialize connection management service."""
+        # Event normalizer for consistent event schema
+        self.event_normalizer = EventNormalizer()
+
+        # Server configuration for HTTP POST
+        self.server_host = os.environ.get("CLAUDE_MPM_SERVER_HOST", "localhost")
+        self.server_port = int(os.environ.get("CLAUDE_MPM_SERVER_PORT", "8765"))
+        self.http_endpoint = f"http://{self.server_host}:{self.server_port}/api/events"
+
+        # Initialize EventBus for in-process event distribution (optional)
+        self.event_bus = None
+        self._initialize_eventbus()
+
+        # For backward compatibility with tests
+        self.connection_pool = None  # No longer used
+
+        if DEBUG:
+            print(
+                f"✅ HTTP connection manager initialized - endpoint: {self.http_endpoint}",
+                file=sys.stderr,
+            )
+
+    def _initialize_eventbus(self):
+        """Initialize the EventBus for in-process distribution."""
+        if EVENTBUS_AVAILABLE:
+            try:
+                self.event_bus = EventBus.get_instance()
+                if DEBUG:
+                    print("✅ EventBus initialized for hook handler", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to initialize EventBus: {e}", file=sys.stderr)
+                self.event_bus = None
+
+    def emit_event(self, namespace: str, event: str, data: dict):
+        """Emit event using HTTP POST and optionally EventBus.
+
+        WHY HTTP POST approach:
+        - Stateless: Perfect for ephemeral hook processes
+        - Fire-and-forget: No connection management needed
+        - Fast: Minimal overhead, no handshake
+        - Reliable: Server handles buffering and retries
+        """
+        # Create event data for normalization
+        raw_event = {
+            "type": "hook",
+            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop"
+            "timestamp": datetime.now().isoformat(),
+            "data": data,
+            "source": "claude_hooks",  # Identify the source
+            "session_id": data.get("sessionId"),  # Include session if available
+        }
+
+        # Normalize the event using EventNormalizer for consistent schema
+        normalized_event = self.event_normalizer.normalize(raw_event, source="hook")
+        claude_event_data = normalized_event.to_dict()
+
+        # Log important events for debugging
+        if DEBUG and event in ["subagent_stop", "pre_tool"]:
+            if event == "subagent_stop":
+                agent_type = data.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing SubagentStop for agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+            elif event == "pre_tool" and data.get("tool_name") == "Task":
+                delegation = data.get("delegation_details", {})
+                agent_type = delegation.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing Task delegation to agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+
+        # Primary method: HTTP POST to server
+        # This is fire-and-forget with a short timeout
+        if REQUESTS_AVAILABLE:
+            try:
+                # Send HTTP POST with short timeout (fire-and-forget pattern)
+                response = requests.post(
+                    self.http_endpoint,
+                    json=claude_event_data,
+                    timeout=0.5,  # 500ms timeout - don't wait long
+                    headers={"Content-Type": "application/json"},
+                )
+                if DEBUG and response.status_code == 204:
+                    print(f"✅ Emitted via HTTP POST: {event}", file=sys.stderr)
+                elif DEBUG and response.status_code != 204:
+                    print(
+                        f"⚠️ HTTP POST returned status {response.status_code} for: {event}",
+                        file=sys.stderr,
+                    )
+            except requests.exceptions.Timeout:
+                # Timeout is expected for fire-and-forget pattern
+                if DEBUG:
+                    print(f"✅ HTTP POST sent (timeout OK): {event}", file=sys.stderr)
+            except requests.exceptions.ConnectionError:
+                # Server might not be running - this is OK
+                if DEBUG:
+                    print(f"⚠️ Server not available for: {event}", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to emit via HTTP POST: {e}", file=sys.stderr)
+        elif DEBUG:
+            print(
+                "⚠️ requests module not available - cannot emit via HTTP",
+                file=sys.stderr,
+            )
+
+        # Also publish to EventBus for any in-process subscribers
+        if self.event_bus and EVENTBUS_AVAILABLE:
+            try:
+                # Publish to EventBus with topic format: hook.{event}
+                topic = f"hook.{event}"
+                self.event_bus.publish(topic, claude_event_data)
+                if DEBUG:
+                    print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+
+    def cleanup(self):
+        """Cleanup connections on service destruction."""
+        # Nothing to cleanup for HTTP POST approach

claude_mpm/services/diagnostics/checks/__init__.py

@@ -12,6 +12,7 @@ from .common_issues_check import CommonIssuesCheck
 from .configuration_check import ConfigurationCheck
 from .filesystem_check import FilesystemCheck
 from .installation_check import InstallationCheck
+from .instructions_check import InstructionsCheck
 from .mcp_check import MCPCheck
 from .monitor_check import MonitorCheck
 from .startup_log_check import StartupLogCheck
@@ -24,6 +25,7 @@ __all__ = [
     "ConfigurationCheck",
     "FilesystemCheck",
     "InstallationCheck",
+    "InstructionsCheck",
     "MCPCheck",
     "MonitorCheck",
     "StartupLogCheck",

claude_mpm/services/diagnostics/checks/instructions_check.py

@@ -0,0 +1,418 @@
+"""
+Check for duplicate or conflicting CLAUDE.md and instruction files.
+
+WHY: Detect duplicate content, conflicting directives, and improperly placed
+instruction files that could cause confusion in agent behavior.
+"""
+
+import hashlib
+import re
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict
+
+from ..models import DiagnosticResult, DiagnosticStatus
+from .base_check import BaseDiagnosticCheck
+
+
+class InstructionsCheck(BaseDiagnosticCheck):
+    """Check for duplicate, conflicting, or misplaced instruction files."""
+
+    # Known instruction file patterns
+    INSTRUCTION_FILES = {
+        "CLAUDE.md": "Claude Code instructions (should be in project root only)",
+        "INSTRUCTIONS.md": "MPM agent customization",
+        "BASE_PM.md": "Base PM framework requirements",
+    }
+
+    # Patterns that indicate potential conflicts
+    CONFLICT_PATTERNS = [
+        (r"(?i)you\s+are\s+.*pm", "PM role definition"),
+        (r"(?i)delegation\s+rules?", "Delegation rules"),
+        (r"(?i)agent\s+selection", "Agent selection logic"),
+        (r"(?i)framework\s+behavior", "Framework behavior"),
+        (r"(?i)command\s+interception", "Command interception"),
+        (r"(?i)memory\s+system", "Memory system configuration"),
+        (r"(?i)response\s+format", "Response formatting"),
+    ]
+
+    @property
+    def name(self) -> str:
+        return "instructions_check"
+
+    @property
+    def category(self) -> str:
+        return "Instructions"
+
+    def run(self) -> DiagnosticResult:
+        """Run instructions file diagnostics."""
+        try:
+            sub_results = []
+            details = {}
+
+            # Find all instruction files
+            instruction_files = self._find_instruction_files()
+            details["found_files"] = {
+                str(path): file_type for path, file_type in instruction_files.items()
+            }
+
+            # Check for misplaced CLAUDE.md files
+            claude_result = self._check_claude_md_placement(instruction_files)
+            sub_results.append(claude_result)
+
+            # Check for duplicate content
+            duplicate_result = self._check_duplicates(instruction_files)
+            sub_results.append(duplicate_result)
+
+            # Check for conflicting directives
+            conflict_result = self._check_conflicts(instruction_files)
+            sub_results.append(conflict_result)
+
+            # Check for overlapping agent definitions
+            agent_result = self._check_agent_definitions(instruction_files)
+            sub_results.append(agent_result)
+
+            # Check proper separation of concerns
+            separation_result = self._check_separation_of_concerns(instruction_files)
+            sub_results.append(separation_result)
+
+            # Determine overall status
+            if any(r.status == DiagnosticStatus.ERROR for r in sub_results):
+                status = DiagnosticStatus.ERROR
+                message = "Found critical issues with instruction files"
+            elif any(r.status == DiagnosticStatus.WARNING for r in sub_results):
+                status = DiagnosticStatus.WARNING
+                message = "Found minor issues with instruction files"
+            else:
+                status = DiagnosticStatus.OK
+                message = "Instruction files are properly configured"
+
+            return DiagnosticResult(
+                category=self.category,
+                status=status,
+                message=message,
+                details=details,
+                sub_results=sub_results if self.verbose else [],
+            )
+
+        except Exception as e:
+            return DiagnosticResult(
+                category=self.category,
+                status=DiagnosticStatus.ERROR,
+                message=f"Instructions check failed: {e!s}",
+                details={"error": str(e)},
+            )
+
+    def _find_instruction_files(self) -> Dict[Path, str]:
+        """Find all instruction files in the project and user directories."""
+        found_files = {}
+
+        # Search locations
+        search_paths = [
+            Path.cwd(),  # Current project
+            Path.home() / ".claude-mpm",  # User directory
+            Path.home() / ".claude",  # Alternative user directory
+        ]
+
+        for base_path in search_paths:
+            if not base_path.exists():
+                continue
+
+            for pattern, file_type in self.INSTRUCTION_FILES.items():
+                # Use rglob for recursive search
+                for file_path in base_path.rglob(pattern):
+                    # Skip node_modules and virtual environments
+                    if any(
+                        part in file_path.parts
+                        for part in [
+                            "node_modules",
+                            "venv",
+                            ".venv",
+                            "__pycache__",
+                            ".git",
+                        ]
+                    ):
+                        continue
+                    found_files[file_path] = file_type
+
+        return found_files
+
+    def _check_claude_md_placement(self, files: Dict[Path, str]) -> DiagnosticResult:
+        """Check that CLAUDE.md files are properly placed."""
+        claude_files = [
+            path for path, file_type in files.items() if path.name == "CLAUDE.md"
+        ]
+
+        if not claude_files:
+            return DiagnosticResult(
+                category="CLAUDE.md Placement",
+                status=DiagnosticStatus.OK,
+                message="No CLAUDE.md files found",
+                details={},
+            )
+
+        issues = []
+        project_root = Path.cwd()
+
+        for path in claude_files:
+            # CLAUDE.md should only be in project root
+            if path.parent != project_root:
+                rel_path = (
+                    path.relative_to(project_root)
+                    if project_root in path.parents or path.parent == project_root
+                    else path
+                )
+                issues.append(
+                    f"CLAUDE.md found in non-root location: {rel_path}\n"
+                    f"  → Should be in project root only for Claude Code"
+                )
+
+        if issues:
+            return DiagnosticResult(
+                category="CLAUDE.md Placement",
+                status=DiagnosticStatus.WARNING,
+                message=f"Found {len(issues)} misplaced CLAUDE.md file(s)",
+                details={"issues": issues},
+                fix_description=(
+                    "CLAUDE.md should only exist in the project root directory. "
+                    "Move or remove misplaced files."
+                ),
+            )
+
+        return DiagnosticResult(
+            category="CLAUDE.md Placement",
+            status=DiagnosticStatus.OK,
+            message="CLAUDE.md properly placed in project root",
+            details={"count": len(claude_files)},
+        )
+
+    def _check_duplicates(self, files: Dict[Path, str]) -> DiagnosticResult:
+        """Check for duplicate content between instruction files."""
+        if len(files) < 2:
+            return DiagnosticResult(
+                category="Duplicate Content",
+                status=DiagnosticStatus.OK,
+                message="No duplicate content detected",
+                details={},
+            )
+
+        # Calculate content hashes
+        content_hashes = {}
+        content_snippets = defaultdict(list)
+
+        for path in files:
+            try:
+                content = path.read_text(encoding="utf-8")
+                # Hash significant blocks (paragraphs)
+                paragraphs = re.split(r"\n\s*\n", content)
+                for para in paragraphs:
+                    para = para.strip()
+                    if len(para) > 50:  # Skip short snippets
+                        hash_val = hashlib.md5(para.encode()).hexdigest()
+                        content_snippets[hash_val].append((path, para[:100]))
+            except Exception:
+                continue
+
+        # Find duplicates
+        duplicates = []
+        for hash_val, occurrences in content_snippets.items():
+            if len(occurrences) > 1:
+                files_str = ", ".join(str(path) for path, _ in occurrences)
+                snippet = occurrences[0][1]
+                duplicates.append(
+                    f"Duplicate content found in: {files_str}\n"
+                    f"  Snippet: {snippet}..."
+                )
+
+        if duplicates:
+            return DiagnosticResult(
+                category="Duplicate Content",
+                status=DiagnosticStatus.WARNING,
+                message=f"Found {len(duplicates)} duplicate content block(s)",
+                details={"duplicates": duplicates[:5]},  # Limit to first 5
+                fix_description=(
+                    "Remove duplicate content between files. "
+                    "CLAUDE.md should contain Claude Code instructions, "
+                    "INSTRUCTIONS.md should contain MPM-specific customization."
+                ),
+            )
+
+        return DiagnosticResult(
+            category="Duplicate Content",
+            status=DiagnosticStatus.OK,
+            message="No significant duplicate content found",
+            details={},
+        )
+
+    def _check_conflicts(self, files: Dict[Path, str]) -> DiagnosticResult:
+        """Check for conflicting directives between instruction files."""
+        conflicts = []
+        pattern_occurrences = defaultdict(list)
+
+        for path in files:
+            try:
+                content = path.read_text(encoding="utf-8")
+                for pattern, description in self.CONFLICT_PATTERNS:
+                    matches = re.findall(pattern, content, re.MULTILINE)
+                    if matches:
+                        pattern_occurrences[description].append(
+                            (path, len(matches), matches[0][:100])
+                        )
+            except Exception:
+                continue
+
+        # Find patterns that appear in multiple files
+        for description, occurrences in pattern_occurrences.items():
+            if len(occurrences) > 1:
+                files_info = []
+                for path, count, snippet in occurrences:
+                    rel_path = (
+                        path.relative_to(Path.cwd())
+                        if Path.cwd() in path.parents or path.parent == Path.cwd()
+                        else path
+                    )
+                    files_info.append(f"{rel_path} ({count} occurrence(s))")
+
+                conflicts.append(
+                    f"Potential conflict for '{description}':\n"
+                    f"  Found in: {', '.join(files_info)}"
+                )
+
+        if conflicts:
+            return DiagnosticResult(
+                category="Conflicting Directives",
+                status=DiagnosticStatus.ERROR,
+                message=f"Found {len(conflicts)} potential conflict(s)",
+                details={"conflicts": conflicts},
+                fix_description=(
+                    "Review and consolidate conflicting directives. "
+                    "PM role and behavior should be in INSTRUCTIONS.md, "
+                    "Claude Code directives should be in CLAUDE.md."
+                ),
+            )
+
+        return DiagnosticResult(
+            category="Conflicting Directives",
+            status=DiagnosticStatus.OK,
+            message="No conflicting directives detected",
+            details={},
+        )
+
+    def _check_agent_definitions(self, files: Dict[Path, str]) -> DiagnosticResult:
+        """Check for overlapping or duplicate agent definitions."""
+        agent_definitions = defaultdict(list)
+        agent_pattern = r"(?:agent|Agent)\s+(\w+).*?(?:specializes?|expert|handles?)"
+
+        for path in files:
+            try:
+                content = path.read_text(encoding="utf-8")
+                matches = re.findall(agent_pattern, content, re.IGNORECASE)
+                for agent_name in matches:
+                    agent_definitions[agent_name.lower()].append(path)
+            except Exception:
+                continue
+
+        # Find agents defined in multiple places
+        duplicates = []
+        for agent_name, paths in agent_definitions.items():
+            if len(paths) > 1:
+                files_str = ", ".join(
+                    str(
+                        path.relative_to(Path.cwd())
+                        if Path.cwd() in path.parents or path.parent == Path.cwd()
+                        else path
+                    )
+                    for path in paths
+                )
+                duplicates.append(
+                    f"Agent '{agent_name}' defined in multiple files: {files_str}"
+                )
+
+        if duplicates:
+            return DiagnosticResult(
+                category="Agent Definitions",
+                status=DiagnosticStatus.WARNING,
+                message=f"Found {len(duplicates)} duplicate agent definition(s)",
+                details={"duplicates": duplicates},
+                fix_description=(
+                    "Consolidate agent definitions in INSTRUCTIONS.md. "
+                    "Each agent should be defined only once."
+                ),
+            )
+
+        return DiagnosticResult(
+            category="Agent Definitions",
+            status=DiagnosticStatus.OK,
+            message="Agent definitions are unique",
+            details={"total_agents": len(agent_definitions)},
+        )
+
+    def _check_separation_of_concerns(self, files: Dict[Path, str]) -> DiagnosticResult:
+        """Check that instruction files follow proper separation of concerns."""
+        issues = []
+
+        # Check for MPM-specific content in CLAUDE.md
+        claude_files = [path for path in files if path.name == "CLAUDE.md"]
+        for path in claude_files:
+            try:
+                content = path.read_text(encoding="utf-8")
+                # Check for MPM-specific patterns
+                mpm_patterns = [
+                    r"(?i)multi-agent",
+                    r"(?i)delegation",
+                    r"(?i)agent\s+selection",
+                    r"(?i)PM\s+role",
+                ]
+                for pattern in mpm_patterns:
+                    if re.search(pattern, content):
+                        issues.append(
+                            f"CLAUDE.md contains MPM-specific content (pattern: {pattern})\n"
+                            f"  → Move to INSTRUCTIONS.md"
+                        )
+                        break
+            except Exception:
+                continue
+
+        # Check for Claude Code specific content in INSTRUCTIONS.md
+        instructions_files = [
+            path for path in files if path.name == "INSTRUCTIONS.md"
+        ]
+        for path in instructions_files:
+            try:
+                content = path.read_text(encoding="utf-8")
+                # Check for Claude Code specific patterns
+                claude_patterns = [
+                    r"(?i)claude\s+code",
+                    r"(?i)development\s+guidelines",
+                    r"(?i)project\s+structure",
+                ]
+                for pattern in claude_patterns:
+                    if re.search(pattern, content):
+                        issues.append(
+                            f"INSTRUCTIONS.md contains Claude Code content (pattern: {pattern})\n"
+                            f"  → Should focus on MPM customization only"
+                        )
+                        break
+            except Exception:
+                continue
+
+        if issues:
+            return DiagnosticResult(
+                category="Separation of Concerns",
+                status=DiagnosticStatus.WARNING,
+                message=f"Found {len(issues)} separation of concerns issue(s)",
+                details={"issues": issues},
+                fix_description=(
+                    "Maintain clear separation:\n"
+                    "• CLAUDE.md: Claude Code development guidelines\n"
+                    "• INSTRUCTIONS.md: MPM agent behavior and customization\n"
+                    "• BASE_PM.md: Framework requirements (do not modify)"
+                ),
+            )
+
+        return DiagnosticResult(
+            category="Separation of Concerns",
+            status=DiagnosticStatus.OK,
+            message="Instruction files properly separated",
+            details={},
+        )

claude_mpm/services/diagnostics/diagnostic_runner.py

@@ -18,6 +18,7 @@ from .checks import (
     ConfigurationCheck,
     FilesystemCheck,
     InstallationCheck,
+    InstructionsCheck,
     MCPCheck,
     MonitorCheck,
     StartupLogCheck,
@@ -48,6 +49,7 @@ class DiagnosticRunner:
             InstallationCheck,
             ConfigurationCheck,
             FilesystemCheck,
+            InstructionsCheck,  # Check instruction files early
             ClaudeDesktopCheck,
             AgentCheck,
             MCPCheck,
@@ -107,9 +109,20 @@ class DiagnosticRunner:
 
         # Group checks by dependency level
         # Level 1: No dependencies
-        level1 = [InstallationCheck, FilesystemCheck, ConfigurationCheck]
+        level1 = [
+            InstallationCheck,
+            FilesystemCheck,
+            ConfigurationCheck,
+            InstructionsCheck,
+        ]
         # Level 2: May depend on level 1
-        level2 = [ClaudeDesktopCheck, AgentCheck, MCPCheck, MonitorCheck]
+        level2 = [
+            ClaudeDesktopCheck,
+            AgentCheck,
+            MCPCheck,
+            MonitorCheck,
+            StartupLogCheck,
+        ]
         # Level 3: Depends on others
         level3 = [CommonIssuesCheck]