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

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 """Async Agent Deployment Service for high-performance parallel operations.
 
 This module provides async versions of agent deployment operations to dramatically
@@ -19,114 +21,116 @@ DESIGN DECISIONS:
 
 import asyncio
 import json
-import logging
 import os
 import time
-from pathlib import Path
-from typing import Dict, Any, List, Optional, Tuple
-import aiofiles
 from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, List, Optional, Tuple
+
+import aiofiles
 
-from claude_mpm.core.logger import get_logger
-from claude_mpm.constants import EnvironmentVars, Paths
 from claude_mpm.config.paths import paths
+from claude_mpm.constants import EnvironmentVars, Paths
 from claude_mpm.core.config import Config
+from claude_mpm.core.logger import get_logger
 
 
 class AsyncAgentDeploymentService:
     """Async service for high-performance agent deployment.
-    
+
     WHY: This async version provides:
     - 50-70% reduction in startup time
     - Parallel agent file discovery and processing
     - Non-blocking I/O for all file operations
     - Efficient batching of operations
     - Seamless integration with existing sync code
-    
+
     PERFORMANCE METRICS:
     - Sync discovery: ~500ms for 10 agents across 3 directories
     - Async discovery: ~150ms for same (70% reduction)
     - Sync JSON parsing: ~200ms for 10 files
     - Async JSON parsing: ~50ms for same (75% reduction)
     """
-    
-    def __init__(self, templates_dir: Optional[Path] = None, 
-                 base_agent_path: Optional[Path] = None,
-                 working_directory: Optional[Path] = None):
+
+    def __init__(
+        self,
+        templates_dir: Optional[Path] = None,
+        base_agent_path: Optional[Path] = None,
+        working_directory: Optional[Path] = None,
+    ):
         """Initialize async agent deployment service.
-        
+
         Args:
             templates_dir: Directory containing agent JSON files
             base_agent_path: Path to base_agent.md file
             working_directory: User's working directory (for project agents)
         """
         self.logger = get_logger(self.__class__.__name__)
-        
+
         # Determine working directory
         if working_directory:
             self.working_directory = Path(working_directory)
-        elif 'CLAUDE_MPM_USER_PWD' in os.environ:
-            self.working_directory = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        elif "CLAUDE_MPM_USER_PWD" in os.environ:
+            self.working_directory = Path(os.environ["CLAUDE_MPM_USER_PWD"])
         else:
             self.working_directory = Path.cwd()
-            
+
         # Set template and base agent paths
         if templates_dir:
             self.templates_dir = Path(templates_dir)
         else:
             self.templates_dir = paths.agents_dir / "templates"
-            
+
         if base_agent_path:
             self.base_agent_path = Path(base_agent_path)
         else:
             self.base_agent_path = paths.agents_dir / "base_agent.json"
-            
+
         # Thread pool for CPU-bound JSON parsing
         self.executor = ThreadPoolExecutor(max_workers=4)
-        
+
         # Performance metrics
         self._metrics = {
-            'async_operations': 0,
-            'parallel_files_processed': 0,
-            'time_saved_ms': 0.0
+            "async_operations": 0,
+            "parallel_files_processed": 0,
+            "time_saved_ms": 0.0,
         }
-    
-    async def discover_agents_async(self, directories: List[Path]) -> Dict[str, List[Path]]:
+
+    async def discover_agents_async(
+        self, directories: List[Path]
+    ) -> Dict[str, List[Path]]:
         """Discover agent files across multiple directories in parallel.
-        
+
         WHY: Parallel directory scanning reduces I/O wait time significantly.
         Each directory scan can take 50-100ms sequentially, but parallel
         scanning completes all directories in the time of the slowest one.
-        
+
         Args:
             directories: List of directories to scan
