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

agent_runner/__init__.py

@@ -0,0 +1,3 @@
+"""Agent Runner — restart-on-exit supervisor for autonomous CLI agents."""
+
+__version__ = "0.0.1"

agent_runner/_docgen.py

@@ -0,0 +1,200 @@
+"""Documentation generator — replaces <!-- gen:NAME --> ... <!-- /gen:NAME -->
+content blocks in docs/*.md from registered renderers.
+
+The marker primitive `replace_block` is intentionally separate from the
+renderer registry so the substitution rule is testable in isolation.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+import typing
+from collections.abc import Callable
+from pathlib import Path
+
+from agent_runner.config import (
+    AgentConfig,
+    Config,
+    PromptConfig,
+    RuntimeConfig,
+    VcsConfig,
+)
+from agent_runner.defenses import catalog
+from agent_runner.events import KNOWN_EVENT_KINDS
+from agent_runner.monitor import AUTO_STOP_ALERTS, KNOWN_ALERT_KINDS
+
+_SECTIONS = [
+    ("agent", AgentConfig),
+    ("runtime", RuntimeConfig),
+    ("prompt", PromptConfig),
+    ("vcs", VcsConfig),
+]
+
+
+def _type_label(t: typing.Any) -> str:
+    # dataclasses.fields exposes `.type` as a string (PEP 563), so we render
+    # the raw annotation. Strip ``Path`` / ``Path | None`` wrappers cosmetically.
+    s = str(t).replace("pathlib.", "")
+    return s
+
+
+def _default_label(field: dataclasses.Field) -> str:
+    if field.default is not dataclasses.MISSING:
+        return repr(field.default)
+    if field.default_factory is not dataclasses.MISSING:  # type: ignore[misc]
+        return repr(field.default_factory())
+    return "—"
+
+
+def render_config_schema_table() -> str:
+    """Markdown sub-sections per Config dataclass with field/type/default."""
+    parts: list[str] = []
+    for name, dc in _SECTIONS:
+        parts.append(f"### `[{name}]`")
+        parts.append("")
+        parts.append("| Field | Type | Default |")
+        parts.append("|---|---|---|")
+        for f in dataclasses.fields(dc):
+            parts.append(f"| `{f.name}` | `{_type_label(f.type)}` | {_default_label(f)} |")
+        parts.append("")
+    return "\n".join(parts).rstrip()
+
+
+def replace_block(text: str, name: str, new_content: str) -> str:
+    """Replace the body between ``<!-- gen:NAME -->`` and ``<!-- /gen:NAME -->``.
+
+    The opening / closing markers themselves are preserved. Returns the
+    original text unchanged when the opening marker is absent. Raises
+    ``ValueError`` when the opening marker is present without a matching close.
+    """
+    open_tag = f"<!-- gen:{name} -->"
+    close_tag = f"<!-- /gen:{name} -->"
+    if open_tag not in text:
+        return text
+    if close_tag not in text:
+        raise ValueError(f"<!-- gen:{name} --> has no matching close tag")
+    pattern = re.compile(
+        re.escape(open_tag) + r".*?" + re.escape(close_tag),
+        re.DOTALL,
+    )
+    return pattern.sub(f"{open_tag}\n{new_content}\n{close_tag}", text)
+
+
+def _default_cfg() -> Config:
+    """Build a default Config for doc rendering — defaults only, no user values."""
+    return Config(
+        agent=AgentConfig(command=["agent"], prompt_arg_template=[]),
+        runtime=RuntimeConfig(
+            work_dir=Path("."),
+            log_dir=Path("./logs"),
+        ),
+        prompt=PromptConfig(file=Path("./prompt.md")),
+        vcs=VcsConfig(),
+    )
+
+
+def render_defenses_table() -> str:
+    """Markdown table of the defense catalog. Renders defaults only."""
+    cfg = _default_cfg()
+    lines = [
+        "| Defense | Codifies | Guarded by |",
+        "|---|---|---|",
+    ]
+    for d in catalog(cfg):
+        codifies = d.codifies or "—"
+        guarded = str(d.guarded_by) if d.guarded_by is not None else "—"
+        lines.append(f"| `{d.name}` | {codifies} | `{guarded}` |")
+    return "\n".join(lines)
+
+
+def render_alert_kinds_list() -> str:
+    """Flat bullet list of all known alert kinds, alphabetised."""
+    return "\n".join(f"- `{k}`" for k in sorted(KNOWN_ALERT_KINDS))
+
+
+def render_detector_list() -> str:
+    """Bullet list of detectors; auto-stop kinds flagged inline."""
+    lines: list[str] = []
+    for k in sorted(KNOWN_ALERT_KINDS):
+        suffix = " — **auto-stop**" if k in AUTO_STOP_ALERTS else ""
+        lines.append(f"- `{k}`{suffix}")
+    return "\n".join(lines)
+
+
+def render_event_kinds_list() -> str:
+    """Flat bullet list of all known event kinds, alphabetised."""
+    return "\n".join(f"- `{k}`" for k in sorted(KNOWN_EVENT_KINDS))
+
+
+def render_verb_table() -> str:
+    """Walk the argparse subparsers and render a verb table."""
+    from agent_runner.cli import _build_parser
+
+    parser = _build_parser()
+    # Find the sub-parsers action — there's exactly one.
+    sub_action = next(a for a in parser._actions if a.__class__.__name__ == "_SubParsersAction")
+    rows = [
+        "| Verb | Description |",
+        "|---|---|",
+    ]
+    for verb, _sp in sub_action.choices.items():
+        # Argparse stores help text via `sub_action._choices_actions` indexed by add order.
+        help_text = (
+            next(
+                (c.help for c in sub_action._choices_actions if c.dest == verb),
+                "",
+            )
+            or ""
+        )
+        rows.append(f"| `{verb}` | {help_text} |")
+    return "\n".join(rows)
+
+
+RENDERERS: dict[str, Callable[[], str]] = {
+    "defenses-table": render_defenses_table,
+    "alert-kinds": render_alert_kinds_list,
+    "detector-list": render_detector_list,
+    "event-kinds": render_event_kinds_list,
+    "config-schema": render_config_schema_table,
+    "verb-table": render_verb_table,
+}
+
+_GEN_OPEN = re.compile(r"<!-- gen:([a-z0-9-]+) -->")
+
+
+def render(docs_dir: Path, *, write: bool = True) -> dict[Path, str]:
+    """Render every ``<!-- gen:NAME -->`` block in ``docs_dir/*.md``.
+
+    Returns a {path: rendered_text} mapping. When ``write=True`` also writes
+    the rewritten text back to each path.
+
+    Raises ``ValueError`` when a marker references an unknown renderer name.
+    """
+    out: dict[Path, str] = {}
+    for md in sorted(docs_dir.glob("*.md")):
+        text = md.read_text(encoding="utf-8")
+        for match in _GEN_OPEN.finditer(text):
+            name = match.group(1)
+            if name not in RENDERERS:
+                raise ValueError(
+                    f"{md.name}: unknown gen marker {name!r} — valid names: {sorted(RENDERERS)}"
+                )
+            try:
+                text = replace_block(text, name, RENDERERS[name]())
+            except ValueError as e:
+                raise ValueError(f"{md.name}: {e}") from e
+        out[md] = text
+        if write:
+            md.write_text(text, encoding="utf-8")
+    return out
+
+
+def main() -> int:
+    repo_root = Path(__file__).resolve().parent.parent
+    render(docs_dir=repo_root / "docs")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

agent_runner/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

agent_runner/agent_runtime.py

@@ -0,0 +1,127 @@
+"""Agent subprocess management — ONLY module that spawns the claude CLI.
+
+Defenses encoded here:
+- R725: SIGTERM handler reaps process group before runner exits
+- R1128: ROUND_TIMEOUT is wall-clock hard wall (no activity-based extension)
+- #307: start_new_session=True isolates subprocess in its own pgrp
+- env injection: DISABLE_AUTOUPDATER=1 + CLAUDE_CODE_EFFORT_LEVEL caller-provided
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess  # noqa: TID251 — sanctioned subprocess caller
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+REAP_GRACE_S = 5
+
+
+@dataclass(frozen=True)
+class RunResult:
+    exit_code: int
+    duration_s: float
+    timed_out: bool
+    pid: int
+
+
+def _build_argv(command: list[str], prompt_arg_template: list[str], prompt: str) -> list[str]:
+    """Build full argv: command + prompt args (with {prompt} substituted)."""
+    return list(command) + [a.replace("{prompt}", prompt) for a in prompt_arg_template]
+
+
+def _kill_pgroup(proc: subprocess.Popen) -> None:
+    pgid = proc.pid
+    try:
+        os.killpg(pgid, signal.SIGTERM)
+    except OSError:
+        pass
+    deadline = time.time() + REAP_GRACE_S
+    while time.time() < deadline and proc.poll() is None:
+        time.sleep(0.1)
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except OSError:
+        pass
+    try:
+        proc.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        pass
+
+
+def run(
+    *,
+    command: list[str],
+    prompt_arg_template: list[str],
+    prompt: str,
+    timeout_s: int,
+    log_path: Path,
+    env_extra: dict[str, str],
+) -> RunResult:
+    """Spawn the agent subprocess and wait for exit or timeout.
+
+    Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
+    """
+    argv = _build_argv(command, prompt_arg_template, prompt)
+    env = {**os.environ, **env_extra}
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    log_file = log_path.open("w", encoding="utf-8")
+    start = time.time()
+    proc = subprocess.Popen(
+        argv,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=log_file,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+    try:
+        while True:
+            ret = proc.poll()
+            now = time.time()
+            if ret is not None:
+                duration = now - start
+                return RunResult(exit_code=ret, duration_s=duration, timed_out=False, pid=proc.pid)
+            if now - start > timeout_s:
+                _kill_pgroup(proc)
+                duration = time.time() - start
+                exit_code = proc.returncode if proc.returncode is not None else -1
+                return RunResult(
+                    exit_code=exit_code, duration_s=duration, timed_out=True, pid=proc.pid
+                )
+            time.sleep(0.2)
+    finally:
+        log_file.close()
+
+
+CRITICAL_ENV_DEFAULTS: dict[str, str] = {
+    "DISABLE_AUTOUPDATER": "1",  # do not let claude self-update mid-loop
+    "CLAUDE_CODE_EFFORT_LEVEL": "xhigh",  # full effort, not default
+}
+
+
+def merge_critical_envs(user_env: dict[str, str]) -> dict[str, str]:
+    """Merge user env with CRITICAL_ENV_DEFAULTS — critical always wins."""
+    merged = dict(user_env)
+    merged.update(CRITICAL_ENV_DEFAULTS)
+    return merged
+
+
+def install_sigterm_reaper(reaper: Callable[[], None]) -> object:
+    """Install a SIGTERM handler that calls ``reaper()`` first.
+
+    R725 defense: when supervisor receives SIGTERM (e.g. systemctl stop, manual
+    kill), bash wrapper would otherwise respawn fresh runner while old claude
+    keeps running → two claudes race on the same git tree, second commit can
+    swallow first commit's chat-room entry. Reaper terminates pgroup first.
+
+    Returns the previous SIGTERM handler so caller can restore it.
+    """
+
+    def _handler(_signum: int, _frame: object) -> None:
+        reaper()
+
+    return signal.signal(signal.SIGTERM, _handler)

agent_runner/api.py

@@ -0,0 +1,331 @@
+"""Public Python API mirroring CLI verbs.
+
+Every CLI subcommand has a corresponding api function. CLI files do
+``api.X(...)`` and format the returned dataclass for display. External
+agents (Phase 3 outer Claude Code) can `from agent_runner import api`
+and skip CLI text parsing entirely.
+"""
+
+from __future__ import annotations
+
+import signal
+import subprocess  # noqa: TID251 — api uses systemctl + ssh, both subprocess
+import sys
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from agent_runner import lifecycle
+from agent_runner.api_types import (
+    InitResult,
+    InstallResult,
+    ProjectState,
+    ServiceMode,
+    ServiceStatus,
+    select_path,
+)
+from agent_runner.config import load_config
+from agent_runner.lifecycle import (
+    PIDFile,
+    detect_service_mode,
+    pid_alive,
+    send_signal_to_pid,
+)
+from agent_runner.scaffold import scaffold_project
+from agent_runner.service_unit import (
+    monitor_unit_filename,
+    render_monitor_unit,
+    render_serve_unit,
+    serve_unit_filename,
+)
+
+
+def _project_name(work_dir: Path) -> str:
+    return work_dir.resolve().name or "default"
+
+
+def _log_dir(work_dir: Path) -> Path:
+    """Return the configured log_dir from agent-runner.toml.
+
+    Falls back to the conventional ~/.agent-runner/<project>/logs only when
+    the toml is missing. This keeps `api.status` / `api.stop` aligned with
+    where `serve_cmd.py` actually writes serve.pid.
+    """
+    cfg_path = work_dir / "agent-runner.toml"
+    if cfg_path.exists():
+        return load_config(cfg_path).runtime.log_dir
+    return Path.home() / ".agent-runner" / _project_name(work_dir) / "logs"
+
+
+def _venv_bin() -> Path:
+    """Where this Python interpreter lives — for ExecStart."""
+    return Path(sys.executable).parent
+
+
+def _systemctl_user(*args: str) -> None:
+    subprocess.run(["systemctl", "--user", *args], check=False)
+
+
+# ---------------------------------------------------------------------------
+# init / install / uninstall
+
+
+def init(work_dir: Path | None = None, *, force: bool = False, commit: bool = True) -> InitResult:
+    if work_dir is None:
+        work_dir = Path.cwd()
+    return scaffold_project(work_dir, force=force, commit=commit)
+
+
+def install(
+    work_dir: Path | None = None, *, system: bool = False, with_monitor: bool = False
+) -> InstallResult:
+    if work_dir is None:
+        work_dir = Path.cwd()
+    if system:
+        raise NotImplementedError("--system install not yet implemented in Phase 2")
+    cfg_path = work_dir / "agent-runner.toml"
+    cfg = load_config(cfg_path)
+    project = _project_name(work_dir)
+
+    units_dir = lifecycle._user_systemd_dir()
+    units_dir.mkdir(parents=True, exist_ok=True)
+
+    serve_path = units_dir / serve_unit_filename(project)
+    serve_path.write_text(render_serve_unit(cfg, venv_bin=_venv_bin()))
+
+    monitor_path: Path | None = None
+    if with_monitor:
+        monitor_path = units_dir / monitor_unit_filename(project)
+        monitor_path.write_text(render_monitor_unit(cfg, venv_bin=_venv_bin()))
+
+    _systemctl_user("daemon-reload")
+    _systemctl_user("enable", serve_unit_filename(project))
+    _systemctl_user("start", serve_unit_filename(project))
+    if with_monitor:
+        _systemctl_user("enable", monitor_unit_filename(project))
+        _systemctl_user("start", monitor_unit_filename(project))
+
+    return InstallResult(
+        unit_path=serve_path, monitor_unit_path=monitor_path, enabled=True, started=True
+    )
+
+
+def uninstall(work_dir: Path | None = None) -> bool:
+    if work_dir is None:
+        work_dir = Path.cwd()
+    project = _project_name(work_dir)
+    units_dir = lifecycle._user_systemd_dir()
+    serve = units_dir / serve_unit_filename(project)
+    monitor = units_dir / monitor_unit_filename(project)
+    for p in (serve, monitor):
+        if p.exists():
+            _systemctl_user("stop", p.name)
+            _systemctl_user("disable", p.name)
+            p.unlink(missing_ok=True)
+    _systemctl_user("daemon-reload")
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle: start / stop / kill / cancel / restart / status
+
+
+def start(project: str | Path) -> ServiceStatus:
+    pname = _resolve_project(project)
+    log_dir = _log_dir_for_project(project)
+    mode = detect_service_mode(pname, log_dir=log_dir)
+    if mode == ServiceMode.SYSTEMD_USER:
+        _systemctl_user("start", serve_unit_filename(pname))
+    return status(project)
+
+
+def stop(project: str | Path) -> ServiceStatus:
+    pname = _resolve_project(project)
+    log_dir = _log_dir_for_project(project)
+    mode = detect_service_mode(pname, log_dir=log_dir)
+    if mode == ServiceMode.SYSTEMD_USER:
+        _systemctl_user("stop", serve_unit_filename(pname))
+        return status(project)
+    pid = PIDFile(log_dir / "serve.pid").read()
+    if pid is not None:
+        send_signal_to_pid(pid, signal.SIGTERM)
+    return status(project)
+
+
+def kill(project: str | Path) -> ServiceStatus:
+    pname = _resolve_project(project)
+    log_dir = _log_dir_for_project(project)
+    mode = detect_service_mode(pname, log_dir=log_dir)
+    if mode == ServiceMode.SYSTEMD_USER:
+        _systemctl_user("kill", "--signal=SIGTERM", serve_unit_filename(pname))
+        return status(project)
+    pid = PIDFile(log_dir / "serve.pid").read()
+    if pid is None:
+        return status(project)
+    send_signal_to_pid(pid, signal.SIGTERM)
+    deadline = time.time() + 5
+    alive = True
+    while time.time() < deadline:
+        alive = pid_alive(pid)
+        if not alive:
+            break
+        time.sleep(0.1)
+    if alive:
+        send_signal_to_pid(pid, signal.SIGKILL)
+    return ServiceStatus(mode=ServiceMode.PID_FILE, active=alive, pid=pid)
+
+
+def cancel(project: str | Path) -> bool:
+    pname = _resolve_project(project)
+    log_dir = _log_dir_for_project(project)
+    mode = detect_service_mode(pname, log_dir=log_dir)
+    if mode == ServiceMode.SYSTEMD_USER:
+        _systemctl_user("kill", "--signal=SIGUSR1", serve_unit_filename(pname))
+        return True
+    pid = PIDFile(log_dir / "serve.pid").read()
+    if pid is None:
+        return False
+    return send_signal_to_pid(pid, signal.SIGUSR1)
+
+
+def restart(project: str | Path, *, force: bool = False) -> ServiceStatus:
+    if force:
+        kill(project)
+    else:
+        stop(project)
+    return start(project)
+
+
+def status(project: str | Path) -> ServiceStatus:
+    pname = _resolve_project(project)
+    log_dir = _log_dir_for_project(project)
+    mode = detect_service_mode(pname, log_dir=log_dir)
+    if mode == ServiceMode.PID_FILE:
+        pid = PIDFile(log_dir / "serve.pid").read()
+        return ServiceStatus(mode=mode, active=pid is not None and pid_alive(pid), pid=pid)
+    if mode == ServiceMode.SYSTEMD_USER:
+        unit = lifecycle._user_systemd_dir() / serve_unit_filename(pname)
+        return ServiceStatus(mode=mode, active=True, unit_file=unit)
+    return ServiceStatus(mode=ServiceMode.NONE, active=False)
+
+
+def _resolve_project(project: str | Path) -> str:
+    if isinstance(project, Path):
+        return _project_name(project)
+    if "/" in project or "\\" in project:
+        return _project_name(Path(project))
+    return project
+
+
+def _log_dir_for_project(project: str | Path) -> Path:
+    if isinstance(project, Path):
+        return _log_dir(project)
+    p = Path.cwd() if project == _project_name(Path.cwd()) else None
+    if p is not None:
+        return _log_dir(p)
+    return Path.home() / ".agent-runner" / project / "logs"
+
+
+# ---------------------------------------------------------------------------
+# Observation: peek / monitor_loop / _poll_once
+#
+# Imported lazily to avoid pulling monitor + defenses at module load time
+# for callers that only use lifecycle verbs.
+
+from agent_runner import defenses, monitor  # noqa: E402
+
+
+def peek(
+    project: str | Path | None = None,
+    *,
+    round: int | str | None = None,
+    log: bool = False,
+    events: int | None = None,
+    select: str | None = None,
+) -> ProjectState | Any:
+    """Build a ProjectState snapshot. With select, return that subtree."""
+    from agent_runner import round_view
+
+    work_dir = project if isinstance(project, Path) else Path.cwd()
+    cfg = load_config(work_dir / "agent-runner.toml")
+    log_dir = cfg.runtime.log_dir
+    src = monitor.LocalSource(log_dir=log_dir)
+    base_state = monitor.assemble_project_state(src, project=_project_name(work_dir))
+    parsed_events = monitor.parse_events_from_jsonl_files(src.events_files())
+    round_num = round_view.resolve_round_arg(round, log_dir)
+    current: Any = base_state.current_round
+    if round_num is not None:
+        current = round_view.build_round_view(log_dir, round_num, parsed_events, want_log=log)
+        if current is None:
+            raise KeyError(f"round {round_num} not found under {log_dir}/rounds/")
+    recent = parsed_events[-events:] if events else []
+
+    state = ProjectState(
+        project=base_state.project,
+        status=base_state.status,
+        defenses=[
+            {
+                "name": d.name,
+                "value": d.value,
+                "codifies": d.codifies,
+                "guarded_by": str(d.guarded_by) if d.guarded_by else None,
+                "current_state": d.current_state,
+            }
+            for d in defenses.catalog(cfg)
+        ],
+        current_round=current,
+        recent_rounds=base_state.recent_rounds,
+        orphan=base_state.orphan,
+        system=base_state.system,
+        service=status(project if project is not None else work_dir),
+        recent_events=recent,
+    )
+    return state if select is None else select_path(state, select)
+
+
+def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
+    work_dir = project if isinstance(project, Path) else Path.cwd()
+    cfg = load_config(work_dir / "agent-runner.toml")
+    src: monitor.StateSource
+    if host is None:
+        src = monitor.LocalSource(log_dir=cfg.runtime.log_dir)
+    else:
+        src = monitor.RemoteSource(host=host, project=_project_name(work_dir))
+    events = monitor.parse_events_from_jsonl_files(src.events_files())
+    metrics = monitor.parse_events_from_jsonl_files(src.metrics_files())
+    log_tails = monitor.load_round_log_tails(src.rounds_dir())
+    return monitor.run_all_detectors(
+        events=events,
+        metrics=metrics,
+        log_tails=log_tails,
+        round_timeout_s=cfg.runtime.round_timeout_s,
+    )
+
+
+def monitor_loop(
+    project: str | Path | None = None, *, host: str | None = None, interval_s: int = 30
+) -> Iterator[monitor.Alert]:
+    """Yield alerts as they're detected. Caller decides what to do.
+
+    The loop dedups alerts by (detector, json.dumps(context)) within session.
+    """
+    import json as _json
+
+    seen: set[str] = set()
+    work_dir = project if isinstance(project, Path) else Path.cwd()
+    cfg = load_config(work_dir / "agent-runner.toml")
+    while True:
+        for alert in _poll_once(work_dir, host=host):
+            key = f"{alert.detector}:{_json.dumps(alert.context, sort_keys=True)}"
+            if key in seen:
+                continue
+            seen.add(key)
+            yield alert
+            monitor.on_alert(
+                alert,
+                project=_project_name(work_dir),
+                host=host,
+                log_dir=cfg.runtime.log_dir,
+            )
+        time.sleep(interval_s)