claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/services/agents/deployment/agent_lifecycle_manager.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 #!/usr/bin/env python3
 """
 Agent Lifecycle Manager - ISS-0118 Integration Service
@@ -25,38 +27,37 @@ Created for ISS-0118: Agent Registry and Hierarchical Discovery System
 """
 
 import asyncio
-import logging
 import time
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from enum import Enum
-from pathlib import Path
-from typing import Dict, List, Optional, Set, Any, Tuple, Union
+from typing import Any, Dict, List, Optional, Set, Tuple, Union
 
-from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
-from claude_mpm.services.agents.registry import AgentRegistry, AgentMetadata
-from claude_mpm.services.agents.registry.modification_tracker import (
-    AgentModificationTracker, 
-    AgentModification, 
-    ModificationType, 
-    ModificationTier
-)
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.unified_paths import get_path_manager
+from claude_mpm.models.agent_definition import AgentDefinition, AgentType
+from claude_mpm.services.agents.management import AgentManager
 from claude_mpm.services.agents.memory import (
     AgentPersistenceService,
-    PersistenceStrategy,
+    PersistenceOperation,
     PersistenceRecord,
-    PersistenceOperation
+    PersistenceStrategy,
 )
-from claude_mpm.services.agents.management import AgentManager
-from claude_mpm.models.agent_definition import AgentDefinition, AgentType
-from claude_mpm.core.base_service import BaseService
-from claude_mpm.core.config_paths import ConfigPaths
-from claude_mpm.utils.path_operations import path_ops
+from claude_mpm.services.agents.registry import AgentMetadata, AgentRegistry
+from claude_mpm.services.agents.registry.modification_tracker import (
+    AgentModification,
+    AgentModificationTracker,
+    ModificationTier,
+    ModificationType,
+)
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 from claude_mpm.utils.config_manager import ConfigurationManager
+from claude_mpm.utils.path_operations import path_ops
 
 
 class LifecycleOperation(Enum):
     """Agent lifecycle operations."""
+
     CREATE = "create"
     UPDATE = "update"
     DELETE = "delete"
@@ -68,6 +69,7 @@ class LifecycleOperation(Enum):
 
 class LifecycleState(Enum):
     """Agent lifecycle states."""
+
     ACTIVE = "active"
     MODIFIED = "modified"
     DELETED = "deleted"
@@ -79,7 +81,7 @@ class LifecycleState(Enum):
 @dataclass
 class AgentLifecycleRecord:
     """Complete lifecycle record for an agent."""
-    
+
     agent_name: str
     current_state: LifecycleState
     tier: ModificationTier
@@ -93,12 +95,12 @@ class AgentLifecycleRecord:
     validation_status: str = "valid"
     validation_errors: List[str] = field(default_factory=list)
     metadata: Dict[str, Any] = field(default_factory=dict)
-    
+
     @property
     def age_days(self) -> float:
         """Get age in days."""
         return (time.time() - self.created_at) / (24 * 3600)
-    
+
     @property
     def last_modified_datetime(self) -> datetime:
         """Get last modified as datetime."""
@@ -108,7 +110,7 @@ class AgentLifecycleRecord:
 @dataclass
 class LifecycleOperationResult:
     """Result of a lifecycle operation."""
-    
+
     operation: LifecycleOperation
     agent_name: str
     success: bool
@@ -124,7 +126,7 @@ class LifecycleOperationResult:
 class AgentLifecycleManager(BaseService):
     """
     Agent Lifecycle Manager - Unified agent management across hierarchy tiers.
-    
+
     Features:
     - Complete agent lifecycle management (CRUD operations)
     - Integrated modification tracking and persistence
@@ -133,132 +135,117 @@ class AgentLifecycleManager(BaseService):
     - Real-time conflict detection and resolution
     - Performance monitoring and optimization
     """
-    
+
     def __init__(self, config: Optional[Dict[str, Any]] = None):
         """Initialize the agent lifecycle manager."""
         super().__init__("agent_lifecycle_manager", config)
-        
+
         # Configuration
         self.enable_auto_backup = self.get_config("enable_auto_backup", True)
         self.enable_auto_validation = self.get_config("enable_auto_validation", True)
-        self.enable_cache_invalidation = self.get_config("enable_cache_invalidation", True)
+        self.enable_cache_invalidation = self.get_config(
+            "enable_cache_invalidation", True
+        )
         self.enable_registry_sync = self.get_config("enable_registry_sync", True)
         self.default_persistence_strategy = PersistenceStrategy(
-            self.get_config("default_persistence_strategy", PersistenceStrategy.USER_OVERRIDE.value)
+            self.get_config(
+                "default_persistence_strategy", PersistenceStrategy.USER_OVERRIDE.value
+            )
         )
-        
+
         # Core services
         self.shared_cache: Optional[SharedPromptCache] = None
         self.agent_registry: Optional[AgentRegistry] = None
         self.modification_tracker: Optional[AgentModificationTracker] = None
         self.persistence_service: Optional[AgentPersistenceService] = None
         self.agent_manager: Optional[AgentManager] = None
-        
+
         # Lifecycle tracking
         self.agent_records: Dict[str, AgentLifecycleRecord] = {}
         self.operation_history: List[LifecycleOperationResult] = []
         self.active_operations: Dict[str, LifecycleOperation] = {}
-        
+
         # Performance metrics
         self.performance_metrics = {
-            'total_operations': 0,
-            'successful_operations': 0,
-            'failed_operations': 0,
-            'average_duration_ms': 0.0,
-            'cache_hit_rate': 0.0
+            "total_operations": 0,
+            "successful_operations": 0,
+            "failed_operations": 0,
+            "average_duration_ms": 0.0,
+            "cache_hit_rate": 0.0,
         }
