claude-mpm 4.0.19__py3-none-any.whl → 4.0.22__py3-none-any.whl

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -32,7 +32,7 @@ import os
 import shutil
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from claude_mpm.config.paths import paths
 from claude_mpm.constants import AgentMetadata, EnvironmentVars, Paths
@@ -55,6 +55,7 @@ from .agent_metrics_collector import AgentMetricsCollector
 from .agent_template_builder import AgentTemplateBuilder
 from .agent_validator import AgentValidator
 from .agent_version_manager import AgentVersionManager
+from .multi_source_deployment_service import MultiSourceAgentDeploymentService
 
 
 class AgentDeploymentService(AgentDeploymentInterface):
@@ -161,13 +162,16 @@ class AgentDeploymentService(AgentDeploymentInterface):
 
         # Initialize discovery service (after templates_dir is set)
         self.discovery_service = AgentDiscoveryService(self.templates_dir)
+        
+        # Initialize multi-source deployment service for version comparison
+        self.multi_source_service = MultiSourceAgentDeploymentService()
 
-        # Find base agent file
+        # Find base agent file with priority-based search
         if base_agent_path:
             self.base_agent_path = Path(base_agent_path)
         else:
-            # Use centralized paths for consistency
-            self.base_agent_path = paths.agents_dir / "base_agent.json"
+            # Priority-based search for base_agent.json
+            self.base_agent_path = self._find_base_agent_file()
 
         # Initialize configuration manager (after base_agent_path is set)
         self.configuration_manager = AgentConfigurationManager(self.base_agent_path)
@@ -177,6 +181,68 @@ class AgentDeploymentService(AgentDeploymentInterface):
 
         self.logger.info(f"Templates directory: {self.templates_dir}")
         self.logger.info(f"Base agent path: {self.base_agent_path}")
