anvil-dev-framework 0.1.6

package/global/lib/coordination_service.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+coordination_service.py - Agent coordination and conflict detection for HUD (ANV-106-110)
+
+Tracks file locks between agents, detects conflicts when multiple agents edit
+the same file, and provides branch age information for trunk-based development.
+
+Usage:
+    from coordination_service import CoordinationService
+
+    service = CoordinationService()
+    service.update_from_registry(agents)
+    conflicts = service.get_conflicts()
+"""
+
+import subprocess
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, TypedDict
+
+
+class FileLock(TypedDict, total=False):
+    """Lock on a file by an agent."""
+    agent_id: str           # Agent holding the lock
+    agent_display: str      # Short display name for agent
+    file_path: str          # Full path to file
+    pattern: str            # Directory pattern (e.g., "src/auth/*")
+    since: str              # ISO timestamp when lock acquired
+    operation: str          # Type of operation (Edit, Write, etc.)
+    duration_seconds: int   # How long the lock has been held
+
+
+class FileConflict(TypedDict, total=False):
+    """Conflict when multiple agents edit the same file."""
+    file_path: str          # Full path to conflicting file
+    pattern: str            # Directory pattern
+    agents: List[str]       # Agent IDs involved in conflict
+    detected: str           # ISO timestamp when detected
+    suggestion: str         # Suggested action
+
+
+class BranchInfo(TypedDict, total=False):
+    """Branch age information for an agent."""
+    agent_id: str
+    branch: str             # Branch name
+    age_seconds: int        # Age of branch in seconds
+    age_display: str        # Human-readable age (e.g., "2h 15m")
+    is_stale: bool          # True if branch age exceeds threshold
+
+
+class CoordinationData(TypedDict, total=False):
+    """Aggregated coordination data."""
+    file_locks: Dict[str, FileLock]    # pattern -> lock
+    conflicts: List[FileConflict]       # List of conflicts
+    branches: Dict[str, BranchInfo]     # agent_id -> branch info
+    last_update: float                  # Timestamp
+
+
+# Thresholds
+STALE_BRANCH_THRESHOLD = 4 * 60 * 60  # 4 hours in seconds
+
+
+class CoordinationService:
+    """Service for tracking agent coordination and conflicts (ANV-106-110)."""
+
+    def __init__(self):
+        """Initialize the coordination service."""
+        self._locks: Dict[str, FileLock] = {}  # pattern -> lock
+        self._lock_timestamps: Dict[str, float] = {}  # pattern -> timestamp
+        self._conflicts: List[FileConflict] = []
+        self._branches: Dict[str, BranchInfo] = {}  # agent_id -> branch
+        self._last_update = 0.0
+
+    def update_from_registry(self, agents: Dict[str, Any]) -> CoordinationData:
+        """Update coordination data from agent registry.
+
+        Args:
+            agents: Dictionary of agent_id -> agent data
+
+        Returns:
+            CoordinationData with all coordination information
+        """
+        now = time.time()
+        new_locks: Dict[str, FileLock] = {}
+        agent_files: Dict[str, Set[str]] = {}  # agent_id -> set of file patterns
+
+        for agent_id, agent in agents.items():
+            project = agent.get("project", "")
+            display_id = agent_id[:12] if len(agent_id) > 12 else agent_id
+
+            # Track files from recent tool calls
+            recent_tools = agent.get("recentTools", [])
+            if not recent_tools:
+                # Try to get from detailed state
+                detailed = agent.get("detailed", {})
+                recent_tools = detailed.get("recentTools", [])
+
+            files_touched: Set[str] = set()
+            for tool in recent_tools:
+                tool_name = tool.get("name", "")
+                # Only track write operations
+                if tool_name in ("Edit", "Write", "MultiEdit"):
+                    file_path = tool.get("args", {}).get("file_path", "")
+                    if file_path:
+                        # Get directory pattern
+                        pattern = self._get_pattern(file_path, project)
+                        files_touched.add(pattern)
+
+                        # Create or update lock
+                        if pattern not in new_locks:
+                            # Check if we had this lock before
+                            since = self._lock_timestamps.get(pattern, now)
+                            self._lock_timestamps[pattern] = since
+
+                            new_locks[pattern] = {
+                                "agent_id": agent_id,
+                                "agent_display": display_id,
+                                "file_path": file_path,
+                                "pattern": pattern,
+                                "since": datetime.fromtimestamp(since, timezone.utc).isoformat(),
+                                "operation": tool_name,
+                                "duration_seconds": int(now - since),
+                            }
+
+            agent_files[agent_id] = files_touched
+
+            # Get branch info
+            branch_info = self._get_branch_info(agent_id, project)
+            if branch_info:
+                self._branches[agent_id] = branch_info
+
+        # Update locks
+        self._locks = new_locks
+
+        # Detect conflicts (same pattern touched by multiple agents)
+        self._conflicts = []
+        pattern_agents: Dict[str, List[str]] = {}  # pattern -> [agent_ids]
+
+        for agent_id, patterns in agent_files.items():
+            for pattern in patterns:
+                if pattern not in pattern_agents:
+                    pattern_agents[pattern] = []
+                pattern_agents[pattern].append(agent_id)
+
+        # Find patterns with multiple agents
+        for pattern, agent_ids in pattern_agents.items():
+            if len(agent_ids) > 1:
+                self._conflicts.append({
+                    "file_path": pattern,
+                    "pattern": pattern,
+                    "agents": agent_ids,
+                    "detected": datetime.now(timezone.utc).isoformat(),
+                    "suggestion": "Coordinate via /handoff or stagger work",
+                })
+
+        self._last_update = now
+
+        return self.get_data()
+
+    def get_data(self) -> CoordinationData:
+        """Get current coordination data."""
+        return {
+            "file_locks": self._locks,
+            "conflicts": self._conflicts,
+            "branches": self._branches,
+            "last_update": self._last_update,
+        }
+
+    def get_locks(self) -> Dict[str, FileLock]:
+        """Get current file locks."""
+        return self._locks
+
+    def get_conflicts(self) -> List[FileConflict]:
+        """Get current conflicts."""
+        return self._conflicts
+
+    def get_branches(self) -> Dict[str, BranchInfo]:
+        """Get branch information."""
+        return self._branches
+
+    def _get_pattern(self, file_path: str, project: str) -> str:
+        """Get directory pattern from file path.
+
+        Converts full path to a pattern like "src/auth/*"
+        """
+        try:
+            path = Path(file_path)
+            if project:
+                try:
+                    path = path.relative_to(project)
+                except ValueError:
+                    pass
+
+            # Get parent directory
+            parent = path.parent
+            return str(parent) + "/*" if str(parent) != "." else str(path)
+        except Exception:
+            return file_path
+
+    def _get_branch_info(self, agent_id: str, project: str) -> Optional[BranchInfo]:
+        """Get branch age information for an agent's project."""
+        if not project or not Path(project).exists():
+            return None
+
+        try:
+            # Get current branch
+            result = subprocess.run(
+                ["git", "branch", "--show-current"],
+                cwd=project,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            branch = result.stdout.strip()
+            if not branch:
+                return None
+
+            # Get branch creation/diverge time (commits since main)
+            result = subprocess.run(
+                ["git", "log", "main.." + branch, "--format=%ci", "--reverse"],
+                cwd=project,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+
+            age_seconds = 0
+            if result.stdout.strip():
+                # Get first commit time
+                first_commit = result.stdout.strip().split("\n")[0]
+                try:
+                    # Parse git date format: "2024-01-15 10:30:00 +0000"
+                    # Split off timezone, replace first space with T
+                    parts = first_commit.rsplit(" ", 1)  # Split off timezone
+                    if len(parts) == 2:
+                        dt_str, tz_str = parts
+                        # dt_str is "2024-01-15 10:30:00", tz_str is "+0000"
+                        iso_str = dt_str.replace(" ", "T") + tz_str.replace(":", "")
+                        commit_time = datetime.fromisoformat(iso_str)
+                        age_seconds = int((datetime.now(timezone.utc) - commit_time.astimezone(timezone.utc)).total_seconds())
+                except Exception:
+                    pass
+
+            # If no divergence from main, use branch checkout time instead
+            if age_seconds == 0:
+                # Fallback: use reflog
+                result = subprocess.run(
+                    ["git", "reflog", "show", "--format=%ci", "-1", branch],
+                    cwd=project,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.stdout.strip():
+                    try:
+                        # Parse git date format: "2024-01-15 10:30:00 +0000"
+                        reflog_date = result.stdout.strip()
+                        parts = reflog_date.rsplit(" ", 1)  # Split off timezone
+                        if len(parts) == 2:
+                            dt_str, tz_str = parts
+                            iso_str = dt_str.replace(" ", "T") + tz_str.replace(":", "")
+                            checkout_time = datetime.fromisoformat(iso_str)
+                            age_seconds = int((datetime.now(timezone.utc) - checkout_time.astimezone(timezone.utc)).total_seconds())
+                    except Exception:
+                        pass
+
+            # Format age
+            if age_seconds < 60:
+                age_display = f"{age_seconds}s"
+            elif age_seconds < 3600:
+                age_display = f"{age_seconds // 60}m"
+            else:
+                hours = age_seconds // 3600
+                mins = (age_seconds % 3600) // 60
+                age_display = f"{hours}h {mins}m"
+
+            return {
+                "agent_id": agent_id,
+                "branch": branch,
+                "age_seconds": age_seconds,
+                "age_display": age_display,
+                "is_stale": age_seconds > STALE_BRANCH_THRESHOLD,
+            }
+
+        except Exception:
+            return None
+
+    def clear(self) -> None:
+        """Clear all coordination data."""
+        self._locks.clear()
+        self._lock_timestamps.clear()
+        self._conflicts.clear()
+        self._branches.clear()
+
+
+# Singleton instance
+_service: Optional[CoordinationService] = None
+
+
+def get_coordination_service() -> CoordinationService:
+    """Get singleton service instance."""
+    global _service
+    if _service is None:
+        _service = CoordinationService()
+    return _service
+
+
+if __name__ == "__main__":
+    # Simple test
+    service = CoordinationService()
+
+    # Simulate two agents editing same file
+    test_agents = {
+        "agent-1": {
+            "project": "/tmp/test-project",
+            "recentTools": [
+                {"name": "Edit", "args": {"file_path": "/tmp/test-project/src/auth/login.ts"}},
+            ],
+        },
+        "agent-2": {
+            "project": "/tmp/test-project",
+            "recentTools": [
+                {"name": "Edit", "args": {"file_path": "/tmp/test-project/src/auth/logout.ts"}},
+            ],
+        },
+    }
+
+    data = service.update_from_registry(test_agents)
+    print("Locks:", data["file_locks"])
+    print("Conflicts:", data["conflicts"])