-            
+
         Returns:
             Dictionary mapping directory paths to lists of agent files
         """
         start_time = time.time()
-        
+
         async def scan_directory(directory: Path) -> Tuple[str, List[Path]]:
             """Scan a single directory for agent files asynchronously."""
             if not directory.exists():
                 return str(directory), []
-                
+
             # Use asyncio to run glob in executor (since Path.glob is blocking)
             loop = asyncio.get_event_loop()
             files = await loop.run_in_executor(
-                self.executor,
-                lambda: list(directory.glob("*.json"))
+                self.executor, lambda: list(directory.glob("*.json"))
             )
-            
+
             self.logger.debug(f"Found {len(files)} agents in {directory}")
             return str(directory), files
-        
+
         # Scan all directories in parallel
         results = await asyncio.gather(
-            *[scan_directory(d) for d in directories],
-            return_exceptions=True
+            *[scan_directory(d) for d in directories], return_exceptions=True
         )
-        
+
         # Process results
         discovered = {}
         for result in results:
@@ -135,92 +139,92 @@ class AsyncAgentDeploymentService:
                 continue
             dir_path, files = result
             discovered[dir_path] = files
-        
+
         elapsed = (time.time() - start_time) * 1000
-        self._metrics['time_saved_ms'] += max(0, (len(directories) * 75) - elapsed)
+        self._metrics["time_saved_ms"] += max(0, (len(directories) * 75) - elapsed)
         self.logger.info(f"Discovered agents in {elapsed:.1f}ms (parallel scan)")
-        
+
         return discovered
-    
-    async def load_agent_files_async(self, file_paths: List[Path]) -> List[Dict[str, Any]]:
+
+    async def load_agent_files_async(
+        self, file_paths: List[Path]
+    ) -> List[Dict[str, Any]]:
         """Load and parse multiple agent files in parallel.
-        
+
         WHY: JSON parsing is CPU-bound but file reading is I/O-bound.
         By separating these operations and parallelizing, we achieve:
         - Non-blocking file reads with aiofiles
         - Parallel JSON parsing in thread pool
         - Batch processing for efficiency
-        
+
         Args:
             file_paths: List of agent file paths to load
-            
+
         Returns:
             List of parsed agent configurations
         """
         start_time = time.time()
-        
+
         async def load_single_file(file_path: Path) -> Optional[Dict[str, Any]]:
             """Load and parse a single agent file asynchronously."""
             try:
                 # Non-blocking file read
-                async with aiofiles.open(file_path, 'r') as f:
+                async with aiofiles.open(file_path, "r") as f:
                     content = await f.read()
-                
+
                 # Parse JSON in thread pool (CPU-bound)
                 loop = asyncio.get_event_loop()
-                data = await loop.run_in_executor(
-                    self.executor,
-                    json.loads,
-                    content
-                )
-                
+                data = await loop.run_in_executor(self.executor, json.loads, content)
+
                 # Add file metadata
-                data['_source_file'] = str(file_path)
-                data['_agent_name'] = file_path.stem
-                
+                data["_source_file"] = str(file_path)
+                data["_agent_name"] = file_path.stem
+
                 return data
-                
+
             except Exception as e:
                 self.logger.error(f"Failed to load {file_path}: {e}")
                 return None
-        
+
         # Load all files in parallel
         agents = await asyncio.gather(
-            *[load_single_file(fp) for fp in file_paths],
-            return_exceptions=False
+            *[load_single_file(fp) for fp in file_paths], return_exceptions=False
         )
-        
+
         # Filter out None values (failed loads)
         valid_agents = [a for a in agents if a is not None]
-        
+
         elapsed = (time.time() - start_time) * 1000
-        self._metrics['parallel_files_processed'] += len(file_paths)
-        self._metrics['async_operations'] += len(file_paths)
-        
+        self._metrics["parallel_files_processed"] += len(file_paths)
+        self._metrics["async_operations"] += len(file_paths)
+
         self.logger.info(
             f"Loaded {len(valid_agents)}/{len(file_paths)} agents "
             f"in {elapsed:.1f}ms (parallel load)"
         )
-        
+
         return valid_agents
-    
-    async def validate_agents_async(self, agents: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+
+    async def validate_agents_async(
+        self, agents: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
         """Validate multiple agents in parallel.
-        
+
         WHY: Agent validation involves checking schemas and constraints.
         Parallel validation reduces time from O(n) to O(1) for the batch.
