nullabot 1.0.1__py3-none-any.whl

nullabot/core/reliability.py

@@ -0,0 +1,420 @@
+"""
+Reliability - Circuit breaker, exit detection, and progress tracking.
+
+Borrowed from Ralph Claude Code with enhancements for async Python.
+"""
+
+import hashlib
+import json
+from datetime import datetime, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states (Michael Nygard pattern)."""
+
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Failing, reject calls
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+class CircuitBreaker(BaseModel):
+    """
+    Circuit breaker to prevent cascading failures.
+
+    Transitions:
+    - CLOSED → OPEN: After failure_threshold failures
+    - OPEN → HALF_OPEN: After recovery_timeout
+    - HALF_OPEN → CLOSED: If test call succeeds
+    - HALF_OPEN → OPEN: If test call fails
+    """
+
+    state: CircuitState = CircuitState.CLOSED
+    failure_count: int = 0
+    last_failure_time: Optional[datetime] = None
+    last_success_time: Optional[datetime] = None
+
+    # Configuration
+    failure_threshold: int = 5
+    recovery_timeout_seconds: int = 60
+    half_open_max_calls: int = 1
+    half_open_calls: int = 0
+
+    # Tracking
+    consecutive_no_progress: int = 0
+    consecutive_same_error: int = 0
+    last_error_hash: Optional[str] = None
+
+    def can_execute(self) -> tuple[bool, str]:
+        """
+        Check if we can execute a call.
+
+        Returns:
+            Tuple of (can_execute, reason)
+        """
+        if self.state == CircuitState.CLOSED:
+            return True, "circuit_closed"
+
+        if self.state == CircuitState.OPEN:
+            # Check if recovery timeout has passed
+            if self.last_failure_time:
+                elapsed = datetime.now() - self.last_failure_time
+                if elapsed.total_seconds() >= self.recovery_timeout_seconds:
+                    self.state = CircuitState.HALF_OPEN
+                    self.half_open_calls = 0
+                    return True, "testing_recovery"
+            return False, f"circuit_open_wait_{self.recovery_timeout_seconds}s"
+
+        if self.state == CircuitState.HALF_OPEN:
+            if self.half_open_calls < self.half_open_max_calls:
+                self.half_open_calls += 1
+                return True, "half_open_test"
+            return False, "half_open_limit_reached"
+
+        return False, "unknown_state"
+
+    def record_success(self) -> None:
+        """Record a successful call."""
+        self.last_success_time = datetime.now()
+        self.consecutive_no_progress = 0
+
+        if self.state == CircuitState.HALF_OPEN:
+            # Recovery successful
+            self.state = CircuitState.CLOSED
+            self.failure_count = 0
+            self.consecutive_same_error = 0
+            self.last_error_hash = None
+        elif self.state == CircuitState.CLOSED:
+            # Reset failure count on success
+            self.failure_count = max(0, self.failure_count - 1)
+
+    def record_failure(self, error: str) -> None:
+        """Record a failed call."""
+        self.last_failure_time = datetime.now()
+        self.failure_count += 1
+
+        # Track repeated errors
+        error_hash = hashlib.md5(error.encode()).hexdigest()[:8]
+        if error_hash == self.last_error_hash:
+            self.consecutive_same_error += 1
+        else:
+            self.consecutive_same_error = 1
+            self.last_error_hash = error_hash
+
+        if self.state == CircuitState.HALF_OPEN:
+            # Recovery failed
+            self.state = CircuitState.OPEN
+        elif self.state == CircuitState.CLOSED:
+            # Check if we should open
+            if self.failure_count >= self.failure_threshold:
+                self.state = CircuitState.OPEN
+            elif self.consecutive_same_error >= 3:
+                # Same error repeated = likely stuck
+                self.state = CircuitState.OPEN
+
+    def record_no_progress(self) -> bool:
+        """
+        Record a cycle with no progress.
+
+        Returns:
+            True if circuit should open due to no progress
+        """
+        self.consecutive_no_progress += 1
+
+        if self.consecutive_no_progress >= 3:
+            self.state = CircuitState.OPEN
+            return True
+        return False
+
+    def reset(self) -> None:
+        """Reset circuit breaker to initial state."""
+        self.state = CircuitState.CLOSED
+        self.failure_count = 0
+        self.last_failure_time = None
+        self.consecutive_no_progress = 0
+        self.consecutive_same_error = 0
+        self.last_error_hash = None
+
+
+class ProgressTracker(BaseModel):
+    """Track progress to detect deadlocks and completion."""
+
+    # Output tracking
+    last_output_hash: Optional[str] = None
+    output_hashes: list[str] = Field(default_factory=list)
+
+    # Completion signals
+    completion_signals: list[datetime] = Field(default_factory=list)
+    done_keywords_found: int = 0
+
+    # Cycle tracking
+    cycles_without_change: int = 0
+    total_cycles: int = 0
+
+    # Tool tracking
+    last_tool_calls: list[str] = Field(default_factory=list)
+    repeated_tool_sequences: int = 0
+
+    # Configuration
+    max_cycles_no_change: int = 5
+    max_completion_signals: int = 3
+
+    # Completion keywords to detect
+    COMPLETION_KEYWORDS: list[str] = [
+        "task complete",
+        "all done",
+        "finished",
+        "completed successfully",
+        "nothing left to do",
+        "work is complete",
+    ]
+
+    def compute_hash(self, content: str) -> str:
+        """Compute hash of content for comparison."""
+        return hashlib.md5(content.encode()).hexdigest()[:16]
+
+    def record_cycle(
+        self,
+        output: str,
+        tool_calls: list[str],
+        files_changed: list[str],
+    ) -> dict[str, Any]:
+        """
+        Record a cycle and return analysis.
+
+        Returns dict with:
+        - has_progress: bool
+        - should_exit: bool
+        - exit_reason: Optional[str]
+        """
+        self.total_cycles += 1
+
+        # Check for progress via output change
+        output_hash = self.compute_hash(output)
+        has_output_change = output_hash != self.last_output_hash
+
+        if has_output_change:
+            self.output_hashes.append(output_hash)
+            # Keep only last 10
+            if len(self.output_hashes) > 10:
+                self.output_hashes = self.output_hashes[-10:]
+
+        self.last_output_hash = output_hash
+
+        # Check for progress via files changed
+        has_file_changes = len(files_changed) > 0
+
+        # Check for repeated tool sequences
+        tool_sequence = ",".join(sorted(tool_calls))
+        if tool_calls == self.last_tool_calls:
+            self.repeated_tool_sequences += 1
+        else:
+            self.repeated_tool_sequences = 0
+        self.last_tool_calls = tool_calls
+
+        # Determine if we have progress
+        has_progress = has_output_change or has_file_changes
+
+        if has_progress:
+            self.cycles_without_change = 0
+        else:
+            self.cycles_without_change += 1
+
+        # Check for completion keywords
+        output_lower = output.lower()
+        for keyword in self.COMPLETION_KEYWORDS:
+            if keyword in output_lower:
+                self.done_keywords_found += 1
+                self.completion_signals.append(datetime.now())
+                break
+
+        # Determine if should exit
+        should_exit = False
+        exit_reason = None
+
+        # Exit: Too many cycles without change
+        if self.cycles_without_change >= self.max_cycles_no_change:
+            should_exit = True
+            exit_reason = f"no_progress_{self.cycles_without_change}_cycles"
+
+        # Exit: Multiple completion signals
+        elif self.done_keywords_found >= self.max_completion_signals:
+            should_exit = True
+            exit_reason = "completion_signals_reached"
+
+        # Exit: Repeated same tool calls (stuck in loop)
+        elif self.repeated_tool_sequences >= 3:
+            should_exit = True
+            exit_reason = "repeated_tool_sequence"
+
+        return {
+            "has_progress": has_progress,
+            "should_exit": should_exit,
+            "exit_reason": exit_reason,
+            "cycles_without_change": self.cycles_without_change,
+            "completion_signals": self.done_keywords_found,
+            "total_cycles": self.total_cycles,
+        }
+
+    def reset(self) -> None:
+        """Reset tracker for new task."""
+        self.last_output_hash = None
+        self.output_hashes = []
+        self.completion_signals = []
+        self.done_keywords_found = 0
+        self.cycles_without_change = 0
+        self.total_cycles = 0
+        self.last_tool_calls = []
+        self.repeated_tool_sequences = 0
+
+
+class ExitDetector:
+    """
+    Detect when agent should exit (Ralph's dual-condition gate).
+
+    Requires BOTH:
+    1. Completion indicators (keywords, no changes)
+    2. Explicit signal OR safety threshold
+    """
+
+    def __init__(
+        self,
+        max_cycles: int = 100,
+        max_cycles_no_progress: int = 5,
+        completion_signal_threshold: int = 2,
+        safety_exit_threshold: int = 5,
+    ):
+        self.max_cycles = max_cycles
+        self.max_cycles_no_progress = max_cycles_no_progress
+        self.completion_signal_threshold = completion_signal_threshold
+        self.safety_exit_threshold = safety_exit_threshold
+
+        # State
+        self.completion_indicators: list[int] = []  # Cycle numbers
+        self.test_only_cycles: list[int] = []
+        self.explicit_exit_signal: bool = False
+
+    def record_completion_indicator(self, cycle: int) -> None:
+        """Record that this cycle had completion indicators."""
+        self.completion_indicators.append(cycle)
+        # Keep only last 5
+        if len(self.completion_indicators) > 5:
+            self.completion_indicators = self.completion_indicators[-5:]
+
+    def record_test_only_cycle(self, cycle: int) -> None:
+        """Record that this cycle only ran tests."""
+        self.test_only_cycles.append(cycle)
+        if len(self.test_only_cycles) > 5:
+            self.test_only_cycles = self.test_only_cycles[-5:]
+
+    def set_explicit_exit(self, value: bool = True) -> None:
+        """Set explicit exit signal from agent."""
+        self.explicit_exit_signal = value
+
+    def should_exit(
+        self,
+        current_cycle: int,
+        cycles_no_progress: int,
+        progress_tracker: Optional[ProgressTracker] = None,
+    ) -> tuple[bool, str]:
+        """
+        Check if agent should exit (dual-condition gate).
+
+        Returns:
+            Tuple of (should_exit, reason)
+        """
+        # Safety: Max cycles reached
+        if current_cycle >= self.max_cycles:
+            return True, f"max_cycles_reached_{self.max_cycles}"
+
+        # Safety: No progress for too long
+        if cycles_no_progress >= self.max_cycles_no_progress:
+            return True, f"no_progress_{cycles_no_progress}_cycles"
+
+        # Count recent completion indicators
+        recent_indicators = len([
+            c for c in self.completion_indicators
+            if current_cycle - c <= 5
+        ])
+
+        # Safety circuit breaker: Too many completion indicators
+        if recent_indicators >= self.safety_exit_threshold:
+            return True, "safety_circuit_breaker"
+
+        # Dual-condition: Indicators + explicit signal
+        if recent_indicators >= self.completion_signal_threshold:
+            if self.explicit_exit_signal:
+                return True, "task_complete"
+
+        # Test saturation: Only running tests
+        recent_test_only = len([
+            c for c in self.test_only_cycles
+            if current_cycle - c <= 5
+        ])
+        if recent_test_only >= 3:
+            return True, "test_saturation"
+
+        # Check progress tracker if available
+        if progress_tracker:
+            analysis = progress_tracker.record_cycle("", [], [])
+            if analysis["should_exit"]:
+                return True, analysis["exit_reason"]
+
+        return False, ""
+
+    def reset(self) -> None:
+        """Reset for new task."""
+        self.completion_indicators = []
+        self.test_only_cycles = []
+        self.explicit_exit_signal = False
+
+
+def save_reliability_state(
+    path: Path,
+    circuit_breaker: CircuitBreaker,
+    progress_tracker: ProgressTracker,
+    exit_detector: ExitDetector,
+) -> None:
+    """Save reliability state to disk."""
+    state = {
+        "circuit_breaker": circuit_breaker.model_dump(),
+        "progress_tracker": progress_tracker.model_dump(),
+        "exit_detector": {
+            "completion_indicators": exit_detector.completion_indicators,
+            "test_only_cycles": exit_detector.test_only_cycles,
+            "explicit_exit_signal": exit_detector.explicit_exit_signal,
+            "max_cycles": exit_detector.max_cycles,
+        },
+        "saved_at": datetime.now().isoformat(),
+    }
+    path.write_text(json.dumps(state, indent=2, default=str), encoding="utf-8")
+
+
+def load_reliability_state(
+    path: Path,
+) -> tuple[Optional[CircuitBreaker], Optional[ProgressTracker], Optional[ExitDetector]]:
+    """Load reliability state from disk."""
+    if not path.exists():
+        return None, None, None
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+
+        circuit_breaker = CircuitBreaker.model_validate(data["circuit_breaker"])
+        progress_tracker = ProgressTracker.model_validate(data["progress_tracker"])
+
+        exit_data = data["exit_detector"]
+        exit_detector = ExitDetector(
+            max_cycles=exit_data.get("max_cycles", 100),
+        )
+        exit_detector.completion_indicators = exit_data.get("completion_indicators", [])
+        exit_detector.test_only_cycles = exit_data.get("test_only_cycles", [])
+        exit_detector.explicit_exit_signal = exit_data.get("explicit_exit_signal", False)
+
+        return circuit_breaker, progress_tracker, exit_detector
+    except Exception:
+        return None, None, None

nullabot/core/sandbox.py

@@ -0,0 +1,143 @@
+"""
+Sandbox - Secure folder isolation for projects.
+
+Each project can ONLY access its own folder. No escape allowed.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+class SandboxViolation(Exception):
+    """Raised when agent tries to access outside its sandbox."""
+
+    pass
+
+
+class Sandbox:
+    """
+    Enforces folder isolation for a project.
+
+    All file operations must go through this class to ensure
+    the agent cannot access files outside its designated folder.
+    """
+
+    def __init__(self, project_root: Path):
+        """
+        Initialize sandbox with project root folder.
+
+        Args:
+            project_root: Absolute path to project folder
+        """
+        self.root = project_root.resolve()
+        self.workspace = self.root / "workspace"
+        self._aurora_dir = self.root / ".nullabot"
+
+        # Ensure directories exist
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        self._aurora_dir.mkdir(parents=True, exist_ok=True)
+
+    def validate_path(self, path: str | Path) -> Path:
+        """
+        Validate and resolve a path, ensuring it's within sandbox.
+
+        Args:
+            path: Relative or absolute path to validate
+
+        Returns:
+            Resolved absolute path within sandbox
+
+        Raises:
+            SandboxViolation: If path escapes sandbox
+        """
+        # Convert to Path object
+        path = Path(path)
+
+        # If relative, resolve from workspace
+        if not path.is_absolute():
+            resolved = (self.workspace / path).resolve()
+        else:
+            resolved = path.resolve()
+
+        # Check if within sandbox (workspace or .nullabot)
+        try:
+            resolved.relative_to(self.root)
+        except ValueError:
+            raise SandboxViolation(
+                f"Access denied: '{path}' is outside project sandbox.\n"
+                f"Allowed: {self.root}"
+            )
+
+        return resolved
+
+    def read_file(self, path: str | Path) -> str:
+        """Safely read a file within sandbox."""
+        safe_path = self.validate_path(path)
+        if not safe_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        if not safe_path.is_file():
+            raise IsADirectoryError(f"Not a file: {path}")
+        return safe_path.read_text(encoding="utf-8")
+
+    def write_file(self, path: str | Path, content: str) -> Path:
+        """Safely write a file within sandbox."""
+        safe_path = self.validate_path(path)
+        safe_path.parent.mkdir(parents=True, exist_ok=True)
+        safe_path.write_text(content, encoding="utf-8")
+        return safe_path
+
+    def list_dir(self, path: str | Path = ".") -> list[Path]:
+        """Safely list directory contents within sandbox."""
+        safe_path = self.validate_path(path)
+        if not safe_path.is_dir():
+            raise NotADirectoryError(f"Not a directory: {path}")
+        return list(safe_path.iterdir())
+
+    def exists(self, path: str | Path) -> bool:
+        """Check if path exists within sandbox."""
+        try:
+            safe_path = self.validate_path(path)
+            return safe_path.exists()
+        except SandboxViolation:
+            return False
+
+    def mkdir(self, path: str | Path) -> Path:
+        """Safely create directory within sandbox."""
+        safe_path = self.validate_path(path)
+        safe_path.mkdir(parents=True, exist_ok=True)
+        return safe_path
+
+    def delete_file(self, path: str | Path) -> None:
+        """Safely delete a file within sandbox."""
+        safe_path = self.validate_path(path)
+        if safe_path.is_file():
+            safe_path.unlink()
+        elif safe_path.is_dir():
+            raise IsADirectoryError(f"Cannot delete directory with delete_file: {path}")
+
+    def get_relative_path(self, path: str | Path) -> Path:
+        """Get path relative to workspace."""
+        safe_path = self.validate_path(path)
+        try:
+            return safe_path.relative_to(self.workspace)
+        except ValueError:
+            return safe_path.relative_to(self.root)
+
+    @property
+    def state_file(self) -> Path:
+        """Path to agent state file."""
+        return self._aurora_dir / "state.json"
+
+    @property
+    def checkpoint_file(self) -> Path:
+        """Path to checkpoint file."""
+        return self._aurora_dir / "checkpoint.json"
+
+    @property
+    def history_file(self) -> Path:
+        """Path to conversation history file."""
+        return self._aurora_dir / "history.jsonl"
+
+    def __repr__(self) -> str:
+        return f"Sandbox(root={self.root})"