claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/monitor_build_service.py

@@ -0,0 +1,349 @@
+"""Monitor UI Build Tracking Service.
+
+WHY: The Monitor UI needs its own build tracking separate from the main MPM build
+number to track UI-specific changes and deployments independently.
+
+DESIGN DECISION:
+- Uses atomic file operations for thread-safe build number management
+- Stores build number in MONITOR_BUILD file at project root
+- Formats as 4-digit zero-padded strings (0001, 0002, etc.)
+- Provides both sync and async interfaces for flexibility
+"""
+
+import asyncio
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.logger import get_logger
+
+
+class MonitorBuildService(BaseService):
+    """Service for managing Monitor UI build numbers.
+
+    WHY: Separate build tracking allows the Monitor UI to evolve independently
+    of the main MPM framework, enabling rapid UI iterations without affecting
+    core framework versioning.
+    """
+
+    # Default values
+    DEFAULT_BUILD_NUMBER = 1
+    DEFAULT_VERSION = "1.0.0"
+    BUILD_FILE_NAME = "MONITOR_BUILD"
+
+    def __init__(self):
+        """Initialize the monitor build service."""
+        super().__init__(name="monitor_build_service")
+        self.logger = get_logger(self.__class__.__name__)
+
+        # Determine build file location
+        self._build_file_path = self._get_build_file_path()
+
+        # Cache for build info to reduce file I/O
+        self._cached_build_info: Optional[Dict[str, Any]] = None
+        self._cache_lock = asyncio.Lock()
+
+    def _get_build_file_path(self) -> Path:
+        """Get the path to the MONITOR_BUILD file.
+
+        WHY: Centralizes build file location logic, checking multiple
+        possible locations to support different installation scenarios.
+
+        Returns:
+            Path to the MONITOR_BUILD file
+        """
+        # Try project root first (development)
+        try:
+            from claude_mpm.config.paths import paths
+
+            build_file = paths.project_root / self.BUILD_FILE_NAME
+            if build_file.parent.exists():
+                return build_file
+        except ImportError:
+            pass
+
+        # Fallback to package root
+        package_root = Path(__file__).parent.parent.parent
+        return package_root / self.BUILD_FILE_NAME
+
+    async def _initialize(self) -> None:
+        """Initialize the service and ensure build file exists.
+
+        WHY: Ensures the build file exists with default values on first run,
+        preventing errors and providing a clean starting point.
+        """
+        await self._ensure_build_file_exists()
+        await self._load_build_info()
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources."""
+        self._cached_build_info = None
+
+    async def _ensure_build_file_exists(self) -> None:
+        """Ensure the MONITOR_BUILD file exists with default values.
+
+        WHY: Atomic file creation prevents race conditions when multiple
+        processes might try to create the file simultaneously.
+        """
+        if not self._build_file_path.exists():
+            default_info = {
+                "build_number": self.DEFAULT_BUILD_NUMBER,
+                "version": self.DEFAULT_VERSION,
+                "last_updated": None,
+            }
+            await self._write_build_info(default_info)
+            self.logger.info(f"Created MONITOR_BUILD file at {self._build_file_path}")
+
+    async def _load_build_info(self) -> Dict[str, Any]:
+        """Load build information from file.
+
+        WHY: Centralizes file reading with error handling and caching
+        to improve performance and reliability.
+
+        Returns:
+            Dictionary with build information
+        """
+        async with self._cache_lock:
+            try:
+                if self._build_file_path.exists():
+                    content = self._build_file_path.read_text().strip()
+
+                    # Try to parse as JSON first
+                    try:
+                        self._cached_build_info = json.loads(content)
+                    except json.JSONDecodeError:
+                        # Fallback: treat as plain build number
+                        try:
+                            build_num = int(content)
+                            self._cached_build_info = {
+                                "build_number": build_num,
+                                "version": self.DEFAULT_VERSION,
+                                "last_updated": None,
+                            }
+                        except ValueError:
+                            # Invalid content, use defaults
+                            self._cached_build_info = {
+                                "build_number": self.DEFAULT_BUILD_NUMBER,
+                                "version": self.DEFAULT_VERSION,
+                                "last_updated": None,
+                            }
+                else:
+                    self._cached_build_info = {
+                        "build_number": self.DEFAULT_BUILD_NUMBER,
+                        "version": self.DEFAULT_VERSION,
+                        "last_updated": None,
+                    }
+            except Exception as e:
+                self.logger.error(f"Error loading build info: {e}")
+                self._cached_build_info = {
+                    "build_number": self.DEFAULT_BUILD_NUMBER,
+                    "version": self.DEFAULT_VERSION,
+                    "last_updated": None,
+                }
+
+            return self._cached_build_info
+
+    async def _write_build_info(self, info: Dict[str, Any]) -> None:
+        """Write build information to file atomically.
+
+        WHY: Atomic writes prevent file corruption if the process is
+        interrupted during the write operation.
+
+        Args:
+            info: Build information dictionary
+        """
+        # Add timestamp
+        from datetime import datetime, timezone
+
+        info["last_updated"] = datetime.now(timezone.utc).isoformat()
+
+        # Write atomically using temp file and rename
+        temp_fd, temp_path = tempfile.mkstemp(
+            dir=self._build_file_path.parent, prefix=".monitor_build_", suffix=".tmp"
+        )
+
+        try:
+            # Write JSON content
+            with os.fdopen(temp_fd, "w") as f:
+                json.dump(info, f, indent=2)
+
+            # Atomic rename
+            Path(temp_path).replace(self._build_file_path)
+
+            # Update cache
+            async with self._cache_lock:
+                self._cached_build_info = info
+
+        except Exception as e:
+            # Clean up temp file on error
+            Path(temp_path).unlink(missing_ok=True)
+            raise e
+
+    async def get_build_number(self) -> int:
+        """Get the current monitor build number.
+
+        Returns:
+            Current build number as integer
+        """
+        info = await self._load_build_info()
+        return info.get("build_number", self.DEFAULT_BUILD_NUMBER)
+
+    async def get_formatted_build_number(self) -> str:
+        """Get the current build number as a 4-digit string.
+
+        WHY: Consistent 4-digit formatting ensures proper sorting
+        and display alignment in the UI.
+
+        Returns:
+            Build number as 4-digit zero-padded string
+        """
+        build_num = await self.get_build_number()
+        return f"{build_num:04d}"
+
+    async def increment_build_number(self) -> int:
+        """Increment and return the new build number.
+
+        WHY: Atomic increment operation ensures no build numbers are
+        skipped or duplicated even with concurrent access.
+
+        Returns:
+            New build number after incrementing
+        """
+        info = await self._load_build_info()
+        new_build = info.get("build_number", self.DEFAULT_BUILD_NUMBER) + 1
+        info["build_number"] = new_build
+        await self._write_build_info(info)
+
+        self.logger.info(f"Monitor build number incremented to {new_build:04d}")
+        return new_build
+
+    async def get_monitor_version(self) -> str:
+        """Get the monitor UI version.
+
+        Returns:
+            Monitor UI semantic version string
+        """
+        info = await self._load_build_info()
+        return info.get("version", self.DEFAULT_VERSION)
+
+    async def set_monitor_version(self, version: str) -> None:
+        """Set the monitor UI version.
+
+        Args:
+            version: New semantic version string
+        """
+        info = await self._load_build_info()
+        info["version"] = version
+        await self._write_build_info(info)
+        self.logger.info(f"Monitor version updated to {version}")
+
+    async def get_full_version_string(self) -> str:
+        """Get the full version string for display.
+
+        WHY: Combines semantic version with build number for complete
+        version identification in the UI.
+
+        Returns:
+            Full version string (e.g., "v1.0.0-0001")
+        """
+        version = await self.get_monitor_version()
+        build = await self.get_formatted_build_number()
+        return f"v{version}-{build}"
+
+    async def get_build_info(self) -> Dict[str, Any]:
+        """Get complete build information.
+
+        WHY: Provides all build metadata in a single call for
+        efficient transmission to the UI via SocketIO.
+
+        Returns:
+            Dictionary with all build information
+        """
+        info = await self._load_build_info()
+
+        # Get MPM version info
+        mpm_version = "unknown"
+        mpm_build = "unknown"
+
+        try:
+            from claude_mpm.services.version_service import VersionService
+
+            version_service = VersionService()
+            version_info = version_service.get_version_info()
+            mpm_version = version_info.get("base_version", "unknown")
+            mpm_build = version_info.get("build_number", "unknown")
+        except Exception as e:
+            self.logger.debug(f"Could not get MPM version info: {e}")
+
+        return {
+            "monitor": {
+                "version": info.get("version", self.DEFAULT_VERSION),
+                "build": info.get("build_number", self.DEFAULT_BUILD_NUMBER),
+                "formatted_build": f"{info.get('build_number', self.DEFAULT_BUILD_NUMBER):04d}",
+                "full_version": await self.get_full_version_string(),
+                "last_updated": info.get("last_updated"),
+            },
+            "mpm": {
+                "version": mpm_version,
+                "build": mpm_build,
+                "full_version": (
+                    f"v{mpm_version}-build.{mpm_build}"
+                    if mpm_build != "unknown"
+                    else f"v{mpm_version}"
+                ),
+            },
+        }
+
+    # Synchronous convenience methods for non-async contexts
+
+    def get_build_number_sync(self) -> int:
+        """Synchronous version of get_build_number.
+
+        WHY: Some contexts (like SocketIO handlers) may not support
+        async operations directly.
+
+        Returns:
+            Current build number as integer
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self.get_build_number())
+        finally:
+            loop.close()
+
+    def get_build_info_sync(self) -> Dict[str, Any]:
+        """Synchronous version of get_build_info.
+
+        WHY: SocketIO connection handlers often need synchronous
+        access to build information.
+
+        Returns:
+            Dictionary with all build information
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self.get_build_info())
+        finally:
+            loop.close()
+
+
+# Global instance for singleton pattern
+_monitor_build_service: Optional[MonitorBuildService] = None
+
+
+def get_monitor_build_service() -> MonitorBuildService:
+    """Get or create the global monitor build service instance.
+
+    WHY: Singleton pattern ensures consistent build number management
+    across the application.
+
+    Returns:
+        The global MonitorBuildService instance
+    """
+    global _monitor_build_service
+    if _monitor_build_service is None:
+        _monitor_build_service = MonitorBuildService()
+    return _monitor_build_service

claude_mpm/services/native_agent_converter.py

@@ -0,0 +1,356 @@
+"""Native Agent Converter Service
+
+Converts MPM agent JSON definitions to Claude Code --agents flag format.
+
+WHY: Claude Code 1.0.83+ supports native --agents flag for dynamic agent definition.
+This allows agents to be passed directly via CLI instead of deployed to .claude/agents/.
+
+DESIGN: Converts MPM agent schema → Claude native schema with field mappings:
+- description → description (agent selection hint)
+- system_instructions → prompt (agent behavior)
+- allowed_tools → tools (tool limitations)
+- model_tier → model (model selection)
+
+USAGE:
+    converter = NativeAgentConverter()
+    agents_flag = converter.build_agents_flag(agent_configs)
+    # Returns: --agents '{"agent-name": {...}, ...}'
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_config import get_logger
+
+
+class NativeAgentConverter:
+    """Converts MPM agent configurations to Claude Code --agents format."""
+
+    # Map MPM model tiers to Claude model names
+    MODEL_TIER_MAP = {
+        "opus": "opus",
+        "sonnet": "sonnet",
+        "haiku": "haiku",
+        "claude-3-opus": "opus",
+        "claude-3-sonnet": "sonnet",
+        "claude-3-haiku": "haiku",
+        "claude-3.5-sonnet": "sonnet",
+        "claude-4-sonnet": "sonnet",
+        "claude-4-opus": "opus",
+    }
+
+    # Map MPM tool names to Claude tool names
+    TOOL_NAME_MAP = {
+        "Read": "Read",
+        "Write": "Write",
+        "Edit": "Edit",
+        "MultiEdit": "MultiEdit",
+        "Bash": "Bash",
+        "Grep": "Grep",
+        "Glob": "Glob",
+        "LS": "LS",
+        "WebSearch": "WebSearch",
+        "WebFetch": "WebFetch",
+        "TodoWrite": "TodoWrite",
+        "NotebookEdit": "NotebookEdit",
+        "BashOutput": "BashOutput",
+        "KillShell": "KillShell",
+        "AskUserQuestion": "AskUserQuestion",
+    }
+
+    def __init__(self):
+        """Initialize the native agent converter."""
+        self.logger = get_logger(__name__)
+
+    def convert_mpm_agent_to_native(
+        self, agent_config: Dict[str, Any], agent_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Convert a single MPM agent config to Claude native format.
+
+        Args:
+            agent_config: MPM agent JSON configuration
+            agent_id: Optional agent ID (falls back to agent_config['agent_id'])
+
+        Returns:
+            Dict with Claude native agent format:
+            {
+                "description": "...",
+                "prompt": "...",
+                "tools": [...],
+                "model": "sonnet"
+            }
+        """
+        try:
+            # Extract agent ID
+            if not agent_id:
+                agent_id = agent_config.get("agent_id") or agent_config.get("name", "")
+
+            # Extract description (for agent selection)
+            description = agent_config.get("description", "")
+            if not description and "metadata" in agent_config:
+                description = agent_config["metadata"].get("description", "")
+
+            # Build prompt from instructions and BASE_*.md reference
+            prompt = self._build_agent_prompt(agent_config)
+
+            # Extract and map tools
+            tools = self._extract_and_map_tools(agent_config)
+
+            # Map model tier
+            model = self._map_model_tier(agent_config)
+
+            native_config = {
+                "description": description,
+                "prompt": prompt,
+                "tools": tools,
+                "model": model,
+            }
+
+            self.logger.debug(f"Converted agent '{agent_id}' to native format")
+            return native_config
+
+        except Exception as e:
+            self.logger.error(f"Error converting agent {agent_id}: {e}")
+            # Return minimal valid config as fallback
+            return {
+                "description": f"Agent {agent_id}",
+                "prompt": agent_config.get("instructions", ""),
+                "tools": [],
+                "model": "sonnet",
+            }
+
+    def _build_agent_prompt(self, agent_config: Dict[str, Any]) -> str:
+        """Build agent prompt from instructions and BASE_*.md reference.
+
+        OPTIMIZATION: Keep prompts concise for CLI argument length limits.
+        The BASE_*.md files contain full instructions, so we only need:
+        1. Reference to BASE file
+        2. Brief specialization note
+
+        Args:
+            agent_config: MPM agent configuration
+
+        Returns:
+            Concise prompt string
+        """
+        prompt_parts = []
+
+        # Add base instructions reference if available (most important)
+        if "knowledge" in agent_config:
+            base_file = agent_config["knowledge"].get("base_instructions_file")
+            if base_file:
+                prompt_parts.append(f"Follow {base_file} for all protocols.")
+
+        # Add main instructions (keep brief)
+        instructions = agent_config.get("instructions", "")
+        if instructions:
+            # Limit instruction length to avoid bloat
+            if len(instructions) > 300:
+                instructions = instructions[:300] + "..."
+            prompt_parts.append(instructions)
+
+        # Skip domain expertise and best practices for CLI mode
+        # These are already in BASE_*.md files referenced above
+        # Adding them here just bloats the JSON unnecessarily
+
+        return "\n".join(str(part) for part in prompt_parts if part)
+
+    def _extract_and_map_tools(self, agent_config: Dict[str, Any]) -> List[str]:
+        """Extract and map tools from MPM config to Claude tool names.
+
+        Args:
+            agent_config: MPM agent configuration
+
+        Returns:
+            List of Claude tool names
+        """
+        tools = []
+
+        # Check capabilities.tools
+        if "capabilities" in agent_config and "tools" in agent_config["capabilities"]:
+            mpm_tools = agent_config["capabilities"]["tools"]
+            for tool in mpm_tools:
+                mapped_tool = self.TOOL_NAME_MAP.get(tool, tool)
+                if mapped_tool not in tools:
+                    tools.append(mapped_tool)
+
+        # If no tools specified, provide reasonable defaults
+        if not tools:
+            tools = ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+
+        return tools
+
+    def _map_model_tier(self, agent_config: Dict[str, Any]) -> str:
+        """Map MPM model tier to Claude model name.
+
+        Args:
+            agent_config: MPM agent configuration
+
+        Returns:
+            Claude model name (opus, sonnet, haiku)
+        """
+        # Check capabilities.model
+        if "capabilities" in agent_config and "model" in agent_config["capabilities"]:
+            model_tier = agent_config["capabilities"]["model"]
+            return self.MODEL_TIER_MAP.get(model_tier.lower(), "sonnet")
+
+        # Check metadata.model_preference
+        if (
+            "metadata" in agent_config
+            and "model_preference" in agent_config["metadata"]
+        ):
+            model_tier = agent_config["metadata"]["model_preference"]
+            return self.MODEL_TIER_MAP.get(model_tier.lower(), "sonnet")
+
+        # Default to sonnet
+        return "sonnet"
+
+    def generate_agents_json(self, agents: List[Dict[str, Any]]) -> str:
+        """Generate complete --agents JSON string from list of agent configs.
+
+        Args:
+            agents: List of MPM agent configurations
+
+        Returns:
+            JSON string for --agents flag
+        """
+        native_agents = {}
+
+        for agent_config in agents:
+            agent_id = agent_config.get("agent_id") or agent_config.get("name", "")
+            if not agent_id:
+                self.logger.warning("Skipping agent without ID")
+                continue
+
+            # Skip PM agent (main Claude instance)
+            if agent_id.lower() in ["pm", "project_manager"]:
+                self.logger.debug(f"Skipping PM agent: {agent_id}")
+                continue
+
+            native_config = self.convert_mpm_agent_to_native(agent_config, agent_id)
+            native_agents[agent_id] = native_config
+
+        return json.dumps(native_agents, separators=(",", ":"))
+
+    def build_agents_flag(
+        self, agents: List[Dict[str, Any]], escape_for_shell: bool = True
+    ) -> str:
+        """Build complete --agents flag for CLI.
+
+        Args:
+            agents: List of MPM agent configurations
+            escape_for_shell: Whether to escape JSON for shell
+
+        Returns:
+            Complete flag string: --agents '{"agent1": {...}, ...}'
+        """
+        agents_json = self.generate_agents_json(agents)
+
+        # Check length (Claude CLI has argument length limits)
+        if len(agents_json) > 50000:  # Conservative limit
+            self.logger.warning(
+                f"Agents JSON is very large ({len(agents_json)} chars). "
+                "Consider using file-based deployment."
+            )
+
+        if escape_for_shell:
+            # Escape for shell - wrap in single quotes
+            return f"--agents '{agents_json}'"
+
+        return f"--agents {agents_json}"
+
+    def load_agents_from_templates(
+        self, templates_dir: Optional[Path] = None
+    ) -> List[Dict[str, Any]]:
+        """Load all agent configs from templates directory.
+
+        Args:
+            templates_dir: Path to templates directory (defaults to MPM agents)
+
+        Returns:
+            List of agent configurations
+        """
+        if not templates_dir:
+            # Default to MPM agents directory
+            mpm_package_dir = Path(__file__).parent.parent / "agents" / "templates"
+            templates_dir = mpm_package_dir
+
+        if not templates_dir.exists():
+            self.logger.warning(f"Templates directory not found: {templates_dir}")
+            return []
+
+        agents = []
+        json_files = list(templates_dir.glob("*.json"))
+
+        self.logger.info(
+            f"Loading {len(json_files)} agent templates from {templates_dir}"
+        )
+
+        for json_file in json_files:
+            try:
+                # Skip base_agent.json
+                if json_file.stem == "base_agent":
+                    continue
+
+                agent_config = json.loads(json_file.read_text())
+                agents.append(agent_config)
+                self.logger.debug(f"Loaded agent: {json_file.stem}")
+
+            except Exception as e:
+                self.logger.error(f"Error loading agent {json_file.name}: {e}")
+                continue
+
+        return agents
+
+    def estimate_json_size(self, agents: List[Dict[str, Any]]) -> int:
+        """Estimate the size of --agents JSON output.
+
+        Args:
+            agents: List of agent configurations
+
+        Returns:
+            Estimated size in bytes
+        """
+        agents_json = self.generate_agents_json(agents)
+        return len(agents_json.encode("utf-8"))
+
+    def get_conversion_summary(self, agents: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Get summary of agent conversion for reporting.
+
+        Args:
+            agents: List of agent configurations
+
+        Returns:
+            Summary dict with counts and size info
+        """
+        native_agents = {}
+        model_counts = {"opus": 0, "sonnet": 0, "haiku": 0}
+        tool_usage = {}
+
+        for agent_config in agents:
+            agent_id = agent_config.get("agent_id") or agent_config.get("name", "")
+            if not agent_id or agent_id.lower() in ["pm", "project_manager"]:
+                continue
+
+            native_config = self.convert_mpm_agent_to_native(agent_config, agent_id)
+            native_agents[agent_id] = native_config
+
+            # Count models
+            model = native_config.get("model", "sonnet")
+            model_counts[model] = model_counts.get(model, 0) + 1
+
+            # Count tools
+            for tool in native_config.get("tools", []):
+                tool_usage[tool] = tool_usage.get(tool, 0) + 1
+
+        json_size = len(json.dumps(native_agents, separators=(",", ":")))
+
+        return {
+            "total_agents": len(native_agents),
+            "json_size": json_size,
+            "json_size_kb": round(json_size / 1024, 2),
+            "model_distribution": model_counts,
+            "tool_usage": tool_usage,
+            "agents": list(native_agents.keys()),
+        }