agent-loop-tool 0.1.0__py3-none-any.whl

agent_loop/providers/antigravity.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from .base import Provider
+from . import register
+
+
+@register
+class AntigravityProvider(Provider):
+    name = "antigravity"
+    binary = "agy"
+    auto_mode_env = "ALLOW_AUTO_MODE_ANTIGRAVITY"
+
+    def build_argv(self, prompt: str) -> list[str]:
+        argv = [self.binary, "-p", prompt]
+        if self.auto_mode_enabled:
+            argv.append("--dangerously-skip-permissions")
+        argv.extend(self._model_argv())
+        return argv
+

agent_loop/providers/base.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from .. import audit
+
+
+class ProviderError(RuntimeError):
+    pass
+
+
+#: Grace period for the output pump to drain after the child exits.
+_PUMP_JOIN_SECONDS = 5
+
+
+@dataclass
+class CapturedResult:
+    """Result of a non-streaming, output-capturing provider invocation.
+
+    Produced only by `Provider.run_captured`, which is used by `agent-loop
+    init` to read a provider's full response. The developer/reviewer loop
+    keeps using `Provider.run`, which streams straight to the terminal.
+    """
+
+    returncode: int
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+
+
+class Provider(ABC):
+    name: str
+    binary: str
+    auto_mode_env: str
+    #: Flag this CLI uses to pin a model; overridable per provider.
+    model_flag: str = "--model"
+
+    def __init__(self, model: Optional[str] = None) -> None:
+        #: When None, the underlying CLI resolves its own default model.
+        self.model = model or None
+
+    @abstractmethod
+    def build_argv(self, prompt: str) -> list[str]:
+        ...
+
+    def _model_argv(self) -> list[str]:
+        """Argv fragment that pins the model, or empty to defer to the CLI."""
+        return [self.model_flag, self.model] if self.model else []
+
+    @property
+    def auto_mode_enabled(self) -> bool:
+        return os.environ.get(self.auto_mode_env, "0") == "1"
+
+    def preflight(self) -> None:
+        if shutil.which(self.binary) is None:
+            raise ProviderError(
+                f"Missing CLI for provider '{self.name}': '{self.binary}' not on PATH."
+            )
+
+    def run(self, prompt: str, timeout: int, audit_level: str = "full") -> int:
+        """Stream the agent's output to the terminal *and* the run log.
+
+        The child cannot simply inherit our stdout: `safety.tee_stdout_to`
+        rebinds `sys.stdout` at the Python level, while a subprocess writes to
+        the inherited file descriptor 1 directly. Anything the agent printed
+        would reach the terminal and bypass the log entirely — which is most of
+        what an audit trail is for. So its output is piped back here and
+        re-emitted through `print`, which does go through the tee.
+
+        A pump thread forwards lines as they arrive so long runs stay live
+        rather than surfacing only once the agent exits. `audit_level` (see
+        `agent_loop.audit`) controls what that pump actually does with each
+        line: pass it through untouched (``full``), scrub known secret shapes
+        first (``redacted``), or drop it entirely (``off``) so nothing the
+        agent printed reaches the committed log.
+        """
+        audit.validate(audit_level)
+        argv = self.build_argv(prompt)
+        proc = subprocess.Popen(
+            argv,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+            errors="replace",
+        )
+
+        redactor = audit.StreamRedactor() if audit_level == "redacted" else None
+
+        def _pump() -> None:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                if audit_level == "off":
+                    continue
+                if redactor is not None:
+                    line = redactor.feed_line(line)
+                    if not line:
+                        continue
+                print(line, end="", flush=True)
+
+        pump = threading.Thread(target=_pump, daemon=True)
+        pump.start()
+        try:
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+            pump.join(timeout=_PUMP_JOIN_SECONDS)
+            print(
+                f"[agent-loop] {self.name} timed out after {timeout}s",
+                flush=True,
+            )
+            return 124
+
+        pump.join(timeout=_PUMP_JOIN_SECONDS)
+        return proc.returncode
+
+    def run_captured(self, prompt: str, timeout: int) -> CapturedResult:
+        """Run the provider non-interactively, capturing stdout/stderr.
+
+        Unlike `run`, nothing is streamed to the terminal — this is for
+        callers (namely `agent-loop init`) that need to parse the provider's
+        full response rather than watch it work.
+        """
+        argv = self.build_argv(prompt)
+        try:
+            result = subprocess.run(
+                argv, timeout=timeout, capture_output=True, text=True
+            )
+            return CapturedResult(
+                returncode=result.returncode,
+                stdout=result.stdout,
+                stderr=result.stderr,
+            )
+        except subprocess.TimeoutExpired as e:
+            return CapturedResult(
+                returncode=124,
+                stdout=e.stdout or "",
+                stderr=e.stderr or "",
+                timed_out=True,
+            )