-        
+
         # Operation lock for thread safety
         self._operation_lock = asyncio.Lock()
-        
+
         # Configuration manager
         self.config_mgr = ConfigurationManager(cache_enabled=True)
-        
+
         self.logger.info("AgentLifecycleManager initialized")
-    
+
     async def _initialize(self) -> None:
         """Initialize the lifecycle manager."""
         self.logger.info("Initializing AgentLifecycleManager...")
-        
+
         # Initialize core services
         await self._initialize_core_services()
-        
+
         # Load existing agent records
         await self._load_agent_records()
-        
+
         # Start service integrations
         await self._setup_service_integrations()
-        
+
         # Perform initial registry sync
         if self.enable_registry_sync:
             await self._sync_with_registry()
-        
+
         self.logger.info("AgentLifecycleManager initialized successfully")
-    
+
     async def _cleanup(self) -> None:
         """Cleanup lifecycle manager resources."""
         self.logger.info("Cleaning up AgentLifecycleManager...")
-        
+
         # Save agent records
         await self._save_agent_records()
-        
+
         # Stop core services if we own them
         await self._cleanup_core_services()
-        
+
         self.logger.info("AgentLifecycleManager cleaned up")
-    
+
     async def _health_check(self) -> Dict[str, bool]:
         """Perform lifecycle manager health checks."""
-        checks = {}
-        
-        try:
-            # Check core service availability
-            checks["cache_service"] = self.shared_cache is not None
-            checks["registry_service"] = self.agent_registry is not None
-            checks["tracker_service"] = self.modification_tracker is not None
-            checks["persistence_service"] = self.persistence_service is not None
-            
-            # Check operation capabilities
-            checks["can_create_agents"] = await self._test_create_capability()
-            checks["can_modify_agents"] = await self._test_modify_capability()
-            checks["can_delete_agents"] = await self._test_delete_capability()
-            
-            # Check data integrity
-            checks["agent_records_valid"] = len(self.agent_records) >= 0
-            checks["operation_history_valid"] = len(self.operation_history) >= 0
-            
-        except Exception as e:
-            self.logger.error(f"Lifecycle manager health check failed: {e}")
-            checks["health_check_error"] = False
-        
-        return checks
-    
+        from .lifecycle_health_checker import LifecycleHealthChecker
+
+        checker = LifecycleHealthChecker(self)
+        return await checker.perform_health_check()
+
     async def _initialize_core_services(self) -> None:
         """Initialize core service dependencies."""
         try:
             # Initialize SharedPromptCache
             self.shared_cache = SharedPromptCache.get_instance()
-            
+
             # Initialize AgentRegistry
             self.agent_registry = AgentRegistry(cache_service=self.shared_cache)
-            
+
             # Initialize AgentModificationTracker
             self.modification_tracker = AgentModificationTracker()
             await self.modification_tracker.start()
-            
+
             # Initialize AgentPersistenceService
             self.persistence_service = AgentPersistenceService()
             await self.persistence_service.start()
-            
+
             # Initialize AgentManager
             self.agent_manager = AgentManager()
-            
+
             self.logger.info("Core services initialized successfully")
-            
+
         except Exception as e:
             self.logger.error(f"Failed to initialize core services: {e}")
             raise
-    
+
     async def _setup_service_integrations(self) -> None:
         """Set up integrations between services."""
         try:
@@ -267,79 +254,83 @@ class AgentLifecycleManager(BaseService):
                 self.modification_tracker.register_modification_callback(
                     self._handle_modification_event
                 )
-            
+
             self.logger.debug("Service integrations set up successfully")
-            
+
         except Exception as e:
             self.logger.warning(f"Failed to setup some service integrations: {e}")
-    
+
     async def _load_agent_records(self) -> None:
         """Load existing agent lifecycle records."""
         try:
-            records_file = ConfigPaths.get_tracking_dir() / 'lifecycle_records.json'
+            records_file = (
+                get_path_manager().get_tracking_dir() / "lifecycle_records.json"
+            )
             if path_ops.validate_exists(records_file):
                 data = self.config_mgr.load_json(records_file)
-                
+
                 for agent_name, record_data in data.items():
                     record = AgentLifecycleRecord(**record_data)
                     # Convert string enum back to enum
-                    record.current_state = LifecycleState(record_data['current_state'])
-                    record.tier = ModificationTier(record_data['tier'])
+                    record.current_state = LifecycleState(record_data["current_state"])
+                    record.tier = ModificationTier(record_data["tier"])
                     self.agent_records[agent_name] = record
-                
+
                 self.logger.info(f"Loaded {len(self.agent_records)} agent records")
-            
+
         except Exception as e:
             self.logger.warning(f"Failed to load agent records: {e}")
-    
+
     async def _save_agent_records(self) -> None:
         """Save agent lifecycle records to disk."""
         try:
-            records_file = ConfigPaths.get_tracking_dir() / 'lifecycle_records.json'
+            records_file = (
+                get_path_manager().get_tracking_dir() / "lifecycle_records.json"
+            )
             path_ops.ensure_dir(records_file.parent)
-            
+
             data = {}
             for agent_name, record in self.agent_records.items():
                 record_dict = record.__dict__.copy()
                 # Convert enums to strings for JSON serialization
-                record_dict['current_state'] = record.current_state.value
-                record_dict['tier'] = record.tier.value
+                record_dict["current_state"] = record.current_state.value
+                record_dict["tier"] = record.tier.value
                 data[agent_name] = record_dict
-            
+
             # Use save_json with custom encoder for datetime serialization
             import json
-            
+
             # First convert to JSON string with custom encoder, then save
             json_str = json.dumps(data, indent=2, default=str)
             records_file.parent.mkdir(parents=True, exist_ok=True)
