anvil-dev-framework 0.1.7 → 0.1.9

package/global/lib/ralph_events.py

@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""
+ralph_events.py - Ralph Event Detection and Emission (ANV-299)
+
+Detects state changes in Ralph sessions and emits structured events
+for the notification system.
+
+Usage:
+    python3 ralph_events.py --state .claude/ralph-state.json --emit
+    python3 ralph_events.py --test subtask_complete
+    python3 ralph_events.py --list
+"""
+
+import json
+import os
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import uuid
+import hashlib
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+DEFAULT_STATE_FILE = ".claude/ralph-state.json"
+DEFAULT_EVENTS_DIR = os.path.expanduser("~/.anvil/events")
+DEBOUNCE_STATE_FILE = os.path.expanduser("~/.anvil/events/.debounce-state.json")
+
+
+# =============================================================================
+# Event Types
+# =============================================================================
+
+class RalphEventType(str, Enum):
+    SESSION_STARTED = "session_started"
+    ITERATION_COMPLETE = "iteration_complete"
+    SUBTASK_COMPLETE = "subtask_complete"
+    SESSION_COMPLETE = "session_complete"
+    ERROR_OCCURRED = "error_occurred"
+    CHECKPOINT_TRIGGERED = "checkpoint_triggered"
+    CIRCUIT_BREAKER = "circuit_breaker"
+    MANUAL_STOP = "manual_stop"
+
+
+# =============================================================================
+# Event Data Classes
+# =============================================================================
+
+@dataclass
+class EventProgress:
+    completed: int = 0
+    total: int = 0
+    percent: float = 0.0
+
+
+@dataclass
+class LinearInfo:
+    parent_issue: Optional[str] = None
+    subtask: Optional[str] = None
+    url: Optional[str] = None
+
+
+@dataclass
+class RalphEvent:
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    event_type: str = ""
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    session_id: str = ""
+    task_name: str = ""
+    iteration: int = 0
+    progress: EventProgress = field(default_factory=EventProgress)
+    payload: Dict[str, Any] = field(default_factory=dict)
+    linear: Optional[LinearInfo] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "timestamp": self.timestamp,
+            "session_id": self.session_id,
+            "task_name": self.task_name,
+            "iteration": self.iteration,
+            "progress": asdict(self.progress),
+            "payload": self.payload,
+        }
+        if self.linear:
+            result["linear"] = asdict(self.linear)
+        return result
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+
+# =============================================================================
+# State Snapshot for Change Detection
+# =============================================================================
+
+@dataclass
+class StateSnapshot:
+    iteration: int = 0
+    status: str = ""
+    completed_count: int = 0
+    todo_count: int = 0
+    subtask_statuses: Dict[str, str] = field(default_factory=dict)
+    checkpoint_active: bool = False
+    no_change_count: int = 0
+    state_hash: str = ""
+
+    @classmethod
+    def from_state_file(cls, state_path: str) -> Optional["StateSnapshot"]:
+        if not Path(state_path).exists():
+            return None
+        try:
+            with open(state_path) as f:
+                data = json.load(f)
+            subtask_statuses = {}
+            linear_int = data.get("linear_integration", {})
+            if linear_int and linear_int.get("enabled"):
+                for subtask in linear_int.get("subtasks", []):
+                    subtask_statuses[subtask["identifier"]] = subtask.get("status", "todo")
+            state_hash = hashlib.md5(json.dumps(data, sort_keys=True).encode()).hexdigest()
+            return cls(
+                iteration=data.get("iteration", 0),
+                status=data.get("status", "unknown"),
+                completed_count=len(data.get("completed_items", [])),
+                todo_count=len(data.get("todo_items", [])),
+                subtask_statuses=subtask_statuses,
+                checkpoint_active=data.get("context_checkpoint", {}).get("active", False),
+                no_change_count=data.get("no_change_count", 0),
+                state_hash=state_hash,
+            )
+        except (json.JSONDecodeError, KeyError, TypeError):
+            return None
+
+
+# =============================================================================
+# Debounce State
+# =============================================================================
+
+@dataclass
+class DebounceState:
+    last_event_time: float = 0.0
+    pending_events: List[Dict[str, Any]] = field(default_factory=list)
+    last_state_hash: str = ""
+    last_snapshot: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def load(cls) -> "DebounceState":
+        if not Path(DEBOUNCE_STATE_FILE).exists():
+            return cls()
+        try:
+            with open(DEBOUNCE_STATE_FILE) as f:
+                data = json.load(f)
+            return cls(
+                last_event_time=data.get("last_event_time", 0.0),
+                pending_events=data.get("pending_events", []),
+                last_state_hash=data.get("last_state_hash", ""),
+                last_snapshot=data.get("last_snapshot"),
+            )
+        except (json.JSONDecodeError, KeyError):
+            return cls()
+
+    def save(self) -> None:
+        Path(DEBOUNCE_STATE_FILE).parent.mkdir(parents=True, exist_ok=True)
+        with open(DEBOUNCE_STATE_FILE, "w") as f:
+            json.dump({
+                "last_event_time": self.last_event_time,
+                "pending_events": self.pending_events,
+                "last_state_hash": self.last_state_hash,
+                "last_snapshot": self.last_snapshot,
+            }, f, indent=2)
+
+
+# =============================================================================
+# Event Detection
+# =============================================================================
+
+class RalphEventDetector:
+    def __init__(self, state_path: str = DEFAULT_STATE_FILE):
+        self.state_path = state_path
+        self.debounce = DebounceState.load()
+
+    def detect_changes(self) -> List[RalphEvent]:
+        current = StateSnapshot.from_state_file(self.state_path)
+        if not current:
+            return []
+        previous = None
+        if self.debounce.last_snapshot:
+            previous = StateSnapshot(**self.debounce.last_snapshot)
+        events = []
+        with open(self.state_path) as f:
+            state_data = json.load(f)
+
+        # Session start
+        if previous is None:
+            events.append(self._create_event(RalphEventType.SESSION_STARTED, state_data, current))
+        # Iteration complete
+        elif current.iteration > previous.iteration:
+            events.append(self._create_event(RalphEventType.ITERATION_COMPLETE, state_data, current))
+        # Subtask completions
+        if previous:
+            for identifier, status in current.subtask_statuses.items():
+                prev_status = previous.subtask_statuses.get(identifier, "todo")
+                if status == "completed" and prev_status != "completed":
+                    events.append(self._create_subtask_event(state_data, current, identifier))
+        # Session completion
+        if previous and current.status != previous.status:
+            if current.status in ("completed", "max_iterations", "circuit_breaker", "fatal_error", "stopped"):
+                events.append(self._create_session_complete_event(state_data, current))
+        # Checkpoint
+        if current.checkpoint_active and (not previous or not previous.checkpoint_active):
+            events.append(self._create_event(RalphEventType.CHECKPOINT_TRIGGERED, state_data, current))
+        # Circuit breaker
+        if current.no_change_count >= 3 and (not previous or previous.no_change_count < 3):
+            events.append(self._create_event(RalphEventType.CIRCUIT_BREAKER, state_data, current))
+
+        self.debounce.last_state_hash = current.state_hash
+        self.debounce.last_snapshot = asdict(current)
+        self.debounce.save()
+        return events
+
+    def _get_session_id(self, state_data: Dict) -> str:
+        started_at = state_data.get("started_at", "")
+        if started_at:
+            return hashlib.md5(started_at.encode()).hexdigest()[:12]
+        return str(uuid.uuid4())[:12]
+
+    def _get_progress(self, state_data: Dict, current: StateSnapshot) -> EventProgress:
+        total = current.completed_count + current.todo_count
+        percent = (current.completed_count / total * 100) if total > 0 else 0.0
+        return EventProgress(completed=current.completed_count, total=total, percent=round(percent, 1))
+
+    def _get_linear_info(self, state_data: Dict, subtask_id: Optional[str] = None) -> Optional[LinearInfo]:
+        linear = state_data.get("linear_integration", {})
+        if not linear or not linear.get("enabled"):
+            return None
+        parent = linear.get("parent_issue", "")
+        url = f"https://linear.app/anvil/issue/{parent}" if parent else None
+        return LinearInfo(parent_issue=parent, subtask=subtask_id, url=url)
+
+    def _create_event(self, event_type: RalphEventType, state_data: Dict, current: StateSnapshot) -> RalphEvent:
+        return RalphEvent(
+            event_type=event_type.value,
+            session_id=self._get_session_id(state_data),
+            task_name=state_data.get("task_name", "Unknown"),
+            iteration=current.iteration,
+            progress=self._get_progress(state_data, current),
+            linear=self._get_linear_info(state_data),
+        )
+
+    def _create_subtask_event(self, state_data: Dict, current: StateSnapshot, identifier: str) -> RalphEvent:
+        linear = state_data.get("linear_integration", {})
+        subtask_title = ""
+        for subtask in linear.get("subtasks", []):
+            if subtask["identifier"] == identifier:
+                subtask_title = subtask.get("title", "")
+                break
+        return RalphEvent(
+            event_type=RalphEventType.SUBTASK_COMPLETE.value,
+            session_id=self._get_session_id(state_data),
+            task_name=state_data.get("task_name", "Unknown"),
+            iteration=current.iteration,
+            progress=self._get_progress(state_data, current),
+            payload={"subtask_identifier": identifier, "subtask_title": subtask_title},
+            linear=self._get_linear_info(state_data, identifier),
+        )
+
+    def _create_session_complete_event(self, state_data: Dict, current: StateSnapshot) -> RalphEvent:
+        started_at = state_data.get("started_at", "")
+        duration = 0.0
+        if started_at:
+            try:
+                start = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+                duration = (datetime.now(timezone.utc) - start).total_seconds()
+            except ValueError:
+                pass
+        return RalphEvent(
+            event_type=RalphEventType.SESSION_COMPLETE.value,
+            session_id=self._get_session_id(state_data),
+            task_name=state_data.get("task_name", "Unknown"),
+            iteration=current.iteration,
+            progress=self._get_progress(state_data, current),
+            payload={
+                "total_iterations": current.iteration,
+                "total_duration_seconds": duration,
+                "subtasks_completed": current.completed_count,
+                "subtasks_total": current.completed_count + current.todo_count,
+                "final_status": current.status,
+            },
+            linear=self._get_linear_info(state_data),
+        )
+
+
+# =============================================================================
+# Event Emission
+# =============================================================================
+
+class RalphEventEmitter:
+    def __init__(self, events_dir: str = DEFAULT_EVENTS_DIR):
+        self.events_dir = Path(events_dir)
+        self.events_dir.mkdir(parents=True, exist_ok=True)
+        self.current_session_file = self.events_dir / "current-session.jsonl"
+
+    def emit(self, event: RalphEvent) -> None:
+        with open(self.current_session_file, "a") as f:
+            f.write(event.to_json() + "\n")
+
+    def emit_batch(self, events: List[RalphEvent]) -> None:
+        for event in events:
+            self.emit(event)
+
+    def get_recent_events(self, limit: int = 50) -> List[Dict]:
+        if not self.current_session_file.exists():
+            return []
+        events = []
+        with open(self.current_session_file) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+        return events[-limit:]
+
+
+# =============================================================================
+# Main Entry Point
+# =============================================================================
+
+def check_and_emit(state_path: str = DEFAULT_STATE_FILE, emit: bool = True) -> List[RalphEvent]:
+    detector = RalphEventDetector(state_path)
+    events = detector.detect_changes()
+    if emit and events:
+        emitter = RalphEventEmitter()
+        emitter.emit_batch(events)
+        # Trigger notification dispatch
+        try:
+            import subprocess
+            lib_dir = Path(__file__).parent
+            notifier_path = lib_dir / "ralph_notifier.py"
+            if notifier_path.exists():
+                subprocess.Popen(
+                    ["python3", str(notifier_path), "--dispatch"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    start_new_session=True,
+                )
+        except Exception:
+            pass
+    return events
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Ralph Event Detection")
+    parser.add_argument("--state", default=DEFAULT_STATE_FILE, help="Path to Ralph state file")
+    parser.add_argument("--emit", action="store_true", help="Emit detected events")
+    parser.add_argument("--check", action="store_true", help="Check for changes")
+    parser.add_argument("--test", help="Emit test event of specified type")
+    parser.add_argument("--list", action="store_true", help="List recent events")
+    args = parser.parse_args()
+
+    if args.list:
+        emitter = RalphEventEmitter()
+        for event in emitter.get_recent_events():
+            print(json.dumps(event))
+        return
+
+    if args.test:
+        event = RalphEvent(
+            event_type=args.test,
+            session_id="test-session",
+            task_name="Test Task",
+            iteration=1,
+            progress=EventProgress(completed=1, total=5, percent=20.0),
+            payload={"test": True},
+        )
+        RalphEventEmitter().emit(event)
+        print(f"Emitted test event: {event.event_type}")
+        return
+
+    events = check_and_emit(args.state, emit=args.emit)
+    if events:
+        print(f"Detected {len(events)} event(s):")
+        for event in events:
+            print(f"  - {event.event_type}: {event.task_name}")
+    else:
+        print("No events detected")
+
+
+if __name__ == "__main__":
+    main()