agent_loop/providers/claude.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from .base import Provider
+from . import register
+
+
+@register
+class ClaudeProvider(Provider):
+    name = "claude"
+    binary = "claude"
+    auto_mode_env = "ALLOW_AUTO_MODE_CLAUDE"
+
+    def build_argv(self, prompt: str) -> list[str]:
+        argv = [self.binary, "-p", prompt]
+        if self.auto_mode_enabled:
+            argv.append("--dangerously-skip-permissions")
+        argv.extend(["--output-format", "text"])
+        argv.extend(self._model_argv())
+        return argv

agent_loop/providers/codex.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from .base import Provider
+from . import register
+
+
+@register
+class CodexProvider(Provider):
+    name = "codex"
+    binary = "codex"
+    auto_mode_env = "ALLOW_AUTO_MODE_CODEX"
+    model_flag = "-m"
+
+    def build_argv(self, prompt: str) -> list[str]:
+        flag = (
+            "--dangerously-bypass-approvals-and-sandbox"
+            if self.auto_mode_enabled
+            else "--full-auto"
+        )
+        # Model must precede the positional prompt so `exec` parses it as a flag.
+        return [self.binary, "exec", flag, *self._model_argv(), prompt]

agent_loop/providers/grok.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .base import Provider
+from . import register
+
+
+@register
+class GrokProvider(Provider):
+    name = "grok"
+    binary = "grok"
+    auto_mode_env = "ALLOW_AUTO_MODE_GROK"
+
+    def build_argv(self, prompt: str) -> list[str]:
+        argv = [self.binary, "-p", prompt]
+        if self.auto_mode_enabled:
+            argv.append("--always-approve")
+        argv.extend(self._model_argv())
+        return argv

agent_loop/safety.py

@@ -0,0 +1,105 @@
+"""Lockfile, log directory, and auto-mode-flag gating."""
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+
+from .git_ops import GitError, repo_root
+from .providers.base import Provider
+
+
+class LockHeld(RuntimeError):
+    pass
+
+
+class AutoModeGateError(RuntimeError):
+    pass
+
+
+@contextmanager
+def lockfile(path: Path):
+    try:
+        path.mkdir(parents=False, exist_ok=False)
+    except FileExistsError as e:
+        raise LockHeld(
+            f"Another loop appears to be running (lock: {path}). "
+            "Remove the lock only if you are sure no loop process is active."
+        ) from e
+    try:
+        yield
+    finally:
+        try:
+            path.rmdir()
+        except OSError:
+            pass
+
+
+def open_log_file(log_dir: Path) -> Path:
+    log_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return log_dir / f"loop_{stamp}.log"
+
+
+def require_auto_mode_gates(providers: list[Provider]) -> None:
+    """Refuse to launch if any assigned provider's write-mode env isn't set.
+
+    Mirrors the bash script's refusal for prompt-only Claude — every coding-agent
+    CLI in v1 expects yolo/auto mode for unattended runs.
+    """
+    blocked = [p for p in providers if not p.auto_mode_enabled]
+    if not blocked:
+        return
+
+    lines = [
+        "These providers are assigned to a role that writes files, but their",
+        "write-mode env gate is not set:",
+        "",
+    ]
+    for p in blocked:
+        lines.append(f"  {p.name:8s}  set {p.auto_mode_env}=1")
+    lines.extend(
+        [
+            "",
+            "Unattended runs would otherwise block on a permission prompt.",
+            "Re-run with the missing env vars exported.",
+        ]
+    )
+    raise AutoModeGateError("\n".join(lines))
+
+
+def tee_stdout_to(log_path: Path) -> None:
+    """Mirror stdout+stderr to a log file in addition to the terminal."""
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    log_fh = open(log_path, "a", buffering=1)
+
+    class _Tee:
+        def __init__(self, *streams):
+            self.streams = streams
+
+        def write(self, data):
+            for s in self.streams:
+                s.write(data)
+
+        def flush(self):
+            for s in self.streams:
+                s.flush()
+
+    sys.stdout = _Tee(sys.stdout, log_fh)
+    sys.stderr = _Tee(sys.stderr, log_fh)
+
+
+def default_log_dir() -> Path:
+    configured = os.environ.get("LOG_DIR")
+    if configured:
+        return Path(configured)
+    try:
+        return repo_root() / "logs"
+    except GitError:
+        return Path("logs")
+
+
+def default_lock_path() -> Path:
+    return Path(os.environ.get("LOCK_DIR", "/tmp/agent_loop.lock"))

