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

agent_loop/orchestrator.py

@@ -0,0 +1,314 @@
+"""The checkpoint-gated developer/reviewer loop."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+from . import audit, git_ops, safety
+from .providers.base import Provider
+from .state import PlanState, load_state
+
+
+class LoopHalted(RuntimeError):
+    """Raised when a checkpoint cannot be approved within max_review_attempts."""
+
+
+def _log_event(event: str, **fields: Any) -> None:
+    """Print a stable, machine-readable event captured by the loop log tee."""
+    print(
+        f"[agent-loop] {event} "
+        f"{json.dumps({'event': event, **fields}, sort_keys=True, default=str)}",
+        flush=True,
+    )
+
+
+def _commit_audit_tail(message: str, log_dir: Path) -> None:
+    """Commit the run's closing state, flushing the log tail into git.
+
+    Called on every exit path, including failures, so it must never replace the
+    exception that is already propagating: a commit that cannot be made is
+    reported and swallowed.
+    """
+    try:
+        git_ops.commit_checkpoint_changes(message, log_dir=log_dir)
+    except Exception as exc:  # noqa: BLE001 - audit commit is best-effort
+        _log_event(
+            "AUDIT_COMMIT_FAILED",
+            error=str(exc),
+            error_type=type(exc).__name__,
+            message=message,
+        )
+
+
+def _run_agent(
+    *,
+    provider: Provider,
+    role: str,
+    checkpoint: str,
+    prompt: str,
+    timeout: int,
+    run_kind: str,
+    audit_level: str,
+) -> int:
+    """Run an agent while emitting start, prompt, and completion trace events."""
+    common = {
+        "checkpoint": checkpoint,
+        "provider": provider.name,
+        "role": role,
+        "run_kind": run_kind,
+    }
+    _log_event("AGENT_TRACE", action="start", timeout_seconds=timeout, **common)
+    _log_event(
+        "AGENT_TRACE",
+        action="prompt",
+        prompt=audit.prepare_text(prompt, audit_level),
+        **common,
+    )
+    try:
+        return_code = provider.run(prompt, timeout=timeout, audit_level=audit_level)
+    except Exception as exc:
+        _log_event(
+            "AGENT_TRACE",
+            action="finish",
+            error=str(exc),
+            error_type=type(exc).__name__,
+            outcome="error",
+            **common,
+        )
+        raise
+
+    _log_event(
+        "AGENT_TRACE",
+        action="finish",
+        outcome="completed",
+        return_code=return_code,
+        **common,
+    )
+    return return_code
+
+
+# ---------------------------------------------------------------------------
+# Prompt templates — project-agnostic; commands come from state.project.
+# ---------------------------------------------------------------------------
+
+
+def _criteria_block(checkpoint: dict) -> str:
+    return "\n".join(f"- {c}" for c in checkpoint["exit_criteria"])
+
+
+def _verify_clause(state: PlanState, cid: str) -> str:
+    if not state.verify_in_review:
+        return ""
+    parts: list[str] = []
+    for label, field_name in (
+        ("Run the build", "build_cmd"),
+        ("Run the tests", "test_cmd"),
+        ("Run the linter", "lint_cmd"),
+    ):
+        cmd = state.command_for(cid, field_name)
+        if cmd:
+            parts.append(f"- {label}: `{cmd}`")
+    if not parts:
+        return ""
+    return (
+        "\n\nIndependently verify the work by running these project commands:\n"
+        + "\n".join(parts)
+    )
+
+
+def developer_prompt(state: PlanState, cid: str) -> str:
+    cp = state.get(cid)
+    return f"""You are executing the agreed plan in {state.plan_file}.
+Work ONLY on checkpoint '{cid}' ({cp['name']}). Do not start any later phase.
+
+Scope:
+{cp['scope']}
+
+This phase is complete only when ALL of these exit criteria are objectively met:
+{_criteria_block(cp)}
+
+When finished, in {state.path.name} set checkpoint '{cid}' status to 'built' and
+write a concise summary (files touched, tests added, how each exit criterion is
+met) into its 'review_notes' field.
+"""
+
+
+def reviewer_prompt(state: PlanState, cid: str) -> str:
+    cp = state.get(cid)
+    verify = _verify_clause(state, cid)
+    return f"""Review ONLY checkpoint '{cid}' ({cp['name']}) of the plan in {state.plan_file}.
+Read {state.path.name} for the developer's 'review_notes', then independently
+verify the work in the repo.{verify}
+
+Scope for this checkpoint:
+{cp['scope']}
+
+Approve ONLY if every one of these exit criteria is genuinely met:
+{_criteria_block(cp)}
+
+If all pass: set checkpoint '{cid}' status to 'approved' in {state.path.name}.
+If a criterion genuinely fails: set status to 'built' and write SPECIFIC,
+actionable, criterion-referenced fixes into 'review_notes'. Do not nitpick style
+or request scope beyond this phase.
+
+Do not merge to main/master. All final merging must wait for explicit human approval.
+"""
+
+
+def revision_prompt(state: PlanState, cid: str, review_notes: str) -> str:
+    return f"""The reviewer did NOT approve checkpoint '{cid}' of the plan.
+Apply ONLY these requested fixes — do not add scope or pull work from later phases:
+
+{review_notes}
+
+When done, in {state.path.name} set checkpoint '{cid}' status back to 'built' and
+update 'review_notes' describing exactly what you changed.
+
+Do not merge to main/master. All final merging must wait for explicit human approval.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+
+
+def run_loop(
+    *,
+    state_path: Path,
+    developer: Provider,
+    reviewer: Provider,
+    max_review_attempts: int = 3,
+    timeout: int = 1800,
+    log_dir: Optional[Path] = None,
+    audit_level: str = audit.DEFAULT_AUDIT_LEVEL,
+) -> None:
+    audit.validate(audit_level)
+    state = load_state(state_path)
+    log_dir = log_dir or safety.default_log_dir()
+    git_ops.ensure_branch(state.branch)
+    git_ops.require_clean_worktree(log_dir=log_dir)
+
+    try:
+        for cid in state.ids():
+            cp = state.get(cid)
+            if cp["status"] == "approved":
+                print(f">> {cid} already approved — skip", flush=True)
+                _log_event(
+                    "APPROVAL_COMMENT",
+                    approval_status="approved",
+                    checkpoint=cid,
+                    comment=audit.prepare_text(cp["review_notes"], audit_level),
+                    source="existing_checkpoint",
+                )
+                continue
+
+            print(
+                f"\n============================================================"
+                f"\n  CHECKPOINT {cid} — {cp['name']}"
+                f"\n============================================================",
+                flush=True,
+            )
+
+            if cp["status"] != "built":
+                _run_agent(
+                    provider=developer,
+                    role="developer",
+                    checkpoint=cid,
+                    prompt=developer_prompt(state, cid),
+                    timeout=timeout,
+                    run_kind="build",
+                    audit_level=audit_level,
+                )
+                git_ops.commit_checkpoint_changes(f"{cid}: built", log_dir=log_dir)
+                state = load_state(state_path)  # reload after agent mutation
+            else:
+                print(f">> {cid} already built — resuming at review gate", flush=True)
+
+            while True:
+                cp = state.get(cid)
+                attempts = cp["attempts"] + 1
+                state.set_field(cid, "attempts", attempts)
+                state.save()
+                print(
+                    f"--- {cid} review attempt {attempts}/{max_review_attempts} ---",
+                    flush=True,
+                )
+
+                _run_agent(
+                    provider=reviewer,
+                    role="reviewer",
+                    checkpoint=cid,
+                    prompt=reviewer_prompt(state, cid),
+                    timeout=timeout,
+                    run_kind="review",
+                    audit_level=audit_level,
+                )
+                state = load_state(state_path)
+                reviewed_checkpoint = state.get(cid)
+                status = reviewed_checkpoint["status"]
+                notes = reviewed_checkpoint["review_notes"]
+                _log_event(
+                    "REVIEW_COMMENT",
+                    checkpoint=cid,
+                    comment=audit.prepare_text(notes, audit_level),
+                    review_attempt=attempts,
+                    status=status,
+                )
+
+                if status == "approved":
+                    print(f">> {cid} APPROVED", flush=True)
+                    _log_event(
+                        "APPROVAL_COMMENT",
+                        approval_status="approved",
+                        checkpoint=cid,
+                        comment=audit.prepare_text(notes, audit_level),
+                        review_attempt=attempts,
+                        source="reviewer",
+                    )
+                    git_ops.commit_checkpoint_changes(
+                        f"{cid}: approved", log_dir=log_dir
+                    )
+                    break
+
+                if attempts >= max_review_attempts:
+                    raise LoopHalted(
+                        f"{cid} not approved after {attempts} attempts — halting for human review."
+                    )
+
+                _run_agent(
+                    provider=developer,
+                    role="developer",
+                    checkpoint=cid,
+                    prompt=revision_prompt(state, cid, notes),
+                    timeout=timeout,
+                    run_kind="revision",
+                    audit_level=audit_level,
+                )
+                git_ops.commit_checkpoint_changes(
+                    f"{cid}: revision {attempts}", log_dir=log_dir
+                )
+                state = load_state(state_path)
+    except LoopHalted as exc:
+        _log_event("RUN_OUTCOME", outcome="halted", reason=str(exc))
+        _commit_audit_tail("audit: halted", log_dir)
+        raise
+    except BaseException as exc:
+        _log_event(
+            "RUN_OUTCOME",
+            outcome="failed",
+            error=str(exc),
+            error_type=type(exc).__name__,
+        )
+        _commit_audit_tail("audit: run failed", log_dir)
+        raise
+
+    print(f"\n### All checkpoints approved on branch {state.branch}.", flush=True)
+    print(
+        "### No merge was performed. Review the branch and merge to main/master "
+        "only after explicit human approval.",
+        flush=True,
+    )
+    _log_event("RUN_OUTCOME", outcome="completed", branch=state.branch)
+    _commit_audit_tail("audit: completed run", log_dir)