-            with open(records_file, 'w', encoding='utf-8') as f:
+            with open(records_file, "w", encoding="utf-8") as f:
                 f.write(json_str)
-            
+
             self.logger.debug(f"Saved {len(self.agent_records)} agent records")
-            
+
         except Exception as e:
             self.logger.error(f"Failed to save agent records: {e}")
-    
+
     async def _sync_with_registry(self) -> None:
         """Synchronize with agent registry."""
         try:
             if not self.agent_registry:
                 return
-            
+
             # Discover all agents via registry (sync methods)
             self.agent_registry.discover_agents()
             all_agents = self.agent_registry.list_agents()
-            
+
             # Update lifecycle records with registry data
             for agent_metadata in all_agents:
                 if agent_metadata.name not in self.agent_records:
                     # Create new lifecycle record
                     tier_map = {
-                        'project': ModificationTier.PROJECT,
-                        'user': ModificationTier.USER,
-                        'system': ModificationTier.SYSTEM
+                        "project": ModificationTier.PROJECT,
+                        "user": ModificationTier.USER,
+                        "system": ModificationTier.SYSTEM,
                     }
-                    
+
                     record = AgentLifecycleRecord(
                         agent_name=agent_metadata.name,
                         current_state=LifecycleState.ACTIVE,
@@ -349,44 +340,46 @@ class AgentLifecycleManager(BaseService):
                         last_modified=agent_metadata.last_modified or time.time(),
                         version="1.0.0",
                         metadata={
-                            'type': agent_metadata.type,
-                            'description': agent_metadata.description,
-                            'capabilities': agent_metadata.capabilities,
-                            'validated': agent_metadata.validated
-                        }
+                            "type": agent_metadata.type,
+                            "description": agent_metadata.description,
+                            "capabilities": agent_metadata.capabilities,
+                            "validated": agent_metadata.validated,
+                        },
                     )
-                    
+
                     self.agent_records[agent_metadata.name] = record
-            
+
             self.logger.info(f"Synchronized with registry: {len(all_agents)} agents")
-            
+
         except Exception as e:
             self.logger.error(f"Failed to sync with registry: {e}")
-    
-    async def create_agent(self,
-                          agent_name: str,
-                          agent_content: str,
-                          tier: ModificationTier = ModificationTier.USER,
-                          agent_type: str = "custom",
-                          **kwargs) -> LifecycleOperationResult:
+
+    async def create_agent(
+        self,
+        agent_name: str,
+        agent_content: str,
+        tier: ModificationTier = ModificationTier.USER,
+        agent_type: str = "custom",
+        **kwargs,
+    ) -> LifecycleOperationResult:
         """
         Create a new agent with complete lifecycle tracking.
-        
+
         Args:
             agent_name: Name of the agent to create
             agent_content: Content of the agent file
             tier: Target tier for creation
             agent_type: Type of agent (for classification)
             **kwargs: Additional metadata
-            
+
         Returns:
             LifecycleOperationResult with operation details
         """
         start_time = time.time()
-        
+
         async with self._operation_lock:
             self.active_operations[agent_name] = LifecycleOperation.CREATE
-            
+
             try:
                 # Check if agent already exists
                 if agent_name in self.agent_records:
@@ -395,27 +388,33 @@ class AgentLifecycleManager(BaseService):
                         agent_name=agent_name,
                         success=False,
                         duration_ms=(time.time() - start_time) * 1000,
-                        error_message="Agent already exists"
+                        error_message="Agent already exists",
                     )
-                
+
                 # Create agent definition
                 agent_def = await self._create_agent_definition(
                     agent_name, agent_content, tier, agent_type, **kwargs
                 )
-                
+
                 # Determine location based on tier
-                location = "project" if tier == ModificationTier.PROJECT else "framework"
-                
+                location = (
+                    "project" if tier == ModificationTier.PROJECT else "framework"
+                )
+
                 # Create agent using AgentManager (sync call in executor)
                 try:
                     if self.agent_manager:
                         file_path = await self._run_sync_in_executor(
                             self.agent_manager.create_agent,
-                            agent_name, agent_def, location
+                            agent_name,
+                            agent_def,
+                            location,
                         )
                     else:
                         # Fallback to direct file creation if AgentManager not available
-                        file_path = await self._determine_agent_file_path(agent_name, tier)
+                        file_path = await self._determine_agent_file_path(
+                            agent_name, tier
+                        )
                         path_ops.ensure_dir(file_path.parent)
                         path_ops.safe_write(file_path, agent_content)
                 except Exception as e:
@@ -424,7 +423,7 @@ class AgentLifecycleManager(BaseService):
                     file_path = await self._determine_agent_file_path(agent_name, tier)
                     path_ops.ensure_dir(file_path.parent)
                     path_ops.safe_write(file_path, agent_content)
-                
+
                 # Track modification
                 modification = await self.modification_tracker.track_modification(
                     agent_name=agent_name,
@@ -432,9 +431,9 @@ class AgentLifecycleManager(BaseService):
                     file_path=str(file_path),
                     tier=tier,
                     agent_type=agent_type,
-                    **kwargs
+                    **kwargs,
                 )
-                
+
                 # Note: We don't use persistence_service for the actual write anymore
                 # since AgentManager handles that. We create a synthetic record for compatibility.
                 persistence_record = PersistenceRecord(
@@ -446,9 +445,9 @@ class AgentLifecycleManager(BaseService):
                     strategy=self.default_persistence_strategy,
                     success=True,
                     timestamp=time.time(),
-                    file_path=str(file_path)
+                    file_path=str(file_path),
                 )
