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

agent_loop/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agent_loop/audit.py

@@ -0,0 +1,128 @@
+"""Controls how much of an agent's raw output reaches the committed log.
+
+Run logs are git-committed audit artifacts (see `git_ops.commit_checkpoint_changes`),
+which makes anything written to them effectively permanent — much harder to walk
+back than a `/tmp` file. `--audit-level` trades completeness of that record
+against exposure of whatever the developer/reviewer agents happen to print or
+write while doing their work:
+
+- ``full``:     nothing is touched. Agent output and agent-authored free text
+                (prompts, review notes) are logged exactly as produced.
+- ``redacted``: known secret *shapes* (AWS keys, GitHub/Slack/OpenAI tokens,
+                bearer tokens, PEM private key blocks, `key: value`-style
+                assignments) are scrubbed before anything is printed or logged.
+                This is a best-effort net, not a guarantee — it cannot catch a
+                project's own custom secret formats, and it runs on live,
+                streamed subprocess output rather than a byte buffer, so a
+                secret split across two flushed writes can slip through.
+- ``off``:      raw agent output and agent-authored free text are not printed
+                or logged at all. Only structured event metadata (which agent
+                ran, what was approved, what was committed) reaches the log.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+AUDIT_LEVELS = ("full", "redacted", "off")
+DEFAULT_AUDIT_LEVEL = "off"
+
+_ENV_VAR = "AGENT_LOOP_AUDIT_LEVEL"
+
+
+class InvalidAuditLevel(ValueError):
+    pass
+
+
+def default_audit_level() -> str:
+    """The configured level: env override if set and valid, else the default."""
+    configured = os.environ.get(_ENV_VAR)
+    if not configured:
+        return DEFAULT_AUDIT_LEVEL
+    validate(configured)
+    return configured
+
+
+def validate(level: str) -> None:
+    if level not in AUDIT_LEVELS:
+        raise InvalidAuditLevel(
+            f"Invalid audit level {level!r}; must be one of {', '.join(AUDIT_LEVELS)}."
+        )
+
+
+_PRIVATE_KEY_BLOCK = re.compile(
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----",
+    re.DOTALL,
+)
+_PRIVATE_KEY_BEGIN = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")
+_PRIVATE_KEY_END = re.compile(r"-----END [A-Z ]*PRIVATE KEY-----")
+
+# High-confidence secret shapes only — anything looser produces enough false
+# positives to make "redacted" logs unreadable without meaningfully raising
+# recall. checked in order; each substitution runs on the previous pass's output.
+_LINE_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("aws-access-key-id", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("github-token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b")),
+    ("slack-token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")),
+    ("openai-key", re.compile(r"\bsk-[A-Za-z0-9]{20,}\b")),
+    ("bearer-token", re.compile(r"(?i)\bBearer\s+[A-Za-z0-9\-_.]{20,}")),
+    (
+        "assigned-secret",
+        re.compile(
+            r"""(?ix)
+            \b(api[_-]?key|secret|token|password|passwd)\b
+            \s*[:=]\s*
+            ['"]?[^\s'"]{6,}['"]?
+            """
+        ),
+    ),
+]
+
+
+def redact(text: str) -> str:
+    """Best-effort scrub of common secret shapes from a complete string.
+
+    Suitable for whole values already assembled in memory — prompts, review
+    notes, checkpoint comments. For output arriving line-by-line from a live
+    subprocess, use `StreamRedactor` instead so a PEM block split across
+    lines is still caught.
+    """
+    text = _PRIVATE_KEY_BLOCK.sub("[REDACTED:private-key-block]", text)
+    for name, pattern in _LINE_PATTERNS:
+        text = pattern.sub(f"[REDACTED:{name}]", text)
+    return text
+
+
+class StreamRedactor:
+    """Applies `redact` to output arriving one line at a time.
+
+    Holds just enough state to span a PEM private-key block across multiple
+    `feed_line` calls, which a single-call `redact(text)` on each line in
+    isolation cannot do.
+    """
+
+    def __init__(self) -> None:
+        self._in_private_key = False
+
+    def feed_line(self, line: str) -> str:
+        if self._in_private_key:
+            if _PRIVATE_KEY_END.search(line):
+                self._in_private_key = False
+            return ""
+
+        if _PRIVATE_KEY_BLOCK.search(line):
+            return redact(line)  # BEGIN and END both landed on one line
+        if _PRIVATE_KEY_BEGIN.search(line):
+            self._in_private_key = True
+            return "[REDACTED:private-key-block]\n"
+
+        return redact(line)
+
+
+def prepare_text(text: str, audit_level: str) -> str:
+    """Apply an audit level to a complete piece of agent-authored text."""
+    if audit_level == "off":
+        return f"<suppressed by audit-level=off: {len(text)} chars>"
+    if audit_level == "redacted":
+        return redact(text)
+    return text

agent_loop/cli.py

@@ -0,0 +1,354 @@
+"""agent-loop command-line interface."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from . import audit, plan_init, safety
+from .orchestrator import LoopHalted, run_loop
+from .providers import get_provider, known_provider_names
+from .providers.base import ProviderError
+from .state import PROTECTED_BRANCHES, InvalidPlanState, load_state
+
+DEFAULT_STATE = Path("plan_checkpoints.json")
+
+
+def _add_state_arg(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--state",
+        type=Path,
+        default=DEFAULT_STATE,
+        help=f"Path to plan_checkpoints.json (default: {DEFAULT_STATE})",
+    )
+
+
+def positive_int(value: str) -> int:
+    """argparse type for counts and timeouts: a zero/negative one can never succeed.
+
+    Named without a leading underscore because argparse builds its rejection
+    message from `__name__` ("invalid positive_int value: 'abc'").
+    """
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return parsed
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-loop",
+        description="Checkpoint-gated developer/reviewer loop across coding-agent CLIs.",
+    )
+    sub = parser.add_subparsers(dest="cmd")
+
+    run = sub.add_parser("run", help="Run the developer/reviewer loop.")
+    _add_state_arg(run)
+    run.add_argument(
+        "--developer",
+        choices=known_provider_names(),
+        default="claude",
+        help="CLI to play the developer role (default: claude).",
+    )
+    run.add_argument(
+        "--reviewer",
+        choices=known_provider_names(),
+        default="codex",
+        help="CLI to play the reviewer role (default: codex).",
+    )
+    run.add_argument(
+        "--developer-model",
+        default=None,
+        help="Model for the developer CLI. Overrides plan 'models.developer'; "
+        "if neither is set, the CLI picks its own default.",
+    )
+    run.add_argument(
+        "--reviewer-model",
+        default=None,
+        help="Model for the reviewer CLI. Overrides plan 'models.reviewer'; "
+        "if neither is set, the CLI picks its own default.",
+    )
+    run.add_argument("--max-review-attempts", type=positive_int, default=3)
+    run.add_argument(
+        "--timeout",
+        type=positive_int,
+        default=1800,
+        help="Per-agent-call timeout in seconds.",
+    )
+    run.add_argument("--log-dir", type=Path, default=None)
+    run.add_argument(
+        "--audit-level",
+        choices=audit.AUDIT_LEVELS,
+        default=None,
+        help="How much of the agents' output is committed to the run log: "
+        "'full' logs it as-is, 'redacted' scrubs known secret shapes first, "
+        "'off' logs only structured events (no raw agent output or notes). "
+        "Defaults to $AGENT_LOOP_AUDIT_LEVEL, or 'off' if that is unset — "
+        "logs are git-committed audit artifacts, so this leans safe by "
+        "default. Neither 'redacted' nor 'off' is a compliance guarantee; "
+        "see README for what each level actually does.",
+    )
+
+    validate = sub.add_parser("validate", help="Schema-check the state file.")
+    _add_state_arg(validate)
+
+    status = sub.add_parser("status", help="One-line summary of each checkpoint.")
+    _add_state_arg(status)
+
+    init = sub.add_parser(
+        "init",
+        help="Generate plan_checkpoints.json from a feature description or Markdown file.",
+    )
+    init.add_argument(
+        "feature",
+        nargs="?",
+        default=None,
+        help="Plain-English feature description (mutually exclusive with --feature-file).",
+    )
+    init.add_argument(
+        "--feature-file",
+        type=Path,
+        default=None,
+        help="Path to a Markdown file describing the feature.",
+    )
+    _add_state_arg(init)
+    init.add_argument(
+        "--branch",
+        default=None,
+        help="Target branch (default: sanitized feature/<slug>).",
+    )
+    init.add_argument(
+        "--plan-file",
+        default=None,
+        help="'plan_file' recorded in the state (default: the --feature-file path, or "
+        f"{plan_init.DEFAULT_PLAN_FILE} for plain-English input).",
+    )
+    init.add_argument(
+        "--provider",
+        choices=known_provider_names(),
+        default="claude",
+        help="CLI used to generate the plan (default: claude).",
+    )
+    init.add_argument("--model", default=None, help="Model for the planning CLI.")
+    init.add_argument(
+        "--timeout",
+        type=positive_int,
+        default=1800,
+        help="Provider call timeout in seconds.",
+    )
+    init.add_argument(
+        "--force", action="store_true", help="Overwrite an existing state file."
+    )
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Command implementations
+# ---------------------------------------------------------------------------
+
+
+def _cmd_validate(args) -> int:
+    try:
+        state = load_state(args.state)
+    except InvalidPlanState as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    print(f"OK  {args.state} ({len(state.checkpoints)} checkpoints, branch={state.branch})")
+    for cp in state.checkpoints:
+        print(f"  {cp['id']:10s} {cp['status']:9s} {cp['name']}")
+    return 0
+
+
+def _cmd_status(args) -> int:
+    try:
+        state = load_state(args.state)
+    except InvalidPlanState as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    print(f"branch={state.branch}  plan={state.plan_file}  state={args.state}")
+    for cp in state.checkpoints:
+        attempts = cp.get("attempts", 0)
+        print(f"  {cp['id']:10s} {cp['status']:9s} attempts={attempts}  {cp['name']}")
+    return 0
+
+
+def _cmd_run(args) -> int:
+    try:
+        state = load_state(args.state)
+    except InvalidPlanState as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    # Precedence per role: CLI flag > plan 'models.<role>' > the CLI's default.
+    dev_model = args.developer_model or state.model_for("developer")
+    rev_model = args.reviewer_model or state.model_for("reviewer")
+
+    try:
+        dev = get_provider(args.developer, dev_model)
+        rev = get_provider(args.reviewer, rev_model)
+    except ProviderError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        dev.preflight()
+        rev.preflight()
+        safety.require_auto_mode_gates([dev, rev])
+    except (ProviderError, safety.AutoModeGateError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        audit_level = args.audit_level or audit.default_audit_level()
+    except audit.InvalidAuditLevel as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    log_dir = args.log_dir or safety.default_log_dir()
+    log_path = safety.open_log_file(log_dir)
+    safety.tee_stdout_to(log_path)
+    def _role(p) -> str:
+        return f"{p.name}({p.model})" if p.model else p.name
+
+    print(
+        f"### agent-loop | developer={_role(dev)} reviewer={_role(rev)} "
+        f"log={log_path} audit-level={audit_level}"
+    )
+
+    try:
+        with safety.lockfile(safety.default_lock_path()):
+            run_loop(
+                state_path=args.state,
+                developer=dev,
+                reviewer=rev,
+                max_review_attempts=args.max_review_attempts,
+                timeout=args.timeout,
+                log_dir=log_dir,
+                audit_level=audit_level,
+            )
+    except safety.LockHeld as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    except LoopHalted as e:
+        print(f"halted: {e}", file=sys.stderr)
+        return 1
+    except InvalidPlanState as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _cmd_init(args) -> int:
+    # Which source was *supplied*, not which one turned out to be usable: an
+    # empty FEATURE alongside --feature-file is ambiguous input, not a
+    # single-source invocation.
+    have_text = args.feature is not None
+    have_file = args.feature_file is not None
+
+    if have_text and have_file:
+        print(
+            "error: provide a feature description or --feature-file, not both",
+            file=sys.stderr,
+        )
+        return 2
+    if not have_text and not have_file:
+        print(
+            "error: provide a feature description or --feature-file",
+            file=sys.stderr,
+        )
+        return 2
+
+    feature_text = (args.feature or "").strip()
+    if have_text and not feature_text:
+        print("error: feature description is empty", file=sys.stderr)
+        return 2
+
+    if have_file:
+        if not args.feature_file.is_file():
+            print(f"error: feature file not found: {args.feature_file}", file=sys.stderr)
+            return 2
+        feature_text = args.feature_file.read_text().strip()
+        if not feature_text:
+            print(f"error: feature file is empty: {args.feature_file}", file=sys.stderr)
+            return 2
+        slug_source = args.feature_file.stem
+        default_plan_file = str(args.feature_file)
+    else:
+        slug_source = feature_text
+        default_plan_file = plan_init.DEFAULT_PLAN_FILE
+
+    branch = args.branch or f"feature/{plan_init.slugify(slug_source)}"
+    plan_file = args.plan_file or default_plan_file
+
+    if branch in PROTECTED_BRANCHES:
+        print(f"error: refusing protected target branch: {branch}", file=sys.stderr)
+        return 2
+
+    if args.state.exists() and not args.force:
+        print(
+            f"error: {args.state} already exists; use --force to overwrite",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        provider = get_provider(args.provider, args.model)
+        provider.preflight()
+    except ProviderError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        data = plan_init.generate_plan_json(provider, feature_text, args.timeout)
+        checkpoints = plan_init.normalize_checkpoints(data)
+        payload = plan_init.build_generated_payload(plan_file, branch, checkpoints)
+        plan_init.validate_generated_payload(payload)
+    except (
+        plan_init.ProviderExecutionError,
+        plan_init.PlanOutputParseError,
+        InvalidPlanState,
+    ) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        plan_init.write_generated_payload(args.state, payload, force=args.force)
+    except plan_init.StateFileExistsError:
+        # Only reachable if the file appeared after the check above.
+        print(
+            f"error: {args.state} already exists; use --force to overwrite",
+            file=sys.stderr,
+        )
+        return 2
+    except OSError as e:
+        print(f"error: unable to write {args.state}: {e}", file=sys.stderr)
+        return 2
+
+    print(
+        f"wrote {args.state} (branch={branch}, plan_file={plan_file}, "
+        f"{len(checkpoints)} checkpoints)"
+    )
+    return 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.cmd == "run":
+        return _cmd_run(args)
+    if args.cmd == "validate":
+        return _cmd_validate(args)
+    if args.cmd == "status":
+        return _cmd_status(args)
+    if args.cmd == "init":
+        return _cmd_init(args)
+    parser.print_help(sys.stderr)
+    raise SystemExit(2)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

agent_loop/git_ops.py

@@ -0,0 +1,127 @@
+"""Git operations the orchestrator relies on."""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from .state import PROTECTED_BRANCHES
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def _log_commit_statement(*, message: str, status: str, commit_hash: str | None) -> None:
+    """Print a commit outcome that is mirrored into the active loop log."""
+    fields = {
+        "commit_hash": commit_hash,
+        "event": "COMMIT_STATEMENT",
+        "message": message,
+        "status": status,
+    }
+    print(
+        f"[agent-loop] COMMIT_STATEMENT {json.dumps(fields, sort_keys=True)}",
+        flush=True,
+    )
+
+
+def _run(args: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(args, capture_output=True, text=True, check=check)
+
+
+def repo_root() -> Path:
+    res = _run(["git", "rev-parse", "--show-toplevel"], check=False)
+    if res.returncode != 0:
+        raise GitError("Not a git repository")
+    return Path(res.stdout.strip())
+
+
+def current_branch() -> str:
+    return _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+
+
+def ensure_branch(branch: str) -> None:
+    if branch in PROTECTED_BRANCHES:
+        raise GitError(f"Refusing protected branch: {branch}")
+    repo_root()  # raises if not a repo
+    if current_branch() == branch:
+        return
+    exists = _run(["git", "rev-parse", "--verify", branch], check=False).returncode == 0
+    if exists:
+        _run(["git", "checkout", branch])
+    else:
+        _run(["git", "checkout", "-b", branch])
+
+
+def _relative_log_prefix(log_dir: Path | None) -> str | None:
+    """Return the repo-relative ``logs/`` prefix, or None if not inside the repo.
+
+    Raises GitError if log_dir is the repository root itself, as that would
+    bypass all security checks by matching every file in the working tree.
+    """
+    if log_dir is None:
+        return None
+    try:
+        rel = log_dir.resolve().relative_to(repo_root().resolve())
+    except (ValueError, GitError):
+        return None
+    if str(rel) == ".":
+        raise GitError(
+            "Log directory cannot be the repository root itself. "
+            "Use a subdirectory like 'logs/' instead."
+        )
+    return f"{rel}/"
+
+
+def require_clean_worktree(log_dir: Path | None = None) -> None:
+    """Refuse to start on a dirty worktree, tolerating the loop's own log files.
+
+    Logs are committed as audit artifacts, so a log file from a previous run is
+    both *tracked* and *modified* by the time the next run starts: the tee keeps
+    appending after the final commit of the run that created it. Untracked logs
+    (a brand new run) and modified logs (that trailing tail) are therefore both
+    expected, and neither should block the loop.
+    """
+    res = _run(["git", "status", "--porcelain", "--untracked-files=all"])
+    lines = [ln for ln in res.stdout.splitlines() if ln.strip()]
+
+    prefix = _relative_log_prefix(log_dir)
+    if prefix is not None:
+        # Porcelain v1 status codes are two columns followed by a space, so the
+        # path starts at index 3. Paths containing spaces or other special
+        # characters come back double-quoted.
+        lines = [ln for ln in lines if not ln[3:].lstrip('"').startswith(prefix)]
+
+    if lines:
+        raise GitError(
+            "Worktree must be clean before running the loop.\n"
+            "Outstanding changes:\n" + "\n".join(lines)
+        )
+
+
+#: Log directories already warned about, so a multi-checkpoint run says it once.
+_WARNED_EXTERNAL_LOG_DIRS: set[str] = set()
+
+
+def commit_checkpoint_changes(message: str, log_dir: Path) -> None:
+    if _relative_log_prefix(log_dir) is None:
+        key = str(log_dir)
+        if key not in _WARNED_EXTERNAL_LOG_DIRS:
+            _WARNED_EXTERNAL_LOG_DIRS.add(key)
+            print(
+                f"[agent-loop] WARNING: log directory {log_dir} is outside the "
+                "repository; run logs will not be committed as audit artifacts.",
+                flush=True,
+            )
+
+    _run(["git", "add", "-A"])
+
+    cached = _run(["git", "diff", "--cached", "--quiet"], check=False)
+    if cached.returncode == 0:
+        _log_commit_statement(message=message, status="no_changes", commit_hash=None)
+        return
+
+    _run(["git", "commit", "-m", message, "--quiet"])
+    commit_hash = _run(["git", "rev-parse", "HEAD"]).stdout.strip()
+    _log_commit_statement(message=message, status="committed", commit_hash=commit_hash)