claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/services/agents/deployment/startup_reconciliation.py

@@ -0,0 +1,138 @@
+"""
+Startup Reconciliation Hook
+
+This module provides a hook for performing agent/skill reconciliation
+during application startup, ensuring deployed state matches configuration.
+
+Usage:
+    from claude_mpm.services.agents.deployment.startup_reconciliation import (
+        perform_startup_reconciliation
+    )
+
+    # In your startup code
+    perform_startup_reconciliation()
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+from claude_mpm.core.unified_config import UnifiedConfig
+
+from .deployment_reconciler import DeploymentReconciler, DeploymentResult
+
+logger = get_logger(__name__)
+
+
+def perform_startup_reconciliation(
+    project_path: Optional[Path] = None,
+    config: Optional[UnifiedConfig] = None,
+    silent: bool = False,
+) -> tuple[DeploymentResult, DeploymentResult]:
+    """
+    Perform agent and skill reconciliation during startup.
+
+    This ensures the deployed state (.claude/agents, .claude/skills) matches
+    the configuration (agents.enabled, skills.enabled lists).
+
+    Args:
+        project_path: Project directory (default: current directory)
+        config: Configuration instance (auto-loads if None)
+        silent: Suppress info logging (only errors)
+
+    Returns:
+        Tuple of (agent_result, skill_result)
+    """
+    project_path = project_path or Path.cwd()
+
+    # Load config if not provided
+    if config is None:
+        config = UnifiedConfig()
+
+    # Initialize reconciler
+    reconciler = DeploymentReconciler(config)
+
+    if not silent:
+        logger.info("Performing startup reconciliation...")
+
+    # Reconcile agents
+    agent_result = reconciler.reconcile_agents(project_path)
+
+    if agent_result.deployed and not silent:
+        logger.info(f"Deployed agents: {', '.join(agent_result.deployed)}")
+    if agent_result.removed and not silent:
+        logger.info(f"Removed agents: {', '.join(agent_result.removed)}")
+    if agent_result.errors:
+        for error in agent_result.errors:
+            logger.error(f"Agent reconciliation error: {error}")
+
+    # Reconcile skills
+    skill_result = reconciler.reconcile_skills(project_path)
+
+    if skill_result.deployed and not silent:
+        logger.info(f"Deployed skills: {', '.join(skill_result.deployed)}")
+    if skill_result.removed and not silent:
+        logger.info(f"Removed skills: {', '.join(skill_result.removed)}")
+    if skill_result.errors:
+        for error in skill_result.errors:
+            logger.error(f"Skill reconciliation error: {error}")
+
+    if not silent:
+        total_errors = len(agent_result.errors) + len(skill_result.errors)
+        if total_errors == 0:
+            logger.info("Startup reconciliation complete")
+        else:
+            logger.warning(
+                f"Startup reconciliation complete with {total_errors} errors"
+            )
+
+    return agent_result, skill_result
+
+
+def check_reconciliation_needed(
+    project_path: Optional[Path] = None, config: Optional[UnifiedConfig] = None
+) -> bool:
+    """
+    Check if reconciliation is needed (without performing it).
+
+    Args:
+        project_path: Project directory
+        config: Configuration instance
+
+    Returns:
+        True if reconciliation would make changes
+    """
+    project_path = project_path or Path.cwd()
+
+    if config is None:
+        config = UnifiedConfig()
+
+    reconciler = DeploymentReconciler(config)
+    view = reconciler.get_reconciliation_view(project_path)
+
+    agent_state = view["agents"]
+    skill_state = view["skills"]
+
+    # Check if any changes needed
+    return (
+        len(agent_state.to_deploy) > 0
+        or len(agent_state.to_remove) > 0
+        or len(skill_state.to_deploy) > 0
+        or len(skill_state.to_remove) > 0
+    )
+
+
+# Example integration in startup code:
+#
+# from claude_mpm.services.agents.deployment.startup_reconciliation import (
+#     perform_startup_reconciliation,
+#     check_reconciliation_needed
+# )
+#
+# def startup():
+#     # Check if reconciliation needed
+#     if check_reconciliation_needed():
+#         logger.info("Reconciliation needed, performing...")
+#         perform_startup_reconciliation()
+#     else:
+#         logger.debug("No reconciliation needed")

claude_mpm/services/agents/git_source_manager.py

@@ -50,10 +50,10 @@ class GitSourceManager:
 
         Args:
             cache_root: Root directory for repository caches.
-                       Defaults to ~/.claude-mpm/cache/remote-agents/
+                       Defaults to ~/.claude-mpm/cache/agents/
         """
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.cache_root.mkdir(parents=True, exist_ok=True)
@@ -395,8 +395,27 @@ class GitSourceManager:
                     )
                     logger.debug(f"[DEBUG] Found {len(agents)} agents so far")
 