-                
+
                 # Create lifecycle record
                 lifecycle_record = AgentLifecycleRecord(
                     agent_name=agent_name,
@@ -460,18 +459,15 @@ class AgentLifecycleManager(BaseService):
                     version="1.0.0",
                     modifications=[modification.modification_id],
                     persistence_operations=[persistence_record.operation_id],
-                    metadata={
-                        'agent_type': agent_type,
-                        **kwargs
-                    }
+                    metadata={"agent_type": agent_type, **kwargs},
                 )
-                
+
                 self.agent_records[agent_name] = lifecycle_record
-                
+
                 # Invalidate cache and update registry
                 cache_invalidated = await self._invalidate_agent_cache(agent_name)
                 registry_updated = await self._update_registry(agent_name)
-                
+
                 # Create result
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.CREATE,
@@ -482,59 +478,60 @@ class AgentLifecycleManager(BaseService):
                     persistence_id=persistence_record.operation_id,
                     cache_invalidated=cache_invalidated,
                     registry_updated=registry_updated,
-                    metadata={'file_path': str(file_path)}
+                    metadata={"file_path": str(file_path)},
                 )
-                
+
                 if not persistence_record.success:
                     result.error_message = persistence_record.error_message
                     lifecycle_record.current_state = LifecycleState.CONFLICTED
-                
+
                 # Update performance metrics
                 await self._update_performance_metrics(result)
-                
+
                 self.operation_history.append(result)
-                self.logger.info(f"Created agent '{agent_name}' in {result.duration_ms:.1f}ms")
-                
+                self.logger.info(
+                    f"Created agent '{agent_name}' in {result.duration_ms:.1f}ms"
+                )
+
                 return result
-                
+
             except Exception as e:
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.CREATE,
                     agent_name=agent_name,
                     success=False,
                     duration_ms=(time.time() - start_time) * 1000,
-                    error_message=str(e)
+                    error_message=str(e),
                 )
-                
+
                 self.operation_history.append(result)
                 await self._update_performance_metrics(result)
-                
+
                 self.logger.error(f"Failed to create agent '{agent_name}': {e}")
                 return result
-            
+
             finally:
                 self.active_operations.pop(agent_name, None)
-    
-    async def update_agent(self,
-                          agent_name: str,
-                          agent_content: str,
-                          **kwargs) -> LifecycleOperationResult:
+
+    async def update_agent(
+        self, agent_name: str, agent_content: str, **kwargs
+    ) -> LifecycleOperationResult:
         """
         Update an existing agent with lifecycle tracking.
-        
+
         Args:
             agent_name: Name of the agent to update
             agent_content: New content for the agent
             **kwargs: Additional metadata
-            
+
         Returns:
             LifecycleOperationResult with operation details
         """
         start_time = time.time()
-        
+
         async with self._operation_lock:
             self.active_operations[agent_name] = LifecycleOperation.UPDATE
-            
+
             try:
                 # Check if agent exists
                 if agent_name not in self.agent_records:
@@ -543,11 +540,11 @@ class AgentLifecycleManager(BaseService):
                         agent_name=agent_name,
                         success=False,
                         duration_ms=(time.time() - start_time) * 1000,
-                        error_message="Agent not found"
+                        error_message="Agent not found",
                     )
-                
+
                 record = self.agent_records[agent_name]
-                
+
                 # Update agent using AgentManager
                 try:
                     if self.agent_manager:
@@ -555,25 +552,31 @@ class AgentLifecycleManager(BaseService):
                         current_def = await self._run_sync_in_executor(
                             self.agent_manager.read_agent, agent_name
                         )
-                        
+
                         if current_def:
                             # Update raw content
                             current_def.raw_content = agent_content
-                            
+
                             # Apply any metadata updates from kwargs
-                            if 'model_preference' in kwargs:
-                                current_def.metadata.model_preference = kwargs['model_preference']
-                            if 'tags' in kwargs:
-                                current_def.metadata.tags = kwargs['tags']
-                            if 'specializations' in kwargs:
-                                current_def.metadata.specializations = kwargs['specializations']
-                            
+                            if "model_preference" in kwargs:
+                                current_def.metadata.model_preference = kwargs[
+                                    "model_preference"
+                                ]
+                            if "tags" in kwargs:
+                                current_def.metadata.tags = kwargs["tags"]
+                            if "specializations" in kwargs:
+                                current_def.metadata.specializations = kwargs[
+                                    "specializations"
+                                ]
+
                             # Update via AgentManager
                             updated_def = await self._run_sync_in_executor(
                                 self.agent_manager.update_agent,
-                                agent_name, {"raw_content": agent_content}, True
+                                agent_name,
+                                {"raw_content": agent_content},
+                                True,
                             )
-                            
+
                             if not updated_def:
                                 raise Exception("AgentManager update failed")
                         else:
@@ -589,16 +592,16 @@ class AgentLifecycleManager(BaseService):
                     file_path = Path(record.file_path)
                     if path_ops.validate_exists(file_path):
                         path_ops.safe_write(file_path, agent_content)
-                
+
                 # Track modification
                 modification = await self.modification_tracker.track_modification(
                     agent_name=agent_name,
                     modification_type=ModificationType.MODIFY,
                     file_path=record.file_path,
                     tier=record.tier,
-                    **kwargs
+                    **kwargs,
                 )
-                
+
                 # Create synthetic persistence record for compatibility
                 persistence_record = PersistenceRecord(
                     operation_id=f"update_{agent_name}_{time.time()}",
@@ -609,24 +612,24 @@ class AgentLifecycleManager(BaseService):
                     strategy=self.default_persistence_strategy,
                     success=True,
                     timestamp=time.time(),
-                    file_path=record.file_path
+                    file_path=record.file_path,
                 )