agent_loop/plan_init.py

@@ -0,0 +1,357 @@
+"""Shared foundations for building `plan_checkpoints.json` payloads.
+
+Provides the canonical generated-state shape (a payload that satisfies the
+same schema `load_state` enforces) plus reusable in-memory validation, so
+that plan-generation code (see the `init` subcommand, added in a later
+phase) can validate a provider-produced payload before writing anything to
+disk.
+
+Also provides the `init`-only plan-generation path: running a provider in
+captured (non-streaming) mode with a strict JSON-only prompt, then parsing
+and normalizing whatever it returns into checkpoints in the canonical shape
+above. The developer/reviewer loop is untouched by any of this.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import unicodedata
+from pathlib import Path
+from typing import Any, Optional
+
+from .providers.base import Provider
+from .state import (
+    DuplicateCheckpointError,
+    InvalidPlanState,
+    ProtectedBranchError,
+    validate_payload,
+)
+
+__all__ = [
+    "DEFAULT_PLAN_FILE",
+    "DuplicateCheckpointError",
+    "InvalidPlanState",
+    "PlanOutputParseError",
+    "ProtectedBranchError",
+    "ProviderExecutionError",
+    "StateFileExistsError",
+    "build_generated_payload",
+    "build_init_prompt",
+    "generate_plan_json",
+    "new_checkpoint",
+    "normalize_checkpoints",
+    "parse_plan_json",
+    "run_provider_captured",
+    "slugify",
+    "validate_generated_payload",
+    "write_generated_payload",
+]
+
+#: `plan_file` recorded for a plain-English feature description, matching the
+#: convention documented in the README's schema example.
+DEFAULT_PLAN_FILE = "docs/implementation_plan.md"
+
+
+class ProviderExecutionError(RuntimeError):
+    """Raised when the planning provider exits non-zero or times out."""
+
+
+class PlanOutputParseError(ValueError):
+    """Raised when provider output is not raw JSON or a single JSON code fence."""
+
+
+class StateFileExistsError(RuntimeError):
+    """Raised when the target state file exists and overwriting was not requested."""
+
+
+def new_checkpoint(cid: str, name: str, scope: str, exit_criteria: list[str]) -> dict:
+    """Build a single checkpoint in its canonical freshly-generated shape.
+
+    Always starts `pending`, with zero attempts and no review notes,
+    regardless of what a provider returned for those fields.
+    """
+    return {
+        "id": cid,
+        "name": name,
+        "status": "pending",
+        "scope": scope,
+        "exit_criteria": list(exit_criteria),
+        "attempts": 0,
+        "review_notes": "",
+    }
+
+
+def build_generated_payload(
+    plan_file: str,
+    branch: str,
+    checkpoints: list[dict],
+    project: Optional[dict] = None,
+    models: Optional[dict] = None,
+) -> dict[str, Any]:
+    """Assemble a top-level payload in the canonical generated-state shape."""
+    payload: dict[str, Any] = {
+        "plan_file": plan_file,
+        "branch": branch,
+        "checkpoints": checkpoints,
+    }
+    if project:
+        payload["project"] = project
+    if models:
+        payload["models"] = models
+    return payload
+
+
+def validate_generated_payload(payload: dict) -> None:
+    """Validate an in-memory generated payload before it is written to disk.
+
+    Raises `InvalidPlanState` (or the more specific `ProtectedBranchError` /
+    `DuplicateCheckpointError` subclasses) on failure; raises nothing on
+    success.
+    """
+    validate_payload(payload)
+
+
+_SLUG_COLLAPSE_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str, max_len: int = 40) -> str:
+    """Turn arbitrary text into a short, branch-name-safe slug.
+
+    Transliterates accented characters to their ASCII base (so "café"
+    becomes "cafe" rather than "caf"), lowercases, collapses any run of
+    remaining non-alphanumeric characters into a single hyphen, and trims to
+    `max_len`. Falls back to "feature" if nothing alphanumeric survives.
+    """
+    # NFKD splits "é" into "e" + combining accent; dropping non-ASCII then
+    # keeps the base letter. Must run before truncation so `max_len` counts
+    # the characters that actually reach the branch name.
+    decomposed = unicodedata.normalize("NFKD", text)
+    ascii_text = decomposed.encode("ascii", "ignore").decode("ascii")
+    slug = _SLUG_COLLAPSE_RE.sub("-", ascii_text.strip().lower()).strip("-")
+    slug = slug[:max_len].strip("-")
+    return slug or "feature"
+
+
+def _publish_exclusive(tmp_name: str, path: Path) -> None:
+    """Publish `tmp_name` as `path`, refusing to replace an existing file.
+
+    Both routes below create the final name and fail if it is already taken in
+    one atomic step, with no exists()-then-write gap — so a state file that
+    another process creates between the CLI's up-front existence check and
+    this write is never clobbered, on any filesystem.
+    """
+    try:
+        os.link(tmp_name, path)
+        return
+    except FileExistsError as e:
+        raise StateFileExistsError(f"{path} already exists") from e
+    except OSError:
+        pass  # no hardlink support on this filesystem; claim the name instead
+
+    # Filesystems without hardlink support (exFAT, some network mounts) still
+    # honour O_CREAT|O_EXCL, which claims the name atomically and does not
+    # follow symlinks. Claiming it up front means the os.replace below can only
+    # ever overwrite the empty placeholder this process owns — never a state
+    # file a concurrent init wrote. A plain exists()-then-replace would not:
+    # it reopens the very race the exclusive publish exists to close.
+    try:
+        os.close(os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600))
+    except FileExistsError as e:
+        raise StateFileExistsError(f"{path} already exists") from e
+
+    try:
+        os.replace(tmp_name, path)
+    except OSError:
+        # Drop the placeholder so a failed publish does not leave a zero-byte
+        # state file behind, blocking the next run until --force.
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+        raise
+
+
+def write_generated_payload(path: Path, payload: dict, *, force: bool = False) -> None:
+    """Write `payload` as formatted JSON to `path` atomically.
+
+    Writes to a temp file in the same directory first, flushes it to disk,
+    then publishes it under `path`, so a crash or interrupt never leaves
+    `path` truncated or holding partial JSON. Without `force`, an existing
+    `path` is left untouched and `StateFileExistsError` is raised. Callers
+    must validate `payload` before calling this.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+            f.flush()
+            # Durable on disk before it is reachable under `path`.
+            os.fsync(f.fileno())
+
+        if force:
+            os.replace(tmp_name, path)
+            tmp_name = None  # consumed by the rename
+        else:
+            _publish_exclusive(tmp_name, path)
+    finally:
+        # After a successful link the payload lives under both names; drop the
+        # temp one. Also cleans up after any failure above.
+        if tmp_name is not None:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Captured provider execution (init only — the run/review loop keeps using
+# Provider.run's streaming behavior, unchanged).
+# ---------------------------------------------------------------------------
+
+
+def run_provider_captured(provider: Provider, prompt: str, timeout: int) -> str:
+    """Run `provider` non-interactively and return its captured stdout.
+
+    Raises `ProviderExecutionError` on a timeout or a non-zero exit rather
+    than handing the caller a partial or garbage result.
+    """
+    result = provider.run_captured(prompt, timeout=timeout)
+    if result.timed_out:
+        raise ProviderExecutionError(
+            f"{provider.name} timed out after {timeout}s while generating a plan"
+        )
+    if result.returncode != 0:
+        detail = result.stderr.strip()
+        suffix = f": {detail}" if detail else ""
+        raise ProviderExecutionError(
+            f"{provider.name} exited with code {result.returncode} while "
+            f"generating a plan{suffix}"
+        )
+    return result.stdout
+
+
+# ---------------------------------------------------------------------------
+# Prompt: project-agnostic, ordered, independently reviewable checkpoints,
+# JSON-only output.
+# ---------------------------------------------------------------------------
+
+INIT_PROMPT_TEMPLATE = """You are generating an implementation plan for a checkpoint-gated developer/reviewer coding loop. Convert the feature description below into an ordered list of independently reviewable checkpoints.
+
+Feature description:
+{feature_text}
+
+Rules:
+- Break the feature into 2 to 6 sequential checkpoints, ordered so each one builds on the ones before it and can be developed and reviewed in isolation.
+- Each checkpoint must be project-agnostic: do not assume a specific language, framework, build tool, or test command unless the feature description names one.
+- Each checkpoint needs a short unique id (e.g. "phase0", "phase1", ...), a short name, a "scope" describing exactly what to build, and an "exit_criteria" list of objective, independently verifiable conditions. Do not use vague criteria like "code is clean" or "works well".
+- Do not include "status", "attempts", or "review_notes" fields; they are assigned automatically.
+- Output ONLY a single JSON object and nothing else: no prose, no explanation, no markdown headings, before or after it. You may wrap the JSON in a single ```json code fence, or output raw JSON with no fence at all — never mix prose with either form.
+
+Output JSON shape exactly:
+{{
+  "checkpoints": [
+    {{"id": "phase0", "name": "...", "scope": "...", "exit_criteria": ["...", "..."]}}
+  ]
+}}
+"""
+
+
+def build_init_prompt(feature_text: str) -> str:
+    """Build the strict, JSON-only planning prompt for `feature_text`."""
+    return INIT_PROMPT_TEMPLATE.format(feature_text=feature_text)
+
+
+# ---------------------------------------------------------------------------
+# Parsing: raw JSON or a single Markdown-fenced JSON block, nothing else.
+# ---------------------------------------------------------------------------
+
+_FENCE_RE = re.compile(r"\A```(?:json)?\s*\n(?P<body>.*?)\n```\s*\Z", re.DOTALL)
+
+
+def parse_plan_json(raw_output: str) -> Any:
+    """Parse `raw_output` as raw JSON or as a single ```json fenced block.
+
+    Rejects empty output, output that mixes prose with a fence (or has more
+    than one fence), and invalid JSON — always with a `PlanOutputParseError`
+    describing why.
+    """
+    text = raw_output.strip()
+    if not text:
+        raise PlanOutputParseError("Provider produced no output")
+
+    fence_count = text.count("```")
+    if fence_count == 0:
+        candidate = text
+    elif fence_count == 2:
+        fence_match = _FENCE_RE.match(text)
+        if not fence_match:
+            raise PlanOutputParseError(
+                "Provider output mixes prose with a code fence; expected raw "
+                "JSON or a single JSON code fence with nothing else outside it"
+            )
+        candidate = fence_match.group("body")
+    else:
+        raise PlanOutputParseError(
+            "Provider output contains more than one code fence; expected raw "
+            "JSON or a single JSON code fence"
+        )
+
+    try:
+        return json.loads(candidate)
+    except json.JSONDecodeError as e:
+        raise PlanOutputParseError(f"Provider output is not valid JSON: {e}") from e
+
+
+REQUIRED_CHECKPOINT_INPUT_FIELDS = ("id", "name", "scope", "exit_criteria")
+
+
+def normalize_checkpoints(data: Any) -> list[dict]:
+    """Extract and normalize checkpoints from parsed provider JSON.
+
+    Accepts either `{"checkpoints": [...]}` or a bare `[...]` list. Each
+    checkpoint is rebuilt with `new_checkpoint` so status/attempts/review_notes
+    always start canonical, regardless of what the provider returned.
+    """
+    checkpoints = data.get("checkpoints") if isinstance(data, dict) else data
+
+    if not isinstance(checkpoints, list) or not checkpoints:
+        raise PlanOutputParseError(
+            "Provider output must contain a non-empty 'checkpoints' list"
+        )
+
+    normalized: list[dict] = []
+    for idx, cp in enumerate(checkpoints):
+        if not isinstance(cp, dict):
+            raise PlanOutputParseError(f"checkpoint #{idx} must be a JSON object")
+        missing = [f for f in REQUIRED_CHECKPOINT_INPUT_FIELDS if f not in cp]
+        if missing:
+            raise PlanOutputParseError(
+                f"checkpoint #{idx} is missing required field(s): {', '.join(missing)}"
+            )
+        if not isinstance(cp["exit_criteria"], list):
+            raise PlanOutputParseError(
+                f"checkpoint #{idx} ('{cp.get('id')}'): 'exit_criteria' must be a list"
+            )
+        normalized.append(
+            new_checkpoint(cp["id"], cp["name"], cp["scope"], cp["exit_criteria"])
+        )
+    return normalized
+
+
+def generate_plan_json(provider: Provider, feature_text: str, timeout: int) -> Any:
+    """Run the init prompt through `provider` and parse its captured output.
+
+    Composes `run_provider_captured` with `parse_plan_json`. Callers combine
+    the result with `normalize_checkpoints` and `build_generated_payload` to
+    get a payload ready for `validate_generated_payload`.
+    """
+    prompt = build_init_prompt(feature_text)
+    stdout = run_provider_captured(provider, prompt, timeout)
+    return parse_plan_json(stdout)

agent_loop/providers/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .base import Provider, ProviderError
+
+PROVIDERS: dict[str, type[Provider]] = {}
+
+
+def register(cls: type[Provider]) -> type[Provider]:
+    PROVIDERS[cls.name] = cls
+    return cls
+
+
+def get_provider(name: str, model: Optional[str] = None) -> Provider:
+    if name not in PROVIDERS:
+        known = ", ".join(sorted(PROVIDERS)) or "<none>"
+        raise ProviderError(f"Unknown provider '{name}'. Known: {known}")
+    return PROVIDERS[name](model)
+
+
+def known_provider_names() -> list[str]:
+    return sorted(PROVIDERS)
+
+
+# Importing the concrete modules triggers @register side effects.
+from . import antigravity as _antigravity  # noqa: E402, F401
+from . import claude as _claude  # noqa: E402, F401
+from . import codex as _codex  # noqa: E402, F401
+from . import grok as _grok  # noqa: E402, F401