-        logger.debug(f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents")
-        return agents
+        logger.debug(
+            f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents (before deduplication)"
+        )
+
+        # Deduplicate agents by agent_id (Bug #2 fix)
+        # When same agent exists in multiple locations, keep only first occurrence
+        seen_ids = set()
+        deduplicated_agents = []
+
+        for agent in agents:
+            agent_id = agent.get("agent_id") or agent.get("metadata", {}).get("name")
+            if agent_id and agent_id not in seen_ids:
+                seen_ids.add(agent_id)
+                deduplicated_agents.append(agent)
+            elif agent_id:
+                logger.debug(f"[DEBUG] Skipping duplicate agent: {agent_id}")
+
+        logger.debug(
+            f"[DEBUG] After deduplication: {len(deduplicated_agents)} unique agents"
+        )
+        return deduplicated_agents
 
     def _discover_agents_in_directory(
         self,

claude_mpm/services/agents/loading/framework_agent_loader.py

@@ -10,10 +10,19 @@ Loading precedence: Project → User → System
 
 This service integrates with the main agent_loader.py to provide
 markdown-based agent profiles alongside JSON-based templates.
+
+Auto-Deployment: When no agents are configured, the standard 6 core agents
+are automatically deployed:
+- engineer: General-purpose implementation
+- research: Codebase exploration and analysis
+- qa: Testing and quality assurance
+- documentation: Documentation generation
+- ops: Basic deployment operations
+- ticketing: Ticket tracking (essential for PM workflow)
 """
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from claude_mpm.agents.agent_loader import AgentTier, list_agents_by_tier
 from claude_mpm.core.logging_utils import get_logger
@@ -21,6 +30,17 @@ from claude_mpm.core.unified_paths import get_path_manager
 
 logger = get_logger(__name__)
 
+# Standard 6 core agents that are auto-deployed when no agents are specified
+# This list is the canonical source - other modules should import from here
+CORE_AGENTS: List[str] = [
+    "engineer",  # General-purpose implementation
+    "research",  # Codebase exploration and analysis
+    "qa",  # Testing and quality assurance
+    "documentation",  # Documentation generation
+    "ops",  # Basic deployment operations
+    "ticketing",  # Ticket tracking (essential for PM workflow)
+]
+
 
 class FrameworkAgentLoader:
     """Loads agent profiles from project, user, and system directories with proper precedence"""
@@ -86,7 +106,7 @@ class FrameworkAgentLoader:
                 data_claude = package_path / "data" / "agents" / "CLAUDE.md"
                 if data_instructions.exists() or data_claude.exists():
                     return package_path / "data"
-        except Exception:
+        except Exception:  # nosec B110 - intentional fallthrough to next location
             pass
 
         current = Path.cwd()
@@ -431,3 +451,56 @@ Please operate according to your profile specifications and maintain quality sta
 """
 
         return instruction.strip()
+
+    def get_core_agents(self) -> List[str]:
+        """
+        Get the standard 6 core agents for auto-deployment.
+
+        These agents are automatically deployed when no agents are specified
+        in the configuration. They provide essential PM workflow functionality.
+
+        Returns:
+            List of core agent IDs
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> core = loader.get_core_agents()
+            >>> 'engineer' in core
+            True
+            >>> len(core)
+            6
+        """
+        return CORE_AGENTS.copy()
+
+    def get_agents_with_fallback(self) -> Dict[str, list]:
+        """
+        Get available agents, falling back to core agents if none found.
+
+        This method implements the auto-deployment logic: when no agents
+        are found in any tier (project, user, system), it returns the
+        standard 6 core agents as a fallback.
+
+        Returns:
+            Dictionary with agent lists by tier. If no agents found in any tier,
+            returns core agents under 'fallback' key.
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> loader.initialize()
+            >>> agents = loader.get_agents_with_fallback()
+            >>> if 'fallback' in agents:
+            ...     print("Using core agents as fallback")
+        """
+        available = self.get_available_agents()
+
+        # Check if any agents are found
+        total_agents = sum(len(agents) for agents in available.values())
+
+        if total_agents == 0:
+            logger.info(
+                "No agents found in configuration. "
+                "Auto-deploying standard 6 core agents."
+            )
+            return {"fallback": CORE_AGENTS.copy()}
+
+        return available

claude_mpm/services/agents/recommender.py

@@ -226,9 +226,11 @@ class AgentRecommenderService(BaseService, IAgentRecommender):
         if max_agents is not None:
             recommendations = recommendations[:max_agents]
 
-        # Check if toolchain is unknown and we have no recommendations
-        if not recommendations and toolchain.primary_language.lower() == "unknown":
-            self.logger.info("Toolchain unknown - applying default configuration")
+        # Check if we have no recommendations (any reason: unknown language, low scores, etc.)
+        if not recommendations:
+            self.logger.info(
+                f"No agents scored above threshold for {toolchain.primary_language}; using defaults"
+            )
 
             # Get default configuration
             default_config = self._capabilities_config.get("default_configuration", {})

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -30,12 +30,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from src.claude_mpm.config.agent_sources import AgentSourceConfiguration
-from src.claude_mpm.models.git_repository import GitRepository
-from src.claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
+from claude_mpm.config.agent_sources import AgentSourceConfiguration
+from claude_mpm.models.git_repository import GitRepository
+from claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
     RemoteAgentDiscoveryService,
 )
-from src.claude_mpm.services.agents.git_source_manager import GitSourceManager
+from claude_mpm.services.agents.git_source_manager import GitSourceManager
 
 logger = logging.getLogger(__name__)
 
@@ -78,14 +78,14 @@ class SingleTierDeploymentService:
             config: Agent source configuration with repositories
             deployment_dir: Target deployment directory (.claude/agents/)
             cache_root: Cache root for repositories
-                       (defaults to ~/.claude-mpm/cache/remote-agents/)
+                       (defaults to ~/.claude-mpm/cache/agents/)
         """
         self.config = config
         self.deployment_dir = deployment_dir
         self.deployment_dir.mkdir(parents=True, exist_ok=True)
 
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.git_source_manager = GitSourceManager(cache_root)

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -13,11 +13,16 @@ import logging
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 import requests
 
 from claude_mpm.core.file_utils import get_file_hash
+
+# Import normalize function for exclusion filtering
+from claude_mpm.services.agents.deployment.multi_source_deployment_service import (
+    _normalize_agent_name,
+)
 from claude_mpm.services.agents.sources.agent_sync_state import AgentSyncState
 from claude_mpm.utils.progress import create_progress_bar
 
@@ -188,10 +193,10 @@ class GitSourceSyncService:
 
         Args:
             source_url: Base URL for raw files (without trailing slash)
-            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/remote-agents/)
+            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/agents/)
             source_id: Unique identifier for this source (for multi-source support)
 
-        Design Decision: Cache to ~/.claude-mpm/cache/remote-agents/ (canonical location)
+        Design Decision: Cache to ~/.claude-mpm/cache/agents/ (canonical location)
 
         Rationale: Separates cached repository structure from deployed agents.
         This allows preserving nested directory structure in cache while
@@ -207,13 +212,13 @@ class GitSourceSyncService:
         self.source_url = source_url.rstrip("/")
         self.source_id = source_id
 
-        # Setup cache directory (canonical: ~/.claude-mpm/cache/remote-agents/)
+        # Setup cache directory (canonical: ~/.claude-mpm/cache/agents/)
         if cache_dir:
             self.cache_dir = Path(cache_dir)
         else:
-            # Default to ~/.claude-mpm/cache/remote-agents/ (canonical cache location)
+            # Default to ~/.claude-mpm/cache/agents/ (canonical cache location)
             home = Path.home()
-            self.cache_dir = home / ".claude-mpm" / "cache" / "remote-agents"
+            self.cache_dir = home / ".claude-mpm" / "cache" / "agents"
 
         self.cache_dir.mkdir(parents=True, exist_ok=True)
 
@@ -923,6 +928,62 @@ class GitSourceSyncService:
         """
         return self.cache_dir
 
+    def _cleanup_excluded_agents(
+        self,
+        deployment_dir: Path,
+        excluded_set: Set[str],
+    ) -> Dict[str, List[str]]:
+        """Remove excluded agents from deployment directory.
+
+        Removes any agents in the deployment directory whose normalized
+        names match the exclusion list. This ensures that excluded agents
+        are cleaned up from previous deployments.
+
+        Args:
+            deployment_dir: Directory containing deployed agents
+            excluded_set: Set of normalized agent names to exclude
+
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of agent names that were removed
+        """
+        cleanup_results: Dict[str, List[str]] = {"removed": []}
+
+        if not deployment_dir.exists():
+            logger.debug("Deployment directory does not exist, no cleanup needed")
+            return cleanup_results
+
+        for item in deployment_dir.iterdir():
+            # Only process .md files
+            if not item.is_file() or item.suffix != ".md":
+                continue
+
+            # Skip hidden files
+            if item.name.startswith("."):
+                continue
+
+            # Normalize agent name for comparison
+            agent_name = _normalize_agent_name(item.stem)
+
+            # Check if this agent is excluded
+            if agent_name in excluded_set:
+                try:
+                    item.unlink()
+                    cleanup_results["removed"].append(item.stem)
+                    logger.info(f"Removed excluded agent: {item.stem}")
+                except PermissionError as e:
+                    logger.error(f"Permission denied removing {item.stem}: {e}")
+                except Exception as e:
+                    logger.error(f"Failed to remove {item.stem}: {e}")
+
+        # Log summary
+        if cleanup_results["removed"]:
+            logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} excluded agents"
+            )
+
+        return cleanup_results
+
     def deploy_agents_to_project(
         self,
         project_dir: Path,
@@ -977,6 +1038,8 @@ class GitSourceSyncService:
         """
         import shutil
 
+        from claude_mpm.core.config import Config
+
         # Deploy to .claude/agents/ where Claude Code expects them
         deployment_dir = project_dir / ".claude" / "agents"
         deployment_dir.mkdir(parents=True, exist_ok=True)
@@ -989,10 +1052,55 @@ class GitSourceSyncService:
             "deployment_dir": str(deployment_dir),
         }
 
+        # Load project config to get exclusion list
+        config_file = project_dir / ".claude-mpm" / "configuration.yaml"
+        if config_file.exists():
+            config = Config(config_file=config_file)
+            excluded_agents = config.get("excluded_agents", [])
+        else:
+            # No project config, no exclusions
+            excluded_agents = []
+
+        # Create normalized exclusion set
+        excluded_set: Set[str] = (
+            {_normalize_agent_name(name) for name in excluded_agents}
+            if excluded_agents
+            else set()
+        )
+
+        if excluded_set:
+            logger.info(
+                f"Applying exclusions: {', '.join(sorted(excluded_agents))} "
+                f"(normalized: {', '.join(sorted(excluded_set))})"
+            )
+
         # Get agents from cache or use provided list
         if agent_list is None:
             agent_list = self._discover_cached_agents()
 
+        # Filter out excluded agents
+        if excluded_set:
+            original_count = len(agent_list)
+            agent_list = [
+                agent_path
+                for agent_path in agent_list
+                if _normalize_agent_name(Path(agent_path).stem) not in excluded_set
+            ]
+            filtered_count = original_count - len(agent_list)
+            if filtered_count > 0:
+                logger.info(f"Filtered out {filtered_count} excluded agents")
+
+        # Clean up any previously deployed excluded agents
+        if excluded_set:
+            cleanup_results = self._cleanup_excluded_agents(
+                deployment_dir, excluded_set
+            )
+            if cleanup_results["removed"]:
+                logger.info(
+                    f"Cleaned up {len(cleanup_results['removed'])} excluded agents: "
+                    f"{', '.join(cleanup_results['removed'])}"
+                )
+
         logger.info(
             f"Deploying {len(agent_list)} agents from cache to {deployment_dir}"
         )
@@ -1010,14 +1118,17 @@ class GitSourceSyncService:
                 deploy_filename = Path(agent_path).name
                 deploy_file = deployment_dir / deploy_filename
 
-                # Check if update needed (compare modification times)
+                # Check if update needed (compare content, not just mtime)
+                # DESIGN: Use content hash comparison for reliable change detection
+                # Mtime comparison can fail when cache downloads have older timestamps
                 should_deploy = force
                 was_existing = deploy_file.exists()
 
                 if not force and was_existing:
-                    cache_mtime = cache_file.stat().st_mtime
-                    deploy_mtime = deploy_file.stat().st_mtime
-                    should_deploy = cache_mtime > deploy_mtime
+                    # Compare file contents using hash
+                    cache_content = cache_file.read_bytes()
+                    deploy_content = deploy_file.read_bytes()
+                    should_deploy = cache_content != deploy_content
 
                 if not should_deploy and was_existing:
                     results["skipped"].append(deploy_filename)

claude_mpm/services/agents/startup_sync.py

@@ -32,7 +32,9 @@ from claude_mpm.services.agents.sources.git_source_sync_service import (
 logger = logging.getLogger(__name__)
 
 
-def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+def sync_agents_on_startup(
+    config: Optional[Dict[str, Any]] = None, force_refresh: bool = False
+) -> Dict[str, Any]:
     """Synchronize agents from remote sources on Claude MPM startup.
 
     Design Decision: Single-source support for Stage 1
@@ -44,6 +46,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
 
     Args:
         config: Optional configuration dictionary. If None, loads from Config singleton.
+        force_refresh: Force download even if cache is fresh (bypasses ETag).
 
     Returns:
         Dictionary with sync results:
@@ -110,6 +113,26 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
         else:
             cache_dir = None  # Will use default
 
+        # Check for old cache directory names and provide migration guidance
+        # This handles users upgrading from older versions
+        old_cache_paths = [
+            Path.home() / ".claude-mpm" / "cache" / "remote-agents",
+        ]
+        new_cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
+
+        for old_cache in old_cache_paths:
+            if old_cache.exists() and not new_cache_dir.exists():
+                logger.warning(f"Found old cache directory: {old_cache}")
+                logger.warning(
+                    "The cache directory location has changed to: ~/.claude-mpm/cache/agents"
+                )
+                logger.warning("To migrate your existing cache, run:")
+                logger.warning(f"  mv {old_cache} {new_cache_dir}")
+                logger.info(
+                    "Agents will be re-synced to the new cache location automatically."
+                )
+                break  # Only show warning once
+
         # Sync each enabled source
         for source_config in sources:
             try:
@@ -136,7 +159,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
                 )
 
                 # Perform sync
-                sync_result = sync_service.sync_agents(force_refresh=False)
+                sync_result = sync_service.sync_agents(force_refresh=force_refresh)
 
                 # Aggregate results
                 result["sources_synced"] += 1
@@ -217,7 +240,7 @@ def get_sync_status() -> Dict[str, Any]:
             "enabled": agent_sync_config.get("enabled", True),
             "sources_configured": len(enabled_sources),
             "cache_dir": agent_sync_config.get(
-                "cache_dir", "~/.claude-mpm/cache/remote-agents"
+                "cache_dir", "~/.claude-mpm/cache/agents"
             ),
         }
 
@@ -233,7 +256,7 @@ def get_sync_status() -> Dict[str, Any]:
         return {
             "enabled": False,
             "sources_configured": 0,
-            "cache_dir": "~/.claude-mpm/cache/remote-agents",
+            "cache_dir": "~/.claude-mpm/cache/agents",
             "last_sync": None,
             "error": str(e),
         }

claude_mpm/services/cli/__init__.py

@@ -5,6 +5,7 @@ Services specifically for CLI command support and utilities.
 
 from .agent_dependency_service import AgentDependencyService, IAgentDependencyService
 from .agent_validation_service import AgentValidationService, IAgentValidationService
+from .incremental_pause_manager import IncrementalPauseManager, PauseAction
 from .startup_checker import IStartupChecker, StartupCheckerService, StartupWarning
 
 __all__ = [
@@ -13,6 +14,8 @@ __all__ = [
     "IAgentDependencyService",
     "IAgentValidationService",
     "IStartupChecker",
+    "IncrementalPauseManager",
+    "PauseAction",
     "StartupCheckerService",
     "StartupWarning",
 ]