cli-agent-runner 0.1.0__py3-none-any.whl

agent_runner/runner.py

@@ -0,0 +1,236 @@
+"""Main round orchestration. Conducts the other modules; does not touch
+subprocess / git / prompt details directly. Pure rotation — no event-driven
+branches based on prior round state (§7 IMMUTABLE).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from agent_runner import (
+    agent_runtime,
+    context_store,
+    events,
+    metrics,
+    prompt_loader,
+    startup_check,
+    vcs_state,
+)
+from agent_runner.config import Config
+from agent_runner.events import now_iso_ms
+
+
+class LockHeldError(RuntimeError):
+    pass
+
+
+def _acquire_lock_or_raise(lock_path: Path) -> int:
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError as e:
+        os.close(fd)
+        raise LockHeldError(f"another agent-runner is holding {lock_path}") from e
+    return fd
+
+
+@dataclass(frozen=True)
+class RoundResult:
+    round_num: int
+    exit_code: int
+    duration_s: float
+    timed_out: bool
+    dirty_files: list[str]
+    stashed: bool
+
+
+def _phase_for(round_num: int, phases: list[str] | None) -> tuple[str | None, int]:
+    if not phases:
+        return None, 0
+    idx = (round_num - 1) % len(phases)
+    return phases[idx], idx
+
+
+def _previous_block(prev: context_store.Status | None, dirty_last: bool) -> dict[str, Any] | None:
+    if prev is None:
+        return None
+    return {
+        "exit_code": prev.last_exit_code,
+        "duration_s": prev.last_duration_s,
+        "ended_at": prev.last_completed_at,
+        "had_dirty_tree": dirty_last,
+    }
+
+
+def _round_context_for_prompt(
+    round_num: int,
+    started_at: str,
+    phase: str | None,
+    orphan_block: dict[str, Any] | None,
+) -> dict[str, Any]:
+    ctx: dict[str, Any] = {"round_num": round_num, "started_at": started_at}
+    if phase is not None:
+        ctx["phase"] = phase
+    if orphan_block is not None:
+        ctx["orphan_stash"] = orphan_block
+    return ctx
+
+
+def run_one_round(cfg: Config) -> RoundResult:
+    log_dir = cfg.runtime.log_dir
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # L3: startup precondition battery (R721 + #446 defense)
+    failures = [r for r in startup_check.run_battery(cfg) if not r.ok]
+    if failures:
+        for r in failures:
+            print(
+                f"STARTUP FAIL: {r.name}: {r.reason} | how-to-fix: {r.how_to_fix}",
+                file=sys.stderr,
+            )
+            events.emit(log_dir, "smoke_check_failed", reason=f"{r.name}: {r.reason}")
+        sys.exit(1)
+
+    # Concurrency lock (per-project)
+    lock_fd = _acquire_lock_or_raise(log_dir / "agent-runner.lock")
+    try:
+        return _run_one_round_inner(cfg)
+    finally:
+        os.close(lock_fd)
+
+
+def _run_one_round_inner(cfg: Config) -> RoundResult:
+    log_dir = cfg.runtime.log_dir
+
+    prev_status = context_store.read_status(log_dir)
+    if (log_dir / "status.json").exists() and prev_status is None:
+        events.emit(log_dir, "status_recovered", reason="status.json could not be parsed")
+
+    round_num = (prev_status.round_num if prev_status else 0) + 1
+    phase, phase_idx = _phase_for(round_num, cfg.phases)
+    started_at = now_iso_ms()
+
+    orphan = context_store.read_orphan_state(log_dir)
+    orphan_block: dict[str, Any] | None = None
+    if orphan and orphan.stashed_ref:
+        orphan_block = {
+            "ref": orphan.stashed_ref,
+            "message": orphan.stash_message,
+            "files": orphan.files,
+        }
+
+    previous_block = _previous_block(prev_status, dirty_last=bool(orphan))
+
+    context_store.write_round_context(
+        log_dir,
+        round_num=round_num,
+        started_at=started_at,
+        phase=phase,
+        previous=previous_block,
+        orphan_stash=orphan_block,
+    )
+    events.emit(log_dir, "round_start", round_num=round_num, phase=phase)
+    metrics.log_metrics(log_dir, event="round_start", round_num=round_num, phase=phase)
+
+    rounds_dir = log_dir / "rounds"
+    rounds_dir.mkdir(exist_ok=True)
+    log_path = rounds_dir / f"R{round_num}-{datetime.now(UTC).strftime('%Y%m%dT%H%M%S')}.log"
+
+    prompt = prompt_loader.assemble_prompt(
+        cfg.prompt.file,
+        context=_round_context_for_prompt(round_num, started_at, phase, orphan_block),
+        inject_context=cfg.prompt.inject_context,
+    )
+
+    events.emit(log_dir, "agent_spawn", round_num=round_num, timeout_s=cfg.runtime.round_timeout_s)
+    result = agent_runtime.run(
+        command=cfg.agent.command,
+        prompt_arg_template=cfg.agent.prompt_arg_template,
+        prompt=prompt,
+        timeout_s=cfg.runtime.round_timeout_s,
+        log_path=log_path,
+        env_extra=agent_runtime.merge_critical_envs({}),
+    )
+    events.emit(
+        log_dir,
+        "agent_exit",
+        round_num=round_num,
+        exit_code=result.exit_code,
+        duration_s=result.duration_s,
+        timed_out=result.timed_out,
+    )
+
+    dirty = vcs_state.detect_dirty_files(cfg.runtime.work_dir)
+    if dirty:
+        events.emit(log_dir, "dirty_detected", round_num=round_num, files=dirty[:20])
+
+    stashed = False
+    if dirty and not result.timed_out and result.exit_code == 0:
+        ref = vcs_state.stash_orphan(
+            cfg.runtime.work_dir,
+            round_num=round_num,
+            phase=phase,
+            idempotency_s=cfg.vcs.stash_idempotency_s,
+        )
+        if ref is not None:
+            context_store.write_orphan_state(
+                log_dir,
+                context_store.OrphanState(
+                    round_num=round_num,
+                    files=dirty,
+                    stashed_ref=ref.sha,
+                    stash_message=ref.message,
+                    timestamp=now_iso_ms(),
+                    phase=phase,
+                ),
+            )
+            events.emit(
+                log_dir,
+                "orphan_stashed",
+                round_num=round_num,
+                ref=ref.sha,
+                reason="clean_exit_with_dirty_tree",
+            )
+            stashed = True
+    elif not dirty:
+        context_store.clear_orphan_state(log_dir)
+
+    if result.timed_out:
+        events.emit(
+            log_dir,
+            "round_timeout_kill",
+            round_num=round_num,
+            reason=f"exceeded round_timeout_s={cfg.runtime.round_timeout_s}",
+        )
+
+    completed_at = now_iso_ms()
+    context_store.write_status(
+        log_dir,
+        context_store.Status(
+            round_num=round_num,
+            running=False,
+            last_completed_at=completed_at,
+            last_exit_code=result.exit_code,
+            last_duration_s=result.duration_s,
+            current_phase=phase,
+            phase_index=phase_idx,
+        ),
+    )
+    metrics.log_metrics(log_dir, event="round_end", round_num=round_num, phase=phase)
+    events.emit(log_dir, "round_end", round_num=round_num)
+
+    return RoundResult(
+        round_num=round_num,
+        exit_code=result.exit_code,
+        duration_s=result.duration_s,
+        timed_out=result.timed_out,
+        dirty_files=dirty,
+        stashed=stashed,
+    )

agent_runner/scaffold.py

@@ -0,0 +1,124 @@
+"""Project scaffold for `agent-runner init`.
+
+Writes three files into a git repo:
+  agent-runner.toml      — copy of example template, project name substituted
+  prompts/main.md        — neutral 8-line placeholder
+  .gitignore             — append "logs/" if missing
+
+Optionally commits in one step (default true via the CLI).
+"""
+
+from __future__ import annotations
+
+import subprocess  # noqa: TID251 — scaffold needs git for the commit step
+from pathlib import Path
+
+from agent_runner.api_types import InitResult
+from agent_runner.vcs_state import is_git_repo
+
+_TOML_TEMPLATE = """\
+# agent-runner.toml — generated by `agent-runner init`. Edit fields as needed.
+
+[agent]
+command = ["claude", "--model", "claude-opus-4-7",
+           "--dangerously-skip-permissions",
+           "--verbose", "--output-format", "stream-json"]
+prompt_arg_template = ["-p", "{prompt}"]
+
+[runtime]
+work_dir = "."
+log_dir = "~/.agent-runner/{project}/logs"
+round_timeout_s = 1800
+restart_delay_s = 3
+
+[prompt]
+file = "./prompts/main.md"
+inject_context = true
+
+# [phases]                # optional — uncomment for phase rotation
+# list = ["diverge", "converge", "refine"]
+
+[vcs]
+orphan_action = "stash"
+stash_idempotency_s = 5
+
+# [monitor]               # optional — auto-stop policy overrides
+# auto_stop_on = ["oauth_fail", "disk_critical"]
+# disk_warning_pct = 90.0
+# disk_critical_pct = 95.0
+
+# [llm]                   # Phase 3 — reserved, not yet used
+# endpoint = "anthropic"
+# api_key_env = "ANTHROPIC_API_KEY"
+# model = "claude-haiku-4-5"
+"""
+
+_PROMPT_TEMPLATE = """\
+# Agent Prompt
+
+You are an autonomous agent working on this project. Each round begins with a
+`round-context` JSON block prepended above this prompt — read it first.
+
+If `round_num == 1`: orient yourself with the project structure (README, file tree).
+If `previous.exit_code != 0`: investigate what went wrong before resuming.
+If `orphan_stash` is present: decide salvage (`git stash pop`) or abandon (`git stash drop`).
+
+Always: commit and push your work before exiting the round. The supervisor will
+auto-stash if you forget, but explicit commits with meaningful messages are better.
+"""
+
+_GITIGNORE_LINE = "logs/"
+
+
+def scaffold_project(work_dir: Path, *, force: bool, commit: bool) -> InitResult:
+    if not is_git_repo(work_dir):
+        raise RuntimeError(f"{work_dir} is not a git working tree — run `git init` first")
+
+    toml_path = work_dir / "agent-runner.toml"
+    prompt_dir = work_dir / "prompts"
+    prompt_path = prompt_dir / "main.md"
+    gitignore_path = work_dir / ".gitignore"
+
+    if toml_path.exists() and not force:
+        raise FileExistsError(f"{toml_path} already exists; pass force=True to overwrite")
+
+    files_created: list[Path] = []
+
+    project = work_dir.resolve().name or "default"
+    toml_path.write_text(_TOML_TEMPLATE.replace("{project}", project))
+    files_created.append(toml_path)
+
+    prompt_dir.mkdir(parents=True, exist_ok=True)
+    if not prompt_path.exists() or force:
+        prompt_path.write_text(_PROMPT_TEMPLATE)
+        files_created.append(prompt_path)
+
+    existing = gitignore_path.read_text() if gitignore_path.exists() else ""
+    if _GITIGNORE_LINE not in existing.splitlines():
+        new_text = existing
+        if existing and not existing.endswith("\n"):
+            new_text += "\n"
+        new_text += _GITIGNORE_LINE + "\n"
+        gitignore_path.write_text(new_text)
+        files_created.append(gitignore_path)
+
+    committed = False
+    if commit:
+        subprocess.run(["git", "add", "."], cwd=work_dir, check=True)
+        r = subprocess.run(
+            [
+                "git",
+                "-c",
+                "commit.gpgsign=false",
+                "commit",
+                "-q",
+                "-m",
+                "chore: agent-runner initial config",
+            ],
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+        )
+        committed = r.returncode == 0  # may fail if nothing changed
+
+    return InitResult(work_dir=work_dir, files_created=files_created, committed=committed)

agent_runner/service_unit.py

@@ -0,0 +1,74 @@
+"""systemd user-unit content generators for serve and monitor.
+
+Two units per project:
+  agent-runner@<project>.service          - runs `agent-runner serve`
+  agent-runner-monitor@<project>.service  - runs `agent-runner monitor`
+
+Install command writes these to ~/.config/systemd/user/. The graceful-stop
+contract relies on KillSignal=SIGTERM + TimeoutStopSec=round_timeout_s+60.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_runner.config import Config
+
+_GRACE_S = 60
+
+
+def serve_unit_filename(project: str) -> str:
+    return f"agent-runner@{project}.service"
+
+
+def monitor_unit_filename(project: str) -> str:
+    return f"agent-runner-monitor@{project}.service"
+
+
+def _config_path(cfg: Config) -> Path:
+    """Where the config TOML lives (always relative to work_dir for now)."""
+    return cfg.runtime.work_dir / "agent-runner.toml"
+
+
+def render_serve_unit(cfg: Config, *, venv_bin: Path) -> str:
+    """Generate the serve systemd unit body."""
+    timeout_total = cfg.runtime.round_timeout_s + _GRACE_S
+    return (
+        f"[Unit]\n"
+        f"Description=Agent Runner Supervisor ({cfg.runtime.work_dir.name})\n"
+        f"After=network.target\n"
+        f"\n"
+        f"[Service]\n"
+        f"Type=simple\n"
+        f"WorkingDirectory={cfg.runtime.work_dir}\n"
+        f"ExecStart={venv_bin}/agent-runner serve "
+        f"--config {_config_path(cfg)}\n"
+        f"Restart=always\n"
+        f"RestartSec=3\n"
+        f"KillSignal=SIGTERM\n"
+        f"TimeoutStopSec={timeout_total}\n"
+        f"\n"
+        f"[Install]\n"
+        f"WantedBy=default.target\n"
+    )
+
+
+def render_monitor_unit(cfg: Config, *, venv_bin: Path) -> str:
+    """Generate the monitor sidekick systemd unit body."""
+    return (
+        f"[Unit]\n"
+        f"Description=Agent Runner Monitor ({cfg.runtime.work_dir.name})\n"
+        f"After=network.target "
+        f"agent-runner@{cfg.runtime.work_dir.name}.service\n"
+        f"\n"
+        f"[Service]\n"
+        f"Type=simple\n"
+        f"WorkingDirectory={cfg.runtime.work_dir}\n"
+        f"ExecStart={venv_bin}/agent-runner monitor "
+        f"--config {_config_path(cfg)}\n"
+        f"Restart=always\n"
+        f"RestartSec=10\n"
+        f"\n"
+        f"[Install]\n"
+        f"WantedBy=default.target\n"
+    )