-        
+
         Args:
             agents: List of agent configurations to validate
-            
+
         Returns:
             List of valid agent configurations
         """
+
         async def validate_single(agent: Dict[str, Any]) -> Optional[Dict[str, Any]]:
             """Validate a single agent configuration."""
             try:
                 # Basic validation (extend as needed)
-                required_fields = ['agent_id', 'instructions']
+                required_fields = ["agent_id", "instructions"]
                 if all(field in agent for field in required_fields):
                     return agent
                 else:
@@ -233,239 +237,281 @@ class AsyncAgentDeploymentService:
             except Exception as e:
                 self.logger.error(f"Validation error: {e}")
                 return None
-        
+
         # Validate all agents in parallel
         validated = await asyncio.gather(
-            *[validate_single(a) for a in agents],
-            return_exceptions=False
+            *[validate_single(a) for a in agents], return_exceptions=False
         )
-        
+
         return [a for a in validated if a is not None]
-    
-    async def deploy_agents_async(self, target_dir: Optional[Path] = None,
-                                  force_rebuild: bool = False,
-                                  config: Optional[Config] = None) -> Dict[str, Any]:
+
+    async def deploy_agents_async(
+        self,
+        target_dir: Optional[Path] = None,
+        force_rebuild: bool = False,
+        config: Optional[Config] = None,
+    ) -> Dict[str, Any]:
         """Deploy agents using async operations for maximum performance.
-        
+
         WHY: This async deployment method provides:
         - Parallel file discovery across all tiers
         - Concurrent agent loading and validation
         - Batch processing for efficiency
         - 50-70% reduction in total deployment time
-        
+
         Args:
             target_dir: Target directory for agents
             force_rebuild: Force rebuild even if agents exist
             config: Optional configuration object