-                
+
                 # Update lifecycle record
                 record.current_state = LifecycleState.MODIFIED
                 record.last_modified = time.time()
                 record.modifications.append(modification.modification_id)
                 record.persistence_operations.append(persistence_record.operation_id)
-                
+
                 # Increment version
-                current_version = record.version.split('.')
+                current_version = record.version.split(".")
                 current_version[-1] = str(int(current_version[-1]) + 1)
-                record.version = '.'.join(current_version)
-                
+                record.version = ".".join(current_version)
+
                 # Invalidate cache and update registry
                 cache_invalidated = await self._invalidate_agent_cache(agent_name)
                 registry_updated = await self._update_registry(agent_name)
-                
+
                 # Create result
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.UPDATE,
@@ -637,55 +640,57 @@ class AgentLifecycleManager(BaseService):
                     persistence_id=persistence_record.operation_id,
                     cache_invalidated=cache_invalidated,
                     registry_updated=registry_updated,
-                    metadata={'new_version': record.version}
+                    metadata={"new_version": record.version},
                 )
-                
+
                 if not persistence_record.success:
                     result.error_message = persistence_record.error_message
                     record.current_state = LifecycleState.CONFLICTED
-                
+
                 # Update performance metrics
                 await self._update_performance_metrics(result)
-                
+
                 self.operation_history.append(result)
-                self.logger.info(f"Updated agent '{agent_name}' to version {record.version} in {result.duration_ms:.1f}ms")
-                
+                self.logger.info(
+                    f"Updated agent '{agent_name}' to version {record.version} in {result.duration_ms:.1f}ms"
+                )
+
                 return result
-                
+
             except Exception as e:
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.UPDATE,
                     agent_name=agent_name,
                     success=False,
                     duration_ms=(time.time() - start_time) * 1000,
-                    error_message=str(e)
+                    error_message=str(e),
                 )
-                
+
                 self.operation_history.append(result)
                 await self._update_performance_metrics(result)
-                
+
                 self.logger.error(f"Failed to update agent '{agent_name}': {e}")
                 return result
-            
+
             finally:
                 self.active_operations.pop(agent_name, None)
-    
+
     async def delete_agent(self, agent_name: str, **kwargs) -> LifecycleOperationResult:
         """
         Delete an agent with lifecycle tracking.
-        
+
         Args:
             agent_name: Name of the agent to delete
             **kwargs: Additional metadata
-            
+
         Returns:
             LifecycleOperationResult with operation details
         """
         start_time = time.time()
-        
+
         async with self._operation_lock:
             self.active_operations[agent_name] = LifecycleOperation.DELETE
-            
+
             try:
                 # Check if agent exists
                 if agent_name not in self.agent_records:
@@ -694,16 +699,16 @@ class AgentLifecycleManager(BaseService):
                         agent_name=agent_name,
                         success=False,
                         duration_ms=(time.time() - start_time) * 1000,
-                        error_message="Agent not found"
+                        error_message="Agent not found",
                     )
-                
+
                 record = self.agent_records[agent_name]
-                
+
                 # Create backup before deletion
                 backup_path = None
                 if self.enable_auto_backup:
                     backup_path = await self._create_deletion_backup(agent_name, record)
-                
+
                 # Track modification
                 modification = await self.modification_tracker.track_modification(
                     agent_name=agent_name,
@@ -711,9 +716,9 @@ class AgentLifecycleManager(BaseService):
                     file_path=record.file_path,
                     tier=record.tier,
                     backup_path=backup_path,
-                    **kwargs
+                    **kwargs,
                 )
-                
+
                 # Delete agent using AgentManager
                 deletion_success = False
                 try:
@@ -736,18 +741,18 @@ class AgentLifecycleManager(BaseService):
                     if path_ops.validate_exists(file_path):
                         path_ops.safe_delete(file_path)
                         deletion_success = True
-                
+
                 # Update lifecycle record
                 record.current_state = LifecycleState.DELETED
                 record.last_modified = time.time()
                 record.modifications.append(modification.modification_id)
                 if backup_path:
                     record.backup_paths.append(backup_path)
-                
+
                 # Invalidate cache and update registry
                 cache_invalidated = await self._invalidate_agent_cache(agent_name)
                 registry_updated = await self._update_registry(agent_name)
-                
+
                 # Create result
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.DELETE,
@@ -757,414 +762,259 @@ class AgentLifecycleManager(BaseService):
                     modification_id=modification.modification_id,
                     cache_invalidated=cache_invalidated,
                     registry_updated=registry_updated,
-                    metadata={'backup_path': backup_path}
+                    metadata={"backup_path": backup_path},
                 )
-                
+
                 # Update performance metrics
                 await self._update_performance_metrics(result)
-                
+
                 self.operation_history.append(result)
-                self.logger.info(f"Deleted agent '{agent_name}' in {result.duration_ms:.1f}ms")
-                
+                self.logger.info(
+                    f"Deleted agent '{agent_name}' in {result.duration_ms:.1f}ms"
+                )
+
                 return result
-                
+
             except Exception as e:
                 result = LifecycleOperationResult(
                     operation=LifecycleOperation.DELETE,
                     agent_name=agent_name,
                     success=False,
                     duration_ms=(time.time() - start_time) * 1000,
-                    error_message=str(e)
+                    error_message=str(e),
                 )
-                
+
                 self.operation_history.append(result)
                 await self._update_performance_metrics(result)
-                
+
                 self.logger.error(f"Failed to delete agent '{agent_name}': {e}")
                 return result
-            
+
             finally:
                 self.active_operations.pop(agent_name, None)