+    
+    def _find_base_agent_file(self) -> Path:
+        """Find base agent file with priority-based search.
+        
+        Priority order:
+        1. Environment variable override (CLAUDE_MPM_BASE_AGENT_PATH)
+        2. Current working directory (for local development)
+        3. Known development locations  
+        4. User override location (~/.claude/agents/)
+        5. Framework agents directory (from paths)
+        """
+        # Priority 0: Check environment variable override
+        env_path = os.environ.get("CLAUDE_MPM_BASE_AGENT_PATH")
+        if env_path:
+            env_base_agent = Path(env_path)
+            if env_base_agent.exists():
+                self.logger.info(f"Using environment variable base_agent: {env_base_agent}")
+                return env_base_agent
+            else:
+                self.logger.warning(f"CLAUDE_MPM_BASE_AGENT_PATH set but file doesn't exist: {env_base_agent}")
+        
+        # Priority 1: Check current working directory for local development
+        cwd = Path.cwd()
+        cwd_base_agent = cwd / "src" / "claude_mpm" / "agents" / "base_agent.json"
+        if cwd_base_agent.exists():
+            self.logger.info(f"Using local development base_agent from cwd: {cwd_base_agent}")
+            return cwd_base_agent
+        
+        # Priority 2: Check known development locations
+        known_dev_paths = [
+            Path("/Users/masa/Projects/claude-mpm/src/claude_mpm/agents/base_agent.json"),
+            Path.home() / "Projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
+            Path.home() / "projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
+        ]
+        
+        for dev_path in known_dev_paths:
+            if dev_path.exists():
+                self.logger.info(f"Using development base_agent: {dev_path}")
+                return dev_path
+        
+        # Priority 3: Check user override location
+        user_base_agent = Path.home() / ".claude" / "agents" / "base_agent.json"
+        if user_base_agent.exists():
+            self.logger.info(f"Using user override base_agent: {user_base_agent}")
+            return user_base_agent
+        
+        # Priority 4: Use framework agents directory (fallback)
+        framework_base_agent = paths.agents_dir / "base_agent.json"
+        if framework_base_agent.exists():
+            self.logger.info(f"Using framework base_agent: {framework_base_agent}")
+            return framework_base_agent
+        
+        # If still not found, log all searched locations and raise error
+        self.logger.error("Base agent file not found in any location:")
+        self.logger.error(f"  1. CWD: {cwd_base_agent}")
+        self.logger.error(f"  2. Dev paths: {known_dev_paths}")
+        self.logger.error(f"  3. User: {user_base_agent}")
+        self.logger.error(f"  4. Framework: {framework_base_agent}")
+        
+        # Final fallback to framework path even if it doesn't exist
+        # (will fail later with better error message)
+        return framework_base_agent
 
     def deploy_agents(
         self,
@@ -310,20 +376,40 @@ class AgentDeploymentService(AgentDeploymentInterface):
             # Load base agent content
             base_agent_data, base_agent_version = self._load_base_agent()
 
-            # Get and filter template files
-            template_files = self._get_filtered_templates(excluded_agents, config)
-            results["total"] = len(template_files)
+            # Check if we should use multi-source deployment
+            use_multi_source = self._should_use_multi_source_deployment(deployment_mode)
+            
+            if use_multi_source:
+                # Use multi-source deployment to get highest version agents
+                template_files, agent_sources = self._get_multi_source_templates(
+                    excluded_agents, config, agents_dir
+                )
+                results["total"] = len(template_files)
+                results["multi_source"] = True
+                results["agent_sources"] = agent_sources
+            else:
+                # Get and filter template files from single source
+                template_files = self._get_filtered_templates(excluded_agents, config)
+                results["total"] = len(template_files)
+                agent_sources = {}
 
             # Deploy each agent template
             for template_file in template_files:
+                template_file_path = template_file if isinstance(template_file, Path) else Path(template_file)
+                agent_name = template_file_path.stem
+                
+                # Get source info for this agent (agent_sources now uses file stems as keys)
+                source_info = agent_sources.get(agent_name, "unknown") if agent_sources else "single"
+                
                 self._deploy_single_agent(
-                    template_file=template_file,
+                    template_file=template_file_path,
                     agents_dir=agents_dir,
                     base_agent_data=base_agent_data,
                     base_agent_version=base_agent_version,
                     force_rebuild=force_rebuild,
                     deployment_mode=deployment_mode,
                     results=results,
+                    source_info=source_info,
                 )
 
             # Deploy system instructions and framework files
@@ -467,8 +553,10 @@ class AgentDeploymentService(AgentDeploymentInterface):
                     self.logger.warning(f"Could not load base agent: {e}")
 
             # Build the agent markdown
+            # For single agent deployment, determine source from template location
+            source_info = self._determine_agent_source(template_file)
             agent_content = self.template_builder.build_agent_markdown(
-                agent_name, template_file, base_agent_data
+                agent_name, template_file, base_agent_data, source_info
             )
             if not agent_content:
                 self.logger.error(f"Failed to build agent content for {agent_name}")
@@ -718,6 +806,7 @@ class AgentDeploymentService(AgentDeploymentInterface):
         force_rebuild: bool,
         deployment_mode: str,
         results: Dict[str, Any],
+        source_info: str = "unknown",
     ) -> None:
         """
         Deploy a single agent template.
@@ -733,6 +822,7 @@ class AgentDeploymentService(AgentDeploymentInterface):
             force_rebuild: Whether to force rebuild
             deployment_mode: Deployment mode (update/project)
             results: Results dictionary to update
+            source_info: Source of the agent (system/project/user)
         """
         try:
             # METRICS: Track individual agent deployment time
@@ -762,7 +852,7 @@ class AgentDeploymentService(AgentDeploymentInterface):
 
             # Build the agent file as markdown with YAML frontmatter
             agent_content = self.template_builder.build_agent_markdown(
-                agent_name, template_file, base_agent_data
+                agent_name, template_file, base_agent_data, source_info
             )
 
             # Write the agent file
@@ -912,6 +1002,122 @@ class AgentDeploymentService(AgentDeploymentInterface):
 
         validator = AgentFrontmatterValidator(self.logger)
         return validator.validate_and_repair_existing_agents(agents_dir)