-            
+
         Returns:
             Dictionary with deployment results
         """
         start_time = time.time()
-        
+
         # Load configuration
         if config is None:
             config = Config()
-            
+
         # Get exclusion configuration
-        excluded_agents = config.get('agent_deployment.excluded_agents', [])
-        case_sensitive = config.get('agent_deployment.case_sensitive', False)
-        
+        excluded_agents = config.get("agent_deployment.excluded_agents", [])
+        case_sensitive = config.get("agent_deployment.case_sensitive", False)
+
         results = {
             "deployed": [],
             "errors": [],
             "skipped": [],
             "updated": [],
-            "metrics": {
-                "async_mode": True,
-                "start_time": start_time
-            }
+            "metrics": {"async_mode": True, "start_time": start_time},
         }
-        
+
         try:
             # Determine target directory
             if not target_dir:
                 agents_dir = self.working_directory / ".claude" / "agents"
             else:
                 agents_dir = self._resolve_agents_dir(target_dir)
-                
-            agents_dir.mkdir(parents=True, exist_ok=True)
-            
+
+            # Create directory asynchronously
+            await self._create_directory_async(agents_dir)
+
             # Step 1: Discover agent files in parallel
             search_dirs = [
                 self.working_directory / ".claude-mpm" / "agents",  # PROJECT
                 Path.home() / ".claude-mpm" / "agents",  # USER
-                self.templates_dir  # SYSTEM
+                self.templates_dir,  # SYSTEM
             ]
-            
+
             discovered = await self.discover_agents_async(
                 [d for d in search_dirs if d.exists()]
             )
-            
+
             # Step 2: Load all agent files in parallel
             all_files = []
             for files in discovered.values():
                 all_files.extend(files)
-                
+
             if not all_files:
                 self.logger.warning("No agent files found")
                 return results
-                
+
             agents = await self.load_agent_files_async(all_files)
-            
+
             # Step 3: Filter excluded agents
             filtered_agents = self._filter_excluded_agents(
                 agents, excluded_agents, case_sensitive
             )
-            
+
             # Step 4: Validate agents in parallel
             valid_agents = await self.validate_agents_async(filtered_agents)
-            
-            # Step 5: Deploy valid agents (this part remains sync for file writes)
-            # Could be made async with aiofiles if needed
-            for agent in valid_agents:
-                agent_name = agent.get('_agent_name', 'unknown')
-                target_file = agents_dir / f"{agent_name}.md"
-                
-                # Build markdown content (sync operation - could be parallelized)
-                content = self._build_agent_markdown_sync(agent)
-                
-                # Write file (could use aiofiles for true async)
-                target_file.write_text(content)
-                
-                results["deployed"].append(agent_name)
-                
+
+            # Step 5: Deploy valid agents using async file operations
+            await self._deploy_agents_async(valid_agents, agents_dir, results)
+
         except Exception as e:
             self.logger.error(f"Async deployment failed: {e}")
             results["errors"].append(str(e))
-            
+
         # Calculate metrics
         elapsed = (time.time() - start_time) * 1000
         results["metrics"]["duration_ms"] = elapsed
         results["metrics"]["async_stats"] = self._metrics.copy()
-        
+
         self.logger.info(
             f"Async deployment completed in {elapsed:.1f}ms "
             f"({len(results['deployed'])} deployed, "
             f"{len(results['errors'])} errors)"
         )
-        
+
         return results
-    
+
     def _resolve_agents_dir(self, target_dir: Path) -> Path:
         """Resolve the agents directory from target directory."""
         target_dir = Path(target_dir)
-        
+
         if target_dir.name == "agents":
             return target_dir
         elif target_dir.name in [".claude-mpm", ".claude"]:
             return target_dir / "agents"
         else:
             return target_dir / ".claude" / "agents"
-    
-    def _filter_excluded_agents(self, agents: List[Dict[str, Any]],
-                                excluded_agents: List[str],
-                                case_sensitive: bool) -> List[Dict[str, Any]]:
+
+    def _filter_excluded_agents(
+        self,
+        agents: List[Dict[str, Any]],
+        excluded_agents: List[str],
+        case_sensitive: bool,
+    ) -> List[Dict[str, Any]]:
         """Filter out excluded agents from the list."""
         if not excluded_agents:
             return agents
-            
+
         # Normalize exclusion list
         if not case_sensitive:
             excluded_agents = [a.lower() for a in excluded_agents]
-            
+
         filtered = []
         for agent in agents:
-            agent_name = agent.get('_agent_name', '')
+            agent_name = agent.get("_agent_name", "")
             compare_name = agent_name if case_sensitive else agent_name.lower()
-            
+
             if compare_name not in excluded_agents:
                 filtered.append(agent)
             else:
                 self.logger.debug(f"Excluding agent: {agent_name}")
-                
+
         return filtered
-    
+
+    async def _create_directory_async(self, directory: Path) -> None:
+        """Create directory asynchronously using thread pool."""
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            self.executor, lambda: directory.mkdir(parents=True, exist_ok=True)
+        )
+
+    async def _deploy_agents_async(
+        self, agents: List[Dict[str, Any]], agents_dir: Path, results: Dict[str, Any]
+    ) -> None:
+        """Deploy agents using async file operations."""
+
+        async def deploy_single_agent(agent: Dict[str, Any]) -> Optional[str]:
+            """Deploy a single agent asynchronously."""
+            try:
+                agent_name = agent.get("_agent_name", "unknown")
+                target_file = agents_dir / f"{agent_name}.md"
+
+                # Build markdown content in thread pool (CPU-bound)
+                loop = asyncio.get_event_loop()
+                content = await loop.run_in_executor(
+                    self.executor, self._build_agent_markdown_sync, agent
+                )
+
+                # Write file asynchronously
+                async with aiofiles.open(target_file, "w") as f:
+                    await f.write(content)
+
+                return agent_name
+
+            except Exception as e:
+                self.logger.error(
+                    f"Failed to deploy agent {agent.get('_agent_name', 'unknown')}: {e}"
+                )
+                return None
+
+        # Deploy all agents in parallel
+        deployed_names = await asyncio.gather(
+            *[deploy_single_agent(agent) for agent in agents], return_exceptions=False
+        )
+
+        # Update results with successful deployments
+        for name in deployed_names:
+            if name is not None:
+                results["deployed"].append(name)
+
     def _build_agent_markdown_sync(self, agent_data: Dict[str, Any]) -> str:
         """Build agent markdown content matching the synchronous deployment format."""
         from datetime import datetime
-        
+
         # Extract agent info from the loaded JSON data
-        agent_name = agent_data.get('_agent_name', 'unknown')
-        
+        agent_name = agent_data.get("_agent_name", "unknown")
+
         # Extract proper agent_id from template data (not filename)
-        agent_id = agent_data.get('agent_id', agent_name)
-        
+        agent_id = agent_data.get("agent_id", agent_name)
+
         # Handle both 'agent_version' (new format) and 'version' (old format)
-        agent_version = self._parse_version(agent_data.get('agent_version') or agent_data.get('version', '1.0.0'))
+        agent_version = self._parse_version(
+            agent_data.get("agent_version") or agent_data.get("version", "1.0.0")
+        )
         base_version = (0, 1, 0)  # Default base version for async deployment
-        
+
         # Format version string as semantic version
         version_string = self._format_version_display(agent_version)
-        
+
         # Extract metadata using the same logic as synchronous deployment
         # Check new format first (metadata.description), then old format
         description = (
-            agent_data.get('metadata', {}).get('description') or
-            agent_data.get('configuration_fields', {}).get('description') or
-            agent_data.get('description') or
-            'Agent for specialized tasks'
+            agent_data.get("metadata", {}).get("description")
+            or agent_data.get("configuration_fields", {}).get("description")
+            or agent_data.get("description")
+            or "Agent for specialized tasks"
         )
-        
+
         # Get tags from new format (metadata.tags) or old format
         tags = (
-            agent_data.get('metadata', {}).get('tags') or
-            agent_data.get('configuration_fields', {}).get('tags') or
-            agent_data.get('tags') or
-            [agent_id, 'mpm-framework']
+            agent_data.get("metadata", {}).get("tags")
+            or agent_data.get("configuration_fields", {}).get("tags")
+            or agent_data.get("tags")
+            or [agent_id, "mpm-framework"]
         )
-        
+
         # Get tools from capabilities.tools in new format
         tools = (
-            agent_data.get('capabilities', {}).get('tools') or
-            agent_data.get('configuration_fields', {}).get('tools') or
-            ["Read", "Write", "Edit", "Grep", "Glob", "LS"]  # Default fallback
+            agent_data.get("capabilities", {}).get("tools")
+            or agent_data.get("configuration_fields", {}).get("tools")
+            or ["Read", "Write", "Edit", "Grep", "Glob", "LS"]  # Default fallback
         )
-        
+
         # Get model from capabilities.model in new format
         model = (
-            agent_data.get('capabilities', {}).get('model') or
-            agent_data.get('configuration_fields', {}).get('model') or
-            "sonnet"  # Default fallback
+            agent_data.get("capabilities", {}).get("model")
+            or agent_data.get("configuration_fields", {}).get("model")
+            or "sonnet"  # Default fallback
         )
-        
+
         # Simplify model name for Claude Code
         model_map = {
-            'claude-4-sonnet-20250514': 'sonnet',
-            'claude-sonnet-4-20250514': 'sonnet',
-            'claude-opus-4-20250514': 'opus',
-            'claude-3-opus-20240229': 'opus',
-            'claude-3-haiku-20240307': 'haiku',
-            'claude-3.5-sonnet': 'sonnet',
-            'claude-3-sonnet': 'sonnet'
+            "claude-4-sonnet-20250514": "sonnet",
+            "claude-sonnet-4-20250514": "sonnet",
+            "claude-opus-4-20250514": "opus",
+            "claude-3-opus-20240229": "opus",
+            "claude-3-haiku-20240307": "haiku",
+            "claude-3.5-sonnet": "sonnet",
+            "claude-3-sonnet": "sonnet",
         }
         # Better fallback: extract the model type (opus/sonnet/haiku) from the string
         if model not in model_map:
-            if 'opus' in model.lower():
-                model = 'opus'
-            elif 'sonnet' in model.lower():
-                model = 'sonnet'
-            elif 'haiku' in model.lower():
-                model = 'haiku'
+            if "opus" in model.lower():
+                model = "opus"
+            elif "sonnet" in model.lower():
+                model = "sonnet"
+            elif "haiku" in model.lower():
+                model = "haiku"
             else:
                 # Last resort: try to extract from hyphenated format
-                model = model_map.get(model, model.split('-')[-1] if '-' in model else model)
+                model = model_map.get(
+                    model, model.split("-")[-1] if "-" in model else model
+                )
         else:
             model = model_map[model]
-        
+
         # Convert tools list to comma-separated string for Claude Code compatibility
         # IMPORTANT: No spaces after commas - Claude Code requires exact format
-        tools_str = ','.join(tools) if isinstance(tools, list) else str(tools)
-        
+        tools_str = ",".join(tools) if isinstance(tools, list) else str(tools)
+
         # Convert agent_id to Claude Code compatible name (replace underscores with hyphens)
         # Claude Code requires name to match pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
-        claude_code_name = agent_id.replace('_', '-').lower()
-        
+        claude_code_name = agent_id.replace("_", "-").lower()
+
         # Build frontmatter with only the fields Claude Code uses
         frontmatter_lines = [
             "---",
@@ -475,84 +521,82 @@ class AsyncAgentDeploymentService:
             f"base_version: {self._format_version_display(base_version)}",
             f"author: claude-mpm",  # Identify as system agent for deployment
             f"tools: {tools_str}",
-            f"model: {model}"
+            f"model: {model}",
         ]
-        
+
         # Add optional fields if present
         # Check for color in metadata section (new format) or root (old format)
-        color = (
-            agent_data.get('metadata', {}).get('color') or
-            agent_data.get('color')
-        )
+        color = agent_data.get("metadata", {}).get("color") or agent_data.get("color")
         if color:
             frontmatter_lines.append(f"color: {color}")
-        
+
         frontmatter_lines.append("---")
         frontmatter_lines.append("")
         frontmatter_lines.append("")
-        
-        frontmatter = '\n'.join(frontmatter_lines)
-        
+
+        frontmatter = "\n".join(frontmatter_lines)
+
         # Get the main content (instructions)
         # Check multiple possible locations for instructions
         content = (
-            agent_data.get('instructions') or
-            agent_data.get('narrative_fields', {}).get('instructions') or
-            agent_data.get('content') or
-            f"You are the {agent_id} agent. Perform tasks related to {agent_data.get('description', 'your specialization')}."
+            agent_data.get("instructions")
+            or agent_data.get("narrative_fields", {}).get("instructions")
+            or agent_data.get("content")
+            or f"You are the {agent_id} agent. Perform tasks related to {agent_data.get('description', 'your specialization')}."
         )
-        
+
         return frontmatter + content
-    
+
     def _parse_version(self, version_value: Any) -> tuple:
         """
         Parse version from various formats to semantic version tuple.