-    
-    async def _determine_agent_file_path(self, agent_name: str, tier: ModificationTier) -> Path:
+
+    async def _determine_agent_file_path(
+        self, agent_name: str, tier: ModificationTier
+    ) -> Path:
         """Determine appropriate file path for agent."""
         if tier == ModificationTier.USER:
-            base_path = ConfigPaths.get_user_agents_dir()
+            base_path = get_path_manager().get_user_agents_dir()
         elif tier == ModificationTier.PROJECT:
-            base_path = ConfigPaths.get_project_agents_dir()
+            base_path = get_path_manager().get_project_agents_dir()
         else:  # SYSTEM
-            base_path = Path.cwd() / 'claude_pm' / 'agents'
-        
+            base_path = Path.cwd() / "claude_pm" / "agents"
+
         path_ops.ensure_dir(base_path)
         return base_path / f"{agent_name}_agent.py"
-    
-    async def _create_deletion_backup(self, agent_name: str, record: AgentLifecycleRecord) -> Optional[str]:
+
+    async def _create_deletion_backup(
+        self, agent_name: str, record: AgentLifecycleRecord
+    ) -> Optional[str]:
         """Create backup before agent deletion."""
         try:
             source_path = Path(record.file_path)
             if not path_ops.validate_exists(source_path):
                 return None
-            
-            backup_dir = ConfigPaths.get_tracking_dir() / 'backups'
+
+            backup_dir = get_path_manager().get_tracking_dir() / "backups"
             path_ops.ensure_dir(backup_dir)
-            
-            timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
             backup_filename = f"{agent_name}_deleted_{timestamp}{source_path.suffix}"
             backup_path = backup_dir / backup_filename
-            
+
             path_ops.safe_copy(source_path, backup_path)
             return str(backup_path)
-            
+
         except Exception as e:
-            self.logger.warning(f"Failed to create deletion backup for {agent_name}: {e}")
+            self.logger.warning(
+                f"Failed to create deletion backup for {agent_name}: {e}"
+            )
             return None
-    
+
     async def _invalidate_agent_cache(self, agent_name: str) -> bool:
         """Invalidate cache entries for agent."""
         if not self.enable_cache_invalidation or not self.shared_cache:
             return False
-        
+
         try:
             patterns = [
                 f"agent_profile:{agent_name}:*",
                 f"task_prompt:{agent_name}:*",
                 f"agent_registry_discovery",
-                f"agent_profile_enhanced:{agent_name}:*"
+                f"agent_profile_enhanced:{agent_name}:*",
             ]
-            
+
             for pattern in patterns:
                 await asyncio.get_event_loop().run_in_executor(
-                    None, 
-                    lambda p=pattern: self.shared_cache.invalidate(p)
+                    None, lambda p=pattern: self.shared_cache.invalidate(p)
                 )
-            
+
             return True
-            
+
         except Exception as e:
             self.logger.warning(f"Failed to invalidate cache for {agent_name}: {e}")
             return False
-    
+
     async def _update_registry(self, agent_name: str) -> bool:
         """Update agent registry after modification."""
         if not self.enable_registry_sync or not self.agent_registry:
             return False
-        
+
         try:
             # Refresh registry (discover_agents is synchronous)
             self.agent_registry.discover_agents()
             return True
-            
+
         except Exception as e:
             self.logger.warning(f"Failed to update registry for {agent_name}: {e}")
             return False
-    
-    async def _update_performance_metrics(self, result: LifecycleOperationResult) -> None:
-        """Update performance metrics with operation result.
-        
-        METRICS COLLECTION:
-        This method demonstrates a simple ETL pipeline for operational metrics:
-        
-        1. EXTRACT: Pull raw data from operation results
-           - Success/failure status
-           - Operation duration
-           - Cache invalidation events
-           - Operation type and agent tier
-        
-        2. TRANSFORM: Calculate derived metrics
-           - Success rates and failure percentages
-           - Rolling averages for performance
-           - Operation distribution by type
-           - Performance by agent tier
-        
-        3. LOAD: Store in metrics structure
-           - In-memory storage for real-time access
-           - Could be extended to push to:
-             * Time-series databases (Prometheus, InfluxDB)
-             * AI observability platforms (Datadog, New Relic)
-             * Custom analytics pipelines
-        
-        OPTIMIZATION OPPORTUNITIES:
-        - Add percentile calculations (p50, p95, p99)
-        - Track operation queuing times
-        - Monitor resource usage per operation
-        - Implement sliding window metrics
-        """
-        self.performance_metrics['total_operations'] += 1
-        
-        if result.success:
-            self.performance_metrics['successful_operations'] += 1
-        else:
-            self.performance_metrics['failed_operations'] += 1
-        
-        # Update average duration using incremental calculation
-        # This avoids storing all durations in memory
-        total_ops = self.performance_metrics['total_operations']
-        current_avg = self.performance_metrics['average_duration_ms']
-        new_avg = ((current_avg * (total_ops - 1)) + result.duration_ms) / total_ops
-        self.performance_metrics['average_duration_ms'] = new_avg
-        
-        # METRICS: Track operation type distribution
-        # This helps identify which operations are most common
-        op_type = result.operation.value
-        if 'operation_distribution' not in self.performance_metrics:
-            self.performance_metrics['operation_distribution'] = {}
-        self.performance_metrics['operation_distribution'][op_type] = \
-            self.performance_metrics['operation_distribution'].get(op_type, 0) + 1
-        
-        # METRICS: Track performance by agent tier
-        # Useful for identifying tier-specific performance issues
-        if hasattr(result, 'tier') and result.tier:
-            if 'tier_performance' not in self.performance_metrics:
-                self.performance_metrics['tier_performance'] = {}
-            tier_name = result.tier.value if hasattr(result.tier, 'value') else str(result.tier)
-            if tier_name not in self.performance_metrics['tier_performance']:
-                self.performance_metrics['tier_performance'][tier_name] = {
-                    'count': 0,
-                    'total_duration_ms': 0,
-                    'average_duration_ms': 0
-                }
-            tier_metrics = self.performance_metrics['tier_performance'][tier_name]
-            tier_metrics['count'] += 1
-            tier_metrics['total_duration_ms'] += result.duration_ms
-            tier_metrics['average_duration_ms'] = \
-                tier_metrics['total_duration_ms'] / tier_metrics['count']
-        
-        # Update cache hit rate if cache was involved
-        if result.cache_invalidated:
-            # Track cache invalidation frequency
-            if 'cache_invalidations' not in self.performance_metrics:
-                self.performance_metrics['cache_invalidations'] = 0
-            self.performance_metrics['cache_invalidations'] += 1
-    
+
+    async def _update_performance_metrics(
+        self, result: LifecycleOperationResult
+    ) -> None:
+        """Update performance metrics with operation result."""
+        from .lifecycle_performance_tracker import LifecyclePerformanceTracker
+
+        tracker = LifecyclePerformanceTracker(self.performance_metrics)
+        tracker.update_metrics(result)
+
     async def _handle_modification_event(self, modification: AgentModification) -> None:
         """Handle modification events from tracker."""
         try:
             agent_name = modification.agent_name