+    
+    def _determine_agent_source(self, template_path: Path) -> str:
+        """Determine the source of an agent from its template path.
+        
+        WHY: When deploying single agents, we need to track their source
+        for proper version management and debugging.
+        
+        Args:
+            template_path: Path to the agent template
+            
+        Returns:
+            Source string (system/project/user/unknown)
+        """
+        template_str = str(template_path.resolve())
+        
+        # Check if it's a system template
+        if "/claude_mpm/agents/templates/" in template_str or "/src/claude_mpm/agents/templates/" in template_str:
+            return "system"
+        
+        # Check if it's a project agent
+        if "/.claude-mpm/agents/" in template_str:
+            # Check if it's in the current working directory
+            if str(self.working_directory) in template_str:
+                return "project"
+            # Check if it's in user home
+            elif str(Path.home()) in template_str:
+                return "user"
+        
+        return "unknown"
+    
+    def _should_use_multi_source_deployment(self, deployment_mode: str) -> bool:
+        """Determine if multi-source deployment should be used.
+        
+        WHY: Multi-source deployment ensures the highest version wins,
+        but we may want to preserve backward compatibility in some modes.
+        
+        Args:
+            deployment_mode: Current deployment mode
+            
+        Returns:
+            True if multi-source deployment should be used
+        """
+        # Always use multi-source for update mode to get highest versions
+        if deployment_mode == "update":
+            return True
+            
+        # For project mode, also use multi-source to ensure highest version wins
+        # This is the key change - project mode should also compare versions
+        if deployment_mode == "project":
+            return True
+            
+        return False
+    
+    def _get_multi_source_templates(
+        self, excluded_agents: List[str], config: Config, agents_dir: Path
+    ) -> Tuple[List[Path], Dict[str, str]]:
+        """Get agent templates from multiple sources with version comparison.
+        
+        WHY: This method uses the multi-source service to discover agents
+        from all available sources and select the highest version of each.
+        
+        Args:
+            excluded_agents: List of agents to exclude
+            config: Configuration object
+            agents_dir: Target deployment directory
+            
+        Returns:
+            Tuple of (template_files, agent_sources)
+        """
+        # Determine source directories
+        system_templates_dir = self.templates_dir
+        project_agents_dir = None
+        user_agents_dir = None
+        
+        # Check for project agents
+        if self.working_directory:
+            potential_project_dir = self.working_directory / ".claude-mpm" / "agents"
+            if potential_project_dir.exists():
+                project_agents_dir = potential_project_dir
+                self.logger.info(f"Found project agents at: {project_agents_dir}")
+        
+        # Check for user agents
+        user_home = Path.home()
+        potential_user_dir = user_home / ".claude-mpm" / "agents"
+        if potential_user_dir.exists():
+            user_agents_dir = potential_user_dir
+            self.logger.info(f"Found user agents at: {user_agents_dir}")
+        
+        # Get agents with version comparison
+        agents_to_deploy, agent_sources = self.multi_source_service.get_agents_for_deployment(
+            system_templates_dir=system_templates_dir,
+            project_agents_dir=project_agents_dir,
+            user_agents_dir=user_agents_dir,
+            working_directory=self.working_directory,
+            excluded_agents=excluded_agents,
+            config=config
+        )
+        
+        # Compare with deployed versions if agents directory exists
+        if agents_dir.exists():
+            comparison_results = self.multi_source_service.compare_deployed_versions(
+                deployed_agents_dir=agents_dir,
+                agents_to_deploy=agents_to_deploy,
+                agent_sources=agent_sources
+            )
+            
+            # Log version upgrades and source changes
+            if comparison_results.get("version_upgrades"):
+                self.logger.info(f"Version upgrades available for {len(comparison_results['version_upgrades'])} agents")
+            if comparison_results.get("source_changes"):
+                self.logger.info(f"Source changes for {len(comparison_results['source_changes'])} agents")
+        
+        # Convert to list of Path objects
+        template_files = list(agents_to_deploy.values())
+        
+        return template_files, agent_sources
 
     # ================================================================================
     # Interface Adapter Methods

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -31,7 +31,7 @@ class AgentTemplateBuilder:
         self.logger = get_logger(__name__)
 
     def build_agent_markdown(
-        self, agent_name: str, template_path: Path, base_agent_data: dict
+        self, agent_name: str, template_path: Path, base_agent_data: dict, source_info: str = "unknown"
     ) -> str:
         """
         Build a complete agent markdown file with YAML frontmatter.
@@ -40,6 +40,7 @@ class AgentTemplateBuilder:
             agent_name: Name of the agent
             template_path: Path to the agent template JSON file
             base_agent_data: Base agent configuration data
+            source_info: Source of the agent (system/project/user)
 
         Returns:
             Complete markdown content with YAML frontmatter
@@ -197,6 +198,8 @@ class AgentTemplateBuilder:
                 f"color: {color}",
                 f"version: {agent_version}",
                 f"type: {agent_type}",
+                f"source: {source_info}",  # Track which source provided this agent
+                "author: claude-mpm",  # Mark as system-managed agent
                 "---",
                 "",
             ]
@@ -211,6 +214,39 @@ class AgentTemplateBuilder:
             or base_agent_data.get("instructions")
             or "# Agent Instructions\n\nThis agent provides specialized assistance."
         )
+        
+        # Add memory update instructions if not already present
+        if "memory-update" not in content and "Remember" not in content:
+            memory_instructions = """
+
+## Memory Updates
+
+When you learn something important about this project that would be useful for future tasks, include it in your response JSON block:
+
+```json
+{
+  "memory-update": {
+    "Project Architecture": ["Key architectural patterns or structures"],
+    "Implementation Guidelines": ["Important coding standards or practices"],
+    "Current Technical Context": ["Project-specific technical details"]
+  }
+}
+```
+
+Or use the simpler "remember" field for general learnings:
+
+```json
+{
+  "remember": ["Learning 1", "Learning 2"]
+}
+```
+
+Only include memories that are:
+- Project-specific (not generic programming knowledge)
+- Likely to be useful in future tasks
+- Not already documented elsewhere
+"""
+            content = content + memory_instructions
 
         return frontmatter + content
 

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -83,7 +83,8 @@ class AsyncAgentDeploymentService:
         if base_agent_path:
             self.base_agent_path = Path(base_agent_path)
         else:
-            self.base_agent_path = paths.agents_dir / "base_agent.json"
+            # Use priority-based search for base_agent.json
+            self.base_agent_path = self._find_base_agent_file()
 
         # Thread pool for CPU-bound JSON parsing
         self.executor = ThreadPoolExecutor(max_workers=4)
@@ -94,6 +95,69 @@ class AsyncAgentDeploymentService:
             "parallel_files_processed": 0,
             "time_saved_ms": 0.0,
         }
+        
+        self.logger.info(f"Base agent path: {self.base_agent_path}")
+    
+    def _find_base_agent_file(self) -> Path:
+        """Find base agent file with priority-based search.
+        
+        Priority order:
+        1. Environment variable override (CLAUDE_MPM_BASE_AGENT_PATH)
+        2. Current working directory (for local development)
+        3. Known development locations
+        4. User override location (~/.claude/agents/)
+        5. Framework agents directory (from paths)
+        """
+        # Priority 0: Check environment variable override
+        env_path = os.environ.get("CLAUDE_MPM_BASE_AGENT_PATH")
+        if env_path:
+            env_base_agent = Path(env_path)
+            if env_base_agent.exists():
+                self.logger.info(f"Using environment variable base_agent: {env_base_agent}")
+                return env_base_agent
+            else:
+                self.logger.warning(f"CLAUDE_MPM_BASE_AGENT_PATH set but file doesn't exist: {env_base_agent}")
+        
+        # Priority 1: Check current working directory for local development
+        cwd = Path.cwd()
+        cwd_base_agent = cwd / "src" / "claude_mpm" / "agents" / "base_agent.json"
+        if cwd_base_agent.exists():
+            self.logger.info(f"Using local development base_agent from cwd: {cwd_base_agent}")
+            return cwd_base_agent
+        
+        # Priority 2: Check known development locations
+        known_dev_paths = [
+            Path("/Users/masa/Projects/claude-mpm/src/claude_mpm/agents/base_agent.json"),
+            Path.home() / "Projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
+            Path.home() / "projects" / "claude-mpm" / "src" / "claude_mpm" / "agents" / "base_agent.json",
+        ]
+        
+        for dev_path in known_dev_paths:
+            if dev_path.exists():
+                self.logger.info(f"Using development base_agent: {dev_path}")
+                return dev_path
+        
+        # Priority 3: Check user override location
+        user_base_agent = Path.home() / ".claude" / "agents" / "base_agent.json"
+        if user_base_agent.exists():
+            self.logger.info(f"Using user override base_agent: {user_base_agent}")
+            return user_base_agent
+        
+        # Priority 4: Use framework agents directory (fallback)
+        framework_base_agent = paths.agents_dir / "base_agent.json"
+        if framework_base_agent.exists():
+            self.logger.info(f"Using framework base_agent: {framework_base_agent}")
+            return framework_base_agent
+        
+        # If still not found, log all searched locations
+        self.logger.warning("Base agent file not found in any location:")
+        self.logger.warning(f"  1. CWD: {cwd_base_agent}")
+        self.logger.warning(f"  2. Dev paths: {known_dev_paths}")
+        self.logger.warning(f"  3. User: {user_base_agent}")
+        self.logger.warning(f"  4. Framework: {framework_base_agent}")
+        
+        # Final fallback to framework path even if it doesn't exist
+        return framework_base_agent
 
     async def discover_agents_async(
         self, directories: List[Path]