-        
+
         Handles:
         - Integer values: 5 -> (0, 5, 0)
         - String integers: "5" -> (0, 5, 0)
         - Semantic versions: "2.1.0" -> (2, 1, 0)
         - Invalid formats: returns (0, 0, 0)
-        
+
         Args:
             version_value: Version in various formats
-            
+
         Returns:
             Tuple of (major, minor, patch) for comparison
         """
         if isinstance(version_value, int):
             # Legacy integer version - treat as minor version
             return (0, version_value, 0)
-            
+
         if isinstance(version_value, str):
             # Try to parse as simple integer
             if version_value.isdigit():
                 return (0, int(version_value), 0)
-            
+
             # Try to parse semantic version (e.g., "2.1.0" or "v2.1.0")
             import re
-            sem_ver_match = re.match(r'^v?(\d+)\.(\d+)\.(\d+)', version_value)
+
+            sem_ver_match = re.match(r"^v?(\d+)\.(\d+)\.(\d+)", version_value)
             if sem_ver_match:
                 major = int(sem_ver_match.group(1))
                 minor = int(sem_ver_match.group(2))
                 patch = int(sem_ver_match.group(3))
                 return (major, minor, patch)
-            
+
             # Try to extract first number from string as minor version
-            num_match = re.search(r'(\d+)', version_value)
+            num_match = re.search(r"(\d+)", version_value)
             if num_match:
                 return (0, int(num_match.group(1)), 0)
-        
+
         # Default to 0.0.0 for invalid formats
         return (0, 0, 0)
-    
+
     def _format_version_display(self, version_tuple: tuple) -> str:
         """
         Format version tuple for display.
