claude-mpm 4.1.26__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/services/agents/deployment/local_template_deployment.py

@@ -0,0 +1,360 @@
+"""Local Template Deployment Service for Claude MPM.
+
+This module handles the deployment of local JSON agent templates to Claude Code's
+.claude/agents directory. It converts JSON templates to YAML format while preserving
+local metadata and ensuring proper priority handling.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from claude_mpm.core.logging_config import get_logger
+from claude_mpm.services.agents.local_template_manager import (
+    LocalAgentTemplate,
+    LocalAgentTemplateManager,
+)
+
+logger = get_logger(__name__)
+
+
+class LocalTemplateDeploymentService:
+    """Service for deploying local JSON templates to Claude Code."""
+
+    def __init__(self, working_directory: Optional[Path] = None):
+        """Initialize the local template deployment service.
+
+        Args:
+            working_directory: Working directory for project-level agents
+        """
+        self.working_directory = working_directory or Path.cwd()
+        self.template_manager = LocalAgentTemplateManager(working_directory)
+
+        # Target directory for Claude Code agents
+        self.target_dir = self.working_directory / ".claude" / "agents"
+
+        logger.info(
+            f"LocalTemplateDeploymentService initialized for: {self.working_directory}"
+        )
+
+    def deploy_local_templates(
+        self, force_rebuild: bool = False, tier_filter: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Deploy all local JSON templates to Claude Code.
+
+        Args:
+            force_rebuild: Force rebuild even if agents exist
+            tier_filter: Filter by tier ('project' or 'user')
+
+        Returns:
+            Deployment results dictionary
+        """
+        results = {
+            "deployed": [],
+            "updated": [],
+            "skipped": [],
+            "errors": [],
+            "total": 0,
+        }
+
+        # Ensure target directory exists
+        self.target_dir.mkdir(parents=True, exist_ok=True)
+
+        # Discover local templates
+        templates = self.template_manager.discover_local_templates()
+
+        # Filter by tier if requested
+        if tier_filter:
+            templates = {
+                agent_id: template
+                for agent_id, template in templates.items()
+                if template.tier == tier_filter
+            }
+
+        results["total"] = len(templates)
+
+        # Deploy each template
+        for agent_id, template in templates.items():
+            try:
+                deployed = self._deploy_single_template(template, force_rebuild)
+
+                if deployed == "deployed":
+                    results["deployed"].append(agent_id)
+                elif deployed == "updated":
+                    results["updated"].append(agent_id)
+                else:
+                    results["skipped"].append(agent_id)
+
+            except Exception as e:
+                logger.error(f"Failed to deploy local template {agent_id}: {e}")
+                results["errors"].append(f"{agent_id}: {e}")
+
+        logger.debug(
+            f"Local template deployment: deployed={len(results['deployed'])}, "
+            f"updated={len(results['updated'])}, skipped={len(results['skipped'])}, "
+            f"errors={len(results['errors'])}"
+        )
+
+        return results
+
+    def _deploy_single_template(
+        self, template: LocalAgentTemplate, force_rebuild: bool
+    ) -> str:
+        """Deploy a single local template.
+
+        Args:
+            template: Template to deploy
+            force_rebuild: Force rebuild even if exists
+
+        Returns:
+            'deployed', 'updated', or 'skipped'
+        """
+        target_file = self.target_dir / f"{template.agent_id}.md"
+
+        # Check if needs update
+        if not force_rebuild and target_file.exists():
+            # Check version
+            existing_version = self._get_existing_version(target_file)
+            if existing_version and existing_version >= template.agent_version:
+                logger.debug(
+                    f"Skipping {template.agent_id}: version {existing_version} >= {template.agent_version}"
+                )
+                return "skipped"
+
+        # Convert JSON template to YAML frontmatter format
+        yaml_content = self._convert_to_yaml_format(template)
+
+        # Write to target file
+        action = "updated" if target_file.exists() else "deployed"
+        target_file.write_text(yaml_content)
+
+        logger.info(
+            f"{action.capitalize()} local agent {template.agent_id} (v{template.agent_version})"
+        )
+        return action
+
+    def _convert_to_yaml_format(self, template: LocalAgentTemplate) -> str:
+        """Convert local JSON template to YAML frontmatter format.
+
+        Args:
+            template: Template to convert
+
+        Returns:
+            YAML formatted agent content
+        """
+        # Build frontmatter
+        frontmatter = {
+            "name": template.metadata.get("name", template.agent_id),
+            "description": template.metadata.get("description", ""),
+            "version": template.agent_version,
+            "author": template.author,
+            "tier": template.tier,
+            "priority": template.priority,
+            "tags": template.metadata.get("tags", ["local"]),
+            "specializations": template.metadata.get("specializations", []),
+        }
+
+        # Add capabilities
+        if template.capabilities:
+            frontmatter["model"] = template.capabilities.get("model", "sonnet")
+            tools = template.capabilities.get("tools", "*")
+            if tools == "*":
+                frontmatter["tools"] = "all"
+            elif isinstance(tools, list):
+                frontmatter["tools"] = tools
+            else:
+                frontmatter["tools"] = tools.split(",") if "," in tools else [tools]
+
+        # Add configuration if present
+        if template.configuration:
+            frontmatter["temperature"] = template.configuration.get("temperature", 0.7)
+            frontmatter["max_tokens"] = template.configuration.get("max_tokens", 4096)
+
+        # Add parent agent reference if present
+        if template.parent_agent:
+            frontmatter["parent_agent"] = template.parent_agent
+
+        # Add local indicator
+        frontmatter["is_local"] = True
+
+        # Build YAML content
+        yaml_str = yaml.dump(frontmatter, default_flow_style=False, sort_keys=False)
+
+        # Combine with instructions
+        content = f"---\n{yaml_str}---\n\n# {frontmatter['name']}\n\n{frontmatter['description']}\n\n"
+
+        # Add instructions
+        if template.instructions:
+            content += "## Instructions\n\n"
+            content += template.instructions + "\n"
+        else:
+            content += "## Instructions\n\n"
+            content += f"This is a local {template.agent_id} agent for the {template.author} project.\n"
+
+        # Add inheritance note if applicable
+        if template.parent_agent:
+            content += f"\n## Inheritance\n\nThis agent inherits from: {template.parent_agent}\n"
+
+        return content
+
+    def _get_existing_version(self, agent_file: Path) -> Optional[str]:
+        """Get version from existing agent file.
+
+        Args:
+            agent_file: Path to agent file
+
+        Returns:
+            Version string if found, None otherwise
+        """
+        try:
+            content = agent_file.read_text()
+
+            # Parse YAML frontmatter
+            if content.startswith("---"):
+                end_marker = content.find("---", 3)
+                if end_marker != -1:
+                    frontmatter_str = content[3:end_marker].strip()
+                    frontmatter = yaml.safe_load(frontmatter_str)
+                    return frontmatter.get("version")
+
+        except Exception as e:
+            logger.debug(f"Could not extract version from {agent_file}: {e}")
+
+        return None
+
+    def deploy_single_local_template(
+        self, agent_id: str, force_rebuild: bool = False
+    ) -> bool:
+        """Deploy a specific local template by ID.
+
+        Args:
+            agent_id: ID of agent to deploy
+            force_rebuild: Force rebuild even if exists
+
+        Returns:
+            True if deployed successfully, False otherwise
+        """
+        template = self.template_manager.get_local_template(agent_id)
+        if not template:
+            logger.error(f"Local template not found: {agent_id}")
+            return False
+
+        try:
+            result = self._deploy_single_template(template, force_rebuild)
+            return result in ["deployed", "updated"]
+        except Exception as e:
+            logger.error(f"Failed to deploy local template {agent_id}: {e}")
+            return False
+
+    def list_deployed_local_agents(self) -> List[Dict[str, Any]]:
+        """List all deployed local agents.
+
+        Returns:
+            List of deployed local agent information
+        """
+        deployed = []
+
+        if not self.target_dir.exists():
+            return deployed
+
+        for agent_file in self.target_dir.glob("*.md"):
+            try:
+                content = agent_file.read_text()
+
+                # Parse YAML frontmatter
+                if content.startswith("---"):
+                    end_marker = content.find("---", 3)
+                    if end_marker != -1:
+                        frontmatter_str = content[3:end_marker].strip()
+                        frontmatter = yaml.safe_load(frontmatter_str)
+
+                        # Check if it's a local agent
+                        if frontmatter.get("is_local") or frontmatter.get("tier") in [
+                            "project",
+                            "user",
+                        ]:
+                            deployed.append(
+                                {
+                                    "id": agent_file.stem,
+                                    "name": frontmatter.get("name", agent_file.stem),
+                                    "version": frontmatter.get("version", "unknown"),
+                                    "author": frontmatter.get("author", "unknown"),
+                                    "tier": frontmatter.get("tier", "unknown"),
+                                    "tags": frontmatter.get("tags", []),
+                                    "file": str(agent_file),
+                                }
+                            )
+
+            except Exception as e:
+                logger.debug(f"Could not parse {agent_file}: {e}")
+
+        return deployed
+
+    def clean_local_deployments(self) -> int:
+        """Remove all deployed local agents.
+
+        Returns:
+            Number of agents removed
+        """
+        count = 0
+        deployed = self.list_deployed_local_agents()
+
+        for agent_info in deployed:
+            try:
+                agent_file = Path(agent_info["file"])
+                if agent_file.exists():
+                    agent_file.unlink()
+                    count += 1
+                    logger.info(f"Removed deployed local agent: {agent_info['id']}")
+            except Exception as e:
+                logger.error(f"Failed to remove {agent_info['id']}: {e}")
+
+        return count
+
+    def sync_local_templates(self) -> Dict[str, Any]:
+        """Synchronize local templates with deployed agents.
+
+        This ensures deployed agents match their source templates.
+
+        Returns:
+            Sync results dictionary
+        """
+        results = {"updated": [], "removed": [], "added": [], "errors": []}
+
+        # Get current state
+        templates = self.template_manager.discover_local_templates()
+        deployed = {agent["id"]: agent for agent in self.list_deployed_local_agents()}
+
+        # Check for updates and additions
+        for agent_id, template in templates.items():
+            if agent_id in deployed:
+                # Check if needs update
+                if deployed[agent_id][
+                    "version"
+                ] != template.agent_version and self.deploy_single_local_template(
+                    agent_id, force_rebuild=True
+                ):
+                    results["updated"].append(agent_id)
+            # New agent to deploy
+            elif self.deploy_single_local_template(agent_id):
+                results["added"].append(agent_id)
+
+        # Check for orphaned deployments (deployed but no template)
+        for agent_id in deployed:
+            if agent_id not in templates:
+                try:
+                    agent_file = Path(deployed[agent_id]["file"])
+                    agent_file.unlink()
+                    results["removed"].append(agent_id)
+                    logger.info(f"Removed orphaned local agent: {agent_id}")
+                except Exception as e:
+                    logger.error(f"Failed to remove orphaned agent {agent_id}: {e}")
+                    results["errors"].append(f"{agent_id}: {e}")
+
+        logger.info(
+            f"Sync complete: added={len(results['added'])}, "
+            f"updated={len(results['updated'])}, removed={len(results['removed'])}"
+        )
+
+        return results

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -176,23 +176,47 @@ class MultiSourceAgentDeploymentService:
                 # Log if a higher priority source was overridden by version
                 for other_agent in agent_versions:
                     if other_agent != highest_version_agent:
-                        self.version_manager.parse_version(
+                        # Parse both versions for comparison
+                        other_version = self.version_manager.parse_version(
                             other_agent.get("version", "0.0.0")
                         )
-                        if (
-                            other_agent["source"] == "project"
-                            and highest_version_agent["source"] == "system"
+                        highest_version = self.version_manager.parse_version(
+                            highest_version_agent.get("version", "0.0.0")
+                        )
+
+                        # Compare the versions
+                        version_comparison = self.version_manager.compare_versions(
+                            other_version, highest_version
+                        )
+
+                        # Only warn if the other version is actually lower
+                        if version_comparison < 0:
+                            if (
+                                other_agent["source"] == "project"
+                                and highest_version_agent["source"] == "system"
+                            ):
+                                self.logger.warning(
+                                    f"Project agent '{agent_name}' v{other_agent['version']} "
+                                    f"overridden by higher system version v{highest_version_agent['version']}"
+                                )
+                            elif other_agent[
+                                "source"
+                            ] == "user" and highest_version_agent["source"] in [
+                                "system",
+                                "project",
+                            ]:
+                                self.logger.warning(
+                                    f"User agent '{agent_name}' v{other_agent['version']} "
+                                    f"overridden by higher {highest_version_agent['source']} version v{highest_version_agent['version']}"
+                                )
+                        elif (
+                            version_comparison == 0
+                            and other_agent["source"] != highest_version_agent["source"]
                         ):
-                            self.logger.warning(
-                                f"Project agent '{agent_name}' v{other_agent['version']} "
-                                f"overridden by higher system version v{highest_version_agent['version']}"
-                            )
-                        elif other_agent["source"] == "user" and highest_version_agent[
-                            "source"
-                        ] in ["system", "project"]:
-                            self.logger.warning(
-                                f"User agent '{agent_name}' v{other_agent['version']} "
-                                f"overridden by higher {highest_version_agent['source']} version v{highest_version_agent['version']}"
+                            # Log info when versions are equal but different sources
+                            self.logger.info(
+                                f"Using {highest_version_agent['source']} source for '{agent_name}' "
+                                f"(same version v{highest_version_agent['version']} as {other_agent['source']} source)"
                             )
 
         return selected_agents
@@ -469,6 +493,47 @@ class MultiSourceAgentDeploymentService:
 
         return cleanup_results
 
+    def _is_user_created_agent(self, agent_file: Path) -> bool:
+        """Check if an agent is user-created based on metadata.
+
+        User agents are identified by:
+        - Lack of MPM authorship indicators
+        - Missing version or v0.0.0
+        - Certain naming patterns
+
+        Args:
+            agent_file: Path to the agent file to check
+
+        Returns:
+            True if the agent appears to be user-created, False otherwise
+        """
+        try:
+            content = agent_file.read_text()
+
+            # Check for MPM authorship indicators
+            mpm_indicators = [
+                "author: claude-mpm",
+                "author: 'claude-mpm'",
+                'author: "claude-mpm"',
+                "author: Claude MPM",
+                "Claude MPM Team",
+                "Generated by Claude MPM",
+                "claude-mpm-project",
+            ]
+
+            for indicator in mpm_indicators:
+                if indicator.lower() in content.lower():
+                    return False  # This is an MPM agent
+
+            # Check for version 0.0.0 (typical user agent default)
+            if "version: 0.0.0" in content or "version: '0.0.0'" in content:
+                return True
+
+            return True  # Default to user-created if no MPM indicators
+
+        except Exception:
+            return True  # Default to user-created if we can't read it
+
     def _apply_config_filters(
         self, selected_agents: Dict[str, Dict[str, Any]], config: Config
     ) -> Dict[str, Dict[str, Any]]:
@@ -534,7 +599,8 @@ class MultiSourceAgentDeploymentService:
             "needs_update": [],
             "up_to_date": [],
             "new_agents": [],
-            "orphaned_agents": [],  # Agents without templates
+            "orphaned_agents": [],  # System agents without templates
+            "user_agents": [],  # User-created agents (no templates required)
             "version_upgrades": [],
             "version_downgrades": [],
             "source_changes": [],
@@ -655,10 +721,11 @@ class MultiSourceAgentDeploymentService:
                 )
 
         # Check for orphaned agents (deployed but no template)
-        orphaned = self._detect_orphaned_agents_simple(
+        system_orphaned, user_orphaned = self._detect_orphaned_agents_simple(
             deployed_agents_dir, agents_to_deploy
         )
-        comparison_results["orphaned_agents"] = orphaned
+        comparison_results["orphaned_agents"] = system_orphaned
+        comparison_results["user_agents"] = user_orphaned
 
         # Log summary
         summary_parts = [
@@ -668,23 +735,29 @@ class MultiSourceAgentDeploymentService:
         ]
         if comparison_results["orphaned_agents"]:
             summary_parts.append(
-                f"{len(comparison_results['orphaned_agents'])} orphaned"
+                f"{len(comparison_results['orphaned_agents'])} system orphaned"
+            )
+        if comparison_results["user_agents"]:
+            summary_parts.append(
+                f"{len(comparison_results['user_agents'])} user agents"
             )
 
         self.logger.info(f"Version comparison complete: {', '.join(summary_parts)}")
 
+        # Don't log upgrades here - let the caller decide when to log
+        # This prevents repeated upgrade messages on every startup
         if comparison_results["version_upgrades"]:
             for upgrade in comparison_results["version_upgrades"]:
-                self.logger.info(
-                    f"  Upgrade: {upgrade['name']} "
+                self.logger.debug(
+                    f"  Upgrade available: {upgrade['name']} "
                     f"{upgrade['deployed_version']} -> {upgrade['new_version']} "
                     f"(from {upgrade['source']})"
                 )
 
         if comparison_results["source_changes"]:
             for change in comparison_results["source_changes"]:
-                self.logger.info(
-                    f"  Source change: {change['name']} "
+                self.logger.debug(
+                    f"  Source change available: {change['name']} "
                     f"from {change['from_source']} to {change['to_source']}"
                 )
 
@@ -698,10 +771,10 @@ class MultiSourceAgentDeploymentService:
                     f"{downgrade['template_version']} (keeping deployed version)"
                 )
 
-        # Log orphaned agents if found
+        # Log system orphaned agents if found
         if comparison_results["orphaned_agents"]:
             self.logger.info(
-                f"Found {len(comparison_results['orphaned_agents'])} orphaned agent(s) "
+                f"Found {len(comparison_results['orphaned_agents'])} system orphaned agent(s) "
                 f"(deployed without templates):"
             )
             for orphan in comparison_results["orphaned_agents"]:
@@ -710,6 +783,18 @@ class MultiSourceAgentDeploymentService:
                     f"(consider removing or creating a template)"
                 )
 
+        # Log user agents at debug level if found
+        if comparison_results["user_agents"]:
+            self.logger.debug(
+                f"Found {len(comparison_results['user_agents'])} user-created agent(s) "
+                f"(no templates required):"
+            )
+            for user_agent in comparison_results["user_agents"]:
+                self.logger.debug(
+                    f"  - {user_agent['name']} v{user_agent['version']} "
+                    f"(user-created agent)"
+                )
+
         return comparison_results
 
     def _infer_agent_source_from_context(
@@ -767,11 +852,13 @@ class MultiSourceAgentDeploymentService:
                 ):
                     # In development mode, unknown agents are likely system agents being tested
                     return "system"
-                if deployment_context == DeploymentContext.PIPX_INSTALL:
-                    # In pipx mode, unknown agents could be system agents
-                    # Check if agent follows system naming patterns
-                    if agent_name.count("-") <= 2 and len(agent_name) <= 20:
-                        return "system"
+                if (
+                    deployment_context == DeploymentContext.PIPX_INSTALL
+                    and agent_name.count("-") <= 2
+                    and len(agent_name) <= 20
+                ):
+                    # In pipx mode, check if agent follows system naming patterns
+                    return "system"
             except Exception:
                 pass
 
@@ -860,7 +947,7 @@ class MultiSourceAgentDeploymentService:
 
     def _detect_orphaned_agents_simple(
         self, deployed_agents_dir: Path, agents_to_deploy: Dict[str, Path]
-    ) -> List[Dict[str, Any]]:
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
         """Simple orphan detection that works with agents_to_deploy structure.
 
         Args:
@@ -868,12 +955,13 @@ class MultiSourceAgentDeploymentService:
             agents_to_deploy: Dictionary mapping file stems to template paths
 
         Returns:
-            List of orphaned agent information
+            Tuple of (system_orphaned_agents, user_orphaned_agents)
         """
-        orphaned = []
+        system_orphaned = []
+        user_orphaned = []
 
         if not deployed_agents_dir.exists():
-            return orphaned
+            return system_orphaned, user_orphaned
 
         # agents_to_deploy already contains file stems as keys
         available_stems = set(agents_to_deploy.keys())
@@ -885,7 +973,7 @@ class MultiSourceAgentDeploymentService:
             if agent_stem in available_stems:
                 continue
 
-            # This is an orphaned agent
+            # This is an orphaned agent - determine if it's user-created or system
             try:
                 deployed_content = deployed_file.read_text()
                 deployed_version, _, _ = (
@@ -899,11 +987,19 @@ class MultiSourceAgentDeploymentService:
             except Exception:
                 version_str = "unknown"
 
-            orphaned.append(
-                {"name": agent_stem, "file": str(deployed_file), "version": version_str}
-            )
+            orphan_info = {
+                "name": agent_stem,
+                "file": str(deployed_file),
+                "version": version_str,
+            }
 
-        return orphaned
+            # Determine if this is a user-created agent
+            if self._is_user_created_agent(deployed_file):
+                user_orphaned.append(orphan_info)
+            else:
+                system_orphaned.append(orphan_info)
+
+        return system_orphaned, user_orphaned
 
     def cleanup_orphaned_agents(
         self, deployed_agents_dir: Path, dry_run: bool = True