agent_loop/state.py

@@ -0,0 +1,247 @@
+"""Load, validate, mutate, and save plan_checkpoints.json."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+ALLOWED_STATUSES = ("pending", "built", "approved")
+PROTECTED_BRANCHES = ("main", "master")
+REQUIRED_TOP_LEVEL = ("plan_file", "branch", "checkpoints")
+REQUIRED_CHECKPOINT_FIELDS = (
+    "id",
+    "name",
+    "status",
+    "scope",
+    "exit_criteria",
+    "attempts",
+    "review_notes",
+)
+COMMAND_FIELDS = ("build_cmd", "test_cmd", "lint_cmd")
+MODEL_ROLES = ("developer", "reviewer")
+
+
+class InvalidPlanState(ValueError):
+    """Raised when plan_checkpoints.json fails schema validation."""
+
+
+class ProtectedBranchError(InvalidPlanState):
+    """Raised when a payload targets a protected branch (e.g. main, master)."""
+
+
+class DuplicateCheckpointError(InvalidPlanState):
+    """Raised when a payload contains two checkpoints with the same id."""
+
+
+class CheckpointNotFound(KeyError):
+    def __init__(self, cid: str):
+        super().__init__(cid)
+        self.cid = cid
+
+    def __str__(self) -> str:
+        return f"Unknown checkpoint: {self.cid}"
+
+
+@dataclass
+class PlanState:
+    path: Path
+    plan_file: str
+    branch: str
+    checkpoints: list[dict]
+    project: dict = field(default_factory=dict)
+    models: dict = field(default_factory=dict)
+
+    # ------------------------------------------------------------------
+    # Convenience accessors for the project block
+    # ------------------------------------------------------------------
+
+    @property
+    def build_cmd(self) -> Optional[str]:
+        return self.project.get("build_cmd")
+
+    @property
+    def test_cmd(self) -> Optional[str]:
+        return self.project.get("test_cmd")
+
+    @property
+    def lint_cmd(self) -> Optional[str]:
+        return self.project.get("lint_cmd")
+
+    @property
+    def verify_in_review(self) -> bool:
+        return bool(self.project.get("verify_in_review", False))
+
+    def command_for(self, cid: str, field_name: str) -> Optional[str]:
+        if field_name not in COMMAND_FIELDS:
+            raise ValueError(f"Unknown command field: {field_name}")
+        cp = self.get(cid)
+        return cp.get(field_name) or self.project.get(field_name)
+
+    def model_for(self, role: str) -> Optional[str]:
+        """Model pinned for a role in the plan, or None to defer to the CLI."""
+        if role not in MODEL_ROLES:
+            raise ValueError(f"Unknown model role: {role}")
+        return self.models.get(role)
+
+    # ------------------------------------------------------------------
+    # Checkpoint queries / mutations
+    # ------------------------------------------------------------------
+
+    def get(self, cid: str) -> dict:
+        for cp in self.checkpoints:
+            if cp["id"] == cid:
+                return cp
+        raise CheckpointNotFound(cid)
+
+    def ids(self) -> list[str]:
+        return [cp["id"] for cp in self.checkpoints]
+
+    def pending_checkpoints(self) -> Iterable[dict]:
+        return [cp for cp in self.checkpoints if cp["status"] != "approved"]
+
+    def set_field(self, cid: str, field_name: str, value: Any) -> None:
+        cp = self.get(cid)
+        if field_name == "status" and value not in ALLOWED_STATUSES:
+            raise InvalidPlanState(
+                f"checkpoint {cid}: invalid status {value!r}; allowed: {ALLOWED_STATUSES}"
+            )
+        cp[field_name] = value
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self) -> None:
+        payload: dict[str, Any] = {
+            "plan_file": self.plan_file,
+            "branch": self.branch,
+        }
+        if self.project:
+            payload["project"] = self.project
+        if self.models:
+            payload["models"] = self.models
+        payload["checkpoints"] = self.checkpoints
+
+        with self.path.open("w") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+
+
+def load_state(path: Path | str) -> PlanState:
+    path = Path(path)
+    if not path.is_file():
+        raise InvalidPlanState(f"State file not found: {path}")
+    try:
+        raw = json.loads(path.read_text())
+    except json.JSONDecodeError as e:
+        raise InvalidPlanState(f"State file is not valid JSON: {e}") from e
+
+    validate_payload(raw)
+    return PlanState(
+        path=path,
+        plan_file=raw["plan_file"],
+        branch=raw["branch"],
+        checkpoints=raw["checkpoints"],
+        # `or {}` (not a get-default) so an explicit `null` becomes {} too.
+        project=raw.get("project") or {},
+        models=raw.get("models") or {},
+    )
+
+
+def validate_payload(raw: Any) -> None:
+    """Schema-check a plan payload (dict, not yet written to disk).
+
+    Reused by `load_state` and by plan generation (see `plan_init.py`) so an
+    in-memory generated payload can be validated before it is ever written.
+    """
+    if not isinstance(raw, dict):
+        raise InvalidPlanState("Top-level must be a JSON object")
+
+    for field_name in REQUIRED_TOP_LEVEL:
+        if field_name not in raw:
+            raise InvalidPlanState(f"Missing top-level field: {field_name}")
+
+    branch = raw["branch"]
+    if not isinstance(branch, str) or not branch:
+        raise InvalidPlanState("'branch' must be a non-empty string")
+    if branch in PROTECTED_BRANCHES:
+        raise ProtectedBranchError(f"Refusing protected target branch: {branch}")
+
+    if not isinstance(raw["plan_file"], str) or not raw["plan_file"]:
+        raise InvalidPlanState("'plan_file' must be a non-empty string")
+
+    checkpoints = raw["checkpoints"]
+    if not isinstance(checkpoints, list) or not checkpoints:
+        raise InvalidPlanState("'checkpoints' must be a non-empty list")
+
+    seen_ids: set[str] = set()
+    for idx, cp in enumerate(checkpoints):
+        if not isinstance(cp, dict):
+            raise InvalidPlanState(f"checkpoint #{idx} must be a JSON object")
+        for f in REQUIRED_CHECKPOINT_FIELDS:
+            if f not in cp:
+                raise InvalidPlanState(
+                    f"checkpoint #{idx}: missing required field '{f}'"
+                )
+
+        # Identify the checkpoint by index until 'id' is known to be a usable
+        # string; every message below can then name it.
+        if not isinstance(cp["id"], str) or not cp["id"]:
+            raise InvalidPlanState(f"checkpoint #{idx}: 'id' must be a non-empty string")
+        for f in ("name", "scope"):
+            if not isinstance(cp[f], str) or not cp[f]:
+                raise InvalidPlanState(
+                    f"checkpoint {cp['id']}: '{f}' must be a non-empty string"
+                )
+
+        if cp["status"] not in ALLOWED_STATUSES:
+            raise InvalidPlanState(
+                f"checkpoint {cp['id']}: invalid status {cp['status']!r}; "
+                f"allowed: {ALLOWED_STATUSES}"
+            )
+        # Non-empty: a checkpoint with no criteria gives the review gate
+        # nothing objective to check, so it can only ever be waved through.
+        if not isinstance(cp["exit_criteria"], list) or not cp["exit_criteria"]:
+            raise InvalidPlanState(
+                f"checkpoint {cp['id']}: 'exit_criteria' must be a non-empty list"
+            )
+        for c_idx, criterion in enumerate(cp["exit_criteria"]):
+            if not isinstance(criterion, str) or not criterion.strip():
+                raise InvalidPlanState(
+                    f"checkpoint {cp['id']}: 'exit_criteria[{c_idx}]' must be a "
+                    f"non-empty string"
+                )
+        # bool is an int subclass, so reject it explicitly. Negatives are
+        # rejected too: the loop counts up from 'attempts' toward
+        # max_review_attempts, so a negative one buys extra review rounds.
+        if (
+            not isinstance(cp["attempts"], int)
+            or isinstance(cp["attempts"], bool)
+            or cp["attempts"] < 0
+        ):
+            raise InvalidPlanState(
+                f"checkpoint {cp['id']}: 'attempts' must be a non-negative integer"
+            )
+        if not isinstance(cp["review_notes"], str):
+            raise InvalidPlanState(f"checkpoint {cp['id']}: 'review_notes' must be a string")
+
+        if cp["id"] in seen_ids:
+            raise DuplicateCheckpointError(f"duplicate checkpoint id: {cp['id']}")
+        seen_ids.add(cp["id"])
+
+    project = raw.get("project")
+    if project is not None and not isinstance(project, dict):
+        raise InvalidPlanState("'project' must be a JSON object when present")
+
+    models = raw.get("models")
+    if models is not None:
+        if not isinstance(models, dict):
+            raise InvalidPlanState("'models' must be a JSON object when present")
+        for role, model in models.items():
+            if role not in MODEL_ROLES:
+                raise InvalidPlanState(
+                    f"'models' has unknown role {role!r}; allowed: {MODEL_ROLES}"
+                )
+            if not isinstance(model, str) or not model:
+                raise InvalidPlanState(f"'models.{role}' must be a non-empty string")