-        
+
         Args:
             version_tuple: Tuple of (major, minor, patch)
-            
+
         Returns:
             Formatted version string
         """
@@ -562,61 +606,81 @@ class AsyncAgentDeploymentService:
         else:
             # Fallback for legacy format
             return str(version_tuple)
-    
+
     async def cleanup(self):
         """Clean up resources."""
         self.executor.shutdown(wait=False)
 
 
 # Convenience function to run async deployment from sync code
-def deploy_agents_async_wrapper(templates_dir: Optional[Path] = None,
-                               base_agent_path: Optional[Path] = None,
-                               working_directory: Optional[Path] = None,
-                               target_dir: Optional[Path] = None,
-                               force_rebuild: bool = False,
-                               config: Optional[Config] = None) -> Dict[str, Any]:
+def deploy_agents_async_wrapper(
+    templates_dir: Optional[Path] = None,
+    base_agent_path: Optional[Path] = None,
+    working_directory: Optional[Path] = None,
+    target_dir: Optional[Path] = None,
+    force_rebuild: bool = False,
+    config: Optional[Config] = None,
+) -> Dict[str, Any]:
     """Wrapper to run async deployment from synchronous code.
-    
+
     WHY: This wrapper allows the async deployment to be called from
     existing synchronous code without requiring a full async refactor.
     It manages the event loop and ensures proper cleanup.