agent_runner/startup_check.py

@@ -0,0 +1,132 @@
+"""Boot-time precondition battery. R721 + #446 lesson — fail loud before
+spawning the agent so we never silent-burn rounds on broken config.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from agent_runner.config import Config
+from agent_runner.prompt_loader import assemble_prompt
+
+ESCAPE_HATCH_ENV = "AGENT_RUNNER_SKIP_STARTUP_CHECK"
+
+_MIN_PROMPT_BYTES = 500
+_FORBIDDEN_FIRST_CHARS = frozenset({"-", " ", "\n", "\t", "\r"})
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    ok: bool
+    reason: str = ""
+    how_to_fix: str = ""
+
+
+def _check_log_dir(cfg: Config) -> CheckResult:
+    try:
+        cfg.runtime.log_dir.mkdir(parents=True, exist_ok=True)
+        probe = cfg.runtime.log_dir / ".write_probe"
+        probe.write_text("x")
+        probe.unlink()
+        return CheckResult("log_dir_writable", True)
+    except OSError as e:
+        return CheckResult(
+            "log_dir_writable",
+            False,
+            reason=f"cannot create or write {cfg.runtime.log_dir}: {e}",
+            how_to_fix="chmod / chown the dir, or change runtime.log_dir in config",
+        )
+
+
+def _check_agent_cli(cfg: Config) -> CheckResult:
+    if not cfg.agent.command:
+        return CheckResult("agent_cli_in_path", False, "agent.command is empty")
+    cli = cfg.agent.command[0]
+    if shutil.which(cli) is None:
+        return CheckResult(
+            "agent_cli_in_path",
+            False,
+            reason=f"{cli!r} not found on PATH",
+            how_to_fix=f"install {cli} or set agent.command[0] to its absolute path",
+        )
+    return CheckResult("agent_cli_in_path", True)
+
+
+def _check_work_dir_is_git(cfg: Config) -> CheckResult:
+    from agent_runner.vcs_state import is_git_repo
+
+    if not is_git_repo(cfg.runtime.work_dir):
+        return CheckResult(
+            "work_dir_is_git_repo",
+            False,
+            reason=f"{cfg.runtime.work_dir} is not a git working tree",
+            how_to_fix="run `git init` in the work_dir, or change runtime.work_dir in config",
+        )
+    return CheckResult("work_dir_is_git_repo", True)
+
+
+def _check_prompt_file(cfg: Config) -> CheckResult:
+    if not cfg.prompt.file.exists():
+        return CheckResult(
+            "prompt_file_exists",
+            False,
+            reason=f"{cfg.prompt.file} does not exist",
+            how_to_fix="create the prompt .md file or fix prompt.file in config",
+        )
+    return CheckResult("prompt_file_exists", True)
+
+
+def _check_prompt_smoke(cfg: Config) -> CheckResult:
+    if not cfg.prompt.file.exists():
+        return CheckResult(
+            "prompt_smoke_passes",
+            False,
+            "prompt file missing — see prompt_file_exists",
+        )
+    try:
+        prompt = assemble_prompt(cfg.prompt.file, context=None, inject_context=False)
+    except Exception as e:
+        return CheckResult("prompt_smoke_passes", False, f"assembly failed: {e}")
+    if not prompt:
+        return CheckResult("prompt_smoke_passes", False, "assembled prompt is empty")
+    if prompt[0] in _FORBIDDEN_FIRST_CHARS:
+        return CheckResult(
+            "prompt_smoke_passes",
+            False,
+            reason=f"first char {prompt[0]!r} is forbidden (R721 — claude CLI rejects it)",
+            how_to_fix="ensure the prompt body does not start with -, space, or newline",
+        )
+    if len(prompt.encode("utf-8")) < _MIN_PROMPT_BYTES:
+        return CheckResult(
+            "prompt_smoke_passes",
+            False,
+            reason=(f"prompt is {len(prompt.encode('utf-8'))} bytes < {_MIN_PROMPT_BYTES} minimum"),
+            how_to_fix="add substantive content — a stub prompt suggests a broken config",
+        )
+    return CheckResult("prompt_smoke_passes", True)
+
+
+def _check_config_loaded(cfg: Config) -> CheckResult:
+    # Already loaded if we're here; this slot exists to surface the check name in events.
+    return CheckResult("config_loaded", True)
+
+
+CHECKS: list[Callable[[Config], CheckResult]] = [
+    _check_config_loaded,
+    _check_log_dir,
+    _check_agent_cli,
+    _check_work_dir_is_git,
+    _check_prompt_file,
+    _check_prompt_smoke,
+]
+
+
+def run_battery(cfg: Config) -> list[CheckResult]:
+    """Run all checks. Returns empty list if escape hatch env is set."""
+    if os.environ.get(ESCAPE_HATCH_ENV, "").lower() in ("1", "true", "yes", "on"):
+        return []
+    return [check(cfg) for check in CHECKS]