-            
+
             # Update lifecycle record if exists
             if agent_name in self.agent_records:
                 record = self.agent_records[agent_name]
                 record.last_modified = modification.timestamp
                 record.modifications.append(modification.modification_id)
-                
+
                 # Update state based on modification type
                 if modification.modification_type == ModificationType.DELETE:
                     record.current_state = LifecycleState.DELETED
-                elif modification.modification_type in [ModificationType.CREATE, ModificationType.MODIFY]:
+                elif modification.modification_type in [
+                    ModificationType.CREATE,
+                    ModificationType.MODIFY,
+                ]:
                     record.current_state = LifecycleState.MODIFIED
-                
-                self.logger.debug(f"Updated lifecycle record for {agent_name} due to {modification.modification_type.value}")
-            
+
+                self.logger.debug(
+                    f"Updated lifecycle record for {agent_name} due to {modification.modification_type.value}"
+                )
+
         except Exception as e:
             self.logger.error(f"Error handling modification event: {e}")
-    
-    async def _test_create_capability(self) -> bool:
-        """Test agent creation capability."""
-        try:
-            # This would test if we can create agents in the configured tiers
-            return (self.modification_tracker is not None and 
-                   self.persistence_service is not None)
-        except Exception:
-            return False
-    
-    async def _test_modify_capability(self) -> bool:
-        """Test agent modification capability."""
-        try:
-            # This would test if we can modify existing agents
-            return (self.modification_tracker is not None and 
-                   self.persistence_service is not None)
-        except Exception:
-            return False
-    
-    async def _test_delete_capability(self) -> bool:
-        """Test agent deletion capability."""
-        try:
-            # This would test if we can delete agents
-            return self.modification_tracker is not None
-        except Exception:
-            return False
-    
+
+    # Test capability methods moved to LifecycleHealthChecker
+
     async def _cleanup_core_services(self) -> None:
         """Cleanup core services if we manage their lifecycle."""
         try:
             if self.modification_tracker:
                 await self.modification_tracker.stop()
-            
+
             if self.persistence_service:
                 await self.persistence_service.stop()
-            
+
         except Exception as e:
             self.logger.error(f"Error cleaning up core services: {e}")
-    
+
     # Public API Methods
-    
+
     async def get_agent_status(self, agent_name: str) -> Optional[AgentLifecycleRecord]:
         """Get current status of an agent."""
         return self.agent_records.get(agent_name)
-    
-    async def list_agents(self, state_filter: Optional[LifecycleState] = None) -> List[AgentLifecycleRecord]:
+
+    async def list_agents(
+        self, state_filter: Optional[LifecycleState] = None
+    ) -> List[AgentLifecycleRecord]:
         """List agents with optional state filtering."""
         agents = list(self.agent_records.values())
-        
+
         if state_filter:
             agents = [agent for agent in agents if agent.current_state == state_filter]
-        
+
         return sorted(agents, key=lambda x: x.last_modified, reverse=True)
-    
-    async def get_operation_history(self, agent_name: Optional[str] = None, limit: int = 100) -> List[LifecycleOperationResult]:
+
+    async def get_operation_history(
+        self, agent_name: Optional[str] = None, limit: int = 100
+    ) -> List[LifecycleOperationResult]:
         """Get operation history with optional filtering."""
         history = self.operation_history
-        
+
         if agent_name:
             history = [op for op in history if op.agent_name == agent_name]
-        
+
         return sorted(history, key=lambda x: x.duration_ms, reverse=True)[:limit]
-    
+
     async def get_lifecycle_stats(self) -> Dict[str, Any]:
         """Get comprehensive lifecycle statistics."""
         stats = {
-            'total_agents': len(self.agent_records),
-            'active_operations': len(self.active_operations),
-            'performance_metrics': self.performance_metrics.copy()
+            "total_agents": len(self.agent_records),
+            "active_operations": len(self.active_operations),
+            "performance_metrics": self.performance_metrics.copy(),
         }
-        
+
         # State distribution
         state_counts = {}
         for record in self.agent_records.values():
-            state_counts[record.current_state.value] = state_counts.get(record.current_state.value, 0) + 1
-        
-        stats['agents_by_state'] = state_counts
-        
+            state_counts[record.current_state.value] = (
+                state_counts.get(record.current_state.value, 0) + 1
+            )
+
+        stats["agents_by_state"] = state_counts
+
         # Tier distribution
         tier_counts = {}
         for record in self.agent_records.values():
             tier_counts[record.tier.value] = tier_counts.get(record.tier.value, 0) + 1
-        
-        stats['agents_by_tier'] = tier_counts
-        
+
+        stats["agents_by_tier"] = tier_counts
+
         # Recent activity
         recent_ops = [
-            op for op in self.operation_history 
+            op
+            for op in self.operation_history
             if (time.time() - (op.duration_ms / 1000)) < 3600  # Last hour
         ]
-        stats['recent_operations'] = len(recent_ops)
-        
+        stats["recent_operations"] = len(recent_ops)
+
         return stats
-    
-    async def _create_agent_definition(self, agent_name: str, agent_content: str, 
-                                      tier: ModificationTier, agent_type: str, **kwargs) -> AgentDefinition:
-        """
-        Create an AgentDefinition from lifecycle parameters.
-        
-        WHY: This method bridges the gap between the lifecycle manager's parameters
-        and the AgentManager's expected AgentDefinition model.
-        
-        DESIGN DECISION: Creating a minimal AgentDefinition here because:
-        - The full markdown parsing happens in AgentManager
-        - We only need to provide the essential metadata
-        - This keeps the lifecycle manager focused on orchestration
-        """
-        # Map tier to AgentType
-        type_map = {
-            ModificationTier.USER: AgentType.CUSTOM,
-            ModificationTier.PROJECT: AgentType.PROJECT,
-            ModificationTier.SYSTEM: AgentType.SYSTEM
-        }
-        
-        # Create metadata
-        from claude_mpm.models.agent_definition import AgentMetadata, AgentPermissions
-        metadata = AgentMetadata(
-            type=type_map.get(tier, AgentType.CUSTOM),
-            model_preference=kwargs.get('model_preference', 'claude-3-sonnet'),
-            version="1.0.0",
-            author=kwargs.get('author', 'claude-mpm'),
-            tags=kwargs.get('tags', []),
-            specializations=kwargs.get('specializations', [])
-        )
-        
-        # Create minimal definition
-        definition = AgentDefinition(
-            name=agent_name,
-            title=agent_name.replace('-', ' ').title(),
-            file_path="",  # Will be set by AgentManager
-            metadata=metadata,
-            primary_role=kwargs.get('primary_role', f"{agent_name} agent"),
-            when_to_use={"select": [], "do_not_select": []},
-            capabilities=[],
-            authority=AgentPermissions(),
-            workflows=[],
-            escalation_triggers=[],
-            kpis=[],
-            dependencies=[],
-            tools_commands="",
-            raw_content=agent_content
+
+    async def _create_agent_definition(
+        self,
+        agent_name: str,
+        agent_content: str,
+        tier: ModificationTier,
+        agent_type: str,
+        **kwargs,
+    ) -> AgentDefinition:
+        """Create an AgentDefinition from lifecycle parameters."""
+        from .agent_definition_factory import AgentDefinitionFactory
+
+        factory = AgentDefinitionFactory()
+        return factory.create_agent_definition(
+            agent_name, agent_content, tier, agent_type, **kwargs
         )
-        
-        return definition
-    
+
     async def _run_sync_in_executor(self, func, *args, **kwargs):
         """
         Run a synchronous function in an executor to avoid blocking.
-        
+
         WHY: AgentManager has synchronous methods but AgentLifecycleManager is async.
         This allows us to call sync methods without blocking the event loop.
-        
+
         PERFORMANCE: Uses the default executor which manages a thread pool efficiently.
         """
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(None, func, *args, **kwargs)
-    
-    async def restore_agent(self, agent_name: str, backup_path: Optional[str] = None) -> LifecycleOperationResult:
+
+    async def restore_agent(
+        self, agent_name: str, backup_path: Optional[str] = None
+    ) -> LifecycleOperationResult:
         """Restore agent from backup."""
-        start_time = time.time()
-        
-        try:
-            record = self.agent_records.get(agent_name)
-            if not record:
-                return LifecycleOperationResult(
-                    operation=LifecycleOperation.RESTORE,
-                    agent_name=agent_name,
-                    success=False,
-                    duration_ms=(time.time() - start_time) * 1000,
-                    error_message="Agent record not found"
-                )
-            
-            # Use latest backup if not specified
-            if not backup_path and record.backup_paths:
-                backup_path = record.backup_paths[-1]
-            
-            if not backup_path or not path_ops.validate_exists(backup_path):
-                return LifecycleOperationResult(
-                    operation=LifecycleOperation.RESTORE,
-                    agent_name=agent_name,
-                    success=False,
-                    duration_ms=(time.time() - start_time) * 1000,
-                    error_message="No valid backup found"
-                )
-            
-            # Read backup content
-            backup_content = path_ops.safe_read(backup_path)
-            if not backup_content:
-                return LifecycleOperationResult(
-                    operation=LifecycleOperation.RESTORE,
-                    agent_name=agent_name,
-                    success=False,
-                    duration_ms=(time.time() - start_time) * 1000,
-                    error_message="Failed to read backup content"
-                )
-            
-            # Restore via update operation
-            return await self.update_agent(
-                agent_name=agent_name,
-                agent_content=backup_content,
-                restored_from=backup_path
-            )
-            
-        except Exception as e:
-            return LifecycleOperationResult(
-                operation=LifecycleOperation.RESTORE,
-                agent_name=agent_name,
-                success=False,
-                duration_ms=(time.time() - start_time) * 1000,
-                error_message=str(e)
-            )
+        from .agent_restore_handler import AgentRestoreHandler
+
+        handler = AgentRestoreHandler(self)
+        return await handler.restore_agent(agent_name, backup_path)