-    
+
     Args:
         Same as AsyncAgentDeploymentService.deploy_agents_async()
-        
+
     Returns:
         Deployment results dictionary
     """
+
     async def run_deployment():
         service = AsyncAgentDeploymentService(
             templates_dir=templates_dir,
             base_agent_path=base_agent_path,
-            working_directory=working_directory
+            working_directory=working_directory,
         )
-        
+
         try:
             results = await service.deploy_agents_async(
-                target_dir=target_dir,
-                force_rebuild=force_rebuild,
-                config=config
+                target_dir=target_dir, force_rebuild=force_rebuild, config=config
             )
             return results
         finally:
             await service.cleanup()
-    
-    # Run in event loop
+
+    # Run in event loop with proper handling
     try:
-        # Try to get existing event loop
-        loop = asyncio.get_event_loop()
-        if loop.is_running():
-            # If loop is already running, create a new task
+        # Check if we're already in an async context
+        try:
+            loop = asyncio.get_running_loop()
+            # We're in an async context, run in thread pool to avoid blocking
             import concurrent.futures
+
             with concurrent.futures.ThreadPoolExecutor() as executor:
                 future = executor.submit(asyncio.run, run_deployment())
                 return future.result()
-        else:
-            # Run in existing loop
-            return loop.run_until_complete(run_deployment())
-    except RuntimeError:
-        # No event loop, create new one
-        return asyncio.run(run_deployment())
+        except RuntimeError:
+            # No running loop, safe to create new one
+            return asyncio.run(run_deployment())
+    except Exception as e:
+        # Fallback to synchronous deployment if async fails
+        from claude_mpm.core.logger import get_logger
+
+        logger = get_logger("AsyncAgentDeploymentWrapper")
+        logger.warning(f"Async deployment failed, falling back to sync: {e}")
+
+        # Import and use synchronous deployment as fallback
+        from .agent_deployment import AgentDeploymentService
+
+        sync_service = AgentDeploymentService(
+            templates_dir=templates_dir,
+            base_agent_path=base_agent_path,
+            working_directory=working_directory,
+        )
+        return sync_service.deploy_agents(
+            target_dir=target_dir,
+            force_rebuild=force_rebuild,
+            config=config,
+            use_async=False,  # Explicitly disable async to avoid recursion
+        )