claude-mpm 5.4.48__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

@@ -395,7 +395,9 @@ class GitSourceManager:
                     )
                     logger.debug(f"[DEBUG] Found {len(agents)} agents so far")
 
-        logger.debug(f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents (before deduplication)")
+        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
@@ -410,7 +412,9 @@ class GitSourceManager:
             elif agent_id:
                 logger.debug(f"[DEBUG] Skipping duplicate agent: {agent_id}")
 
-        logger.debug(f"[DEBUG] After deduplication: {len(deduplicated_agents)} unique agents")
+        logger.debug(
+            f"[DEBUG] After deduplication: {len(deduplicated_agents)} unique agents"
+        )
         return deduplicated_agents
 
     def _discover_agents_in_directory(

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/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__)
 

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -1092,7 +1092,9 @@ class GitSourceSyncService:
 
         # Clean up any previously deployed excluded agents
         if excluded_set:
-            cleanup_results = self._cleanup_excluded_agents(deployment_dir, 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: "
@@ -1116,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:
@@ -156,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

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",
 ]