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

agent_runner/api_types.py

@@ -0,0 +1,111 @@
+"""Dataclasses for the Python API state tree.
+
+These are the public types that ``agent_runner.api`` returns and that
+``cli/`` formats. Phase 3 LLM/Critic will read these structures.
+
+All frozen — state is immutable, no in-place mutation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ServiceMode(StrEnum):
+    SYSTEMD_USER = "systemd_user"
+    PID_FILE = "pid_file"
+    NONE = "none"
+
+
+@dataclass(frozen=True)
+class ServiceStatus:
+    mode: ServiceMode
+    active: bool
+    pid: int | None = None
+    uptime_s: float | None = None
+    unit_file: Path | None = None
+
+
+@dataclass(frozen=True)
+class SystemMetrics:
+    mem_total_mb: int
+    mem_available_mb: int
+    disk_used_pct: float
+    disk_free_gb: float = 0.0
+    load_1m: float | None = None
+    cpu_pct: float | None = None
+
+
+@dataclass(frozen=True)
+class RoundView:
+    round_num: int
+    phase: str | None
+    started_at: str
+    duration_so_far_s: float | None
+    pid: int | None
+    exit_code: int | None
+    timed_out: bool | None
+    log_path: Path
+    log_tail: str | None = None
+    recent_events: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ProjectState:
+    project: str
+    status: dict[str, Any]
+    defenses: list[dict[str, Any]]
+    current_round: RoundView | None
+    recent_rounds: list[RoundView]
+    orphan: dict[str, Any] | None
+    system: SystemMetrics
+    service: ServiceStatus
+    recent_events: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Alert:
+    severity: str
+    detector: str
+    message: str
+    context: dict[str, Any]
+    ts: str
+    auto_action: str = "none"
+
+
+@dataclass(frozen=True)
+class InitResult:
+    work_dir: Path
+    files_created: list[Path]
+    committed: bool
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    unit_path: Path
+    monitor_unit_path: Path | None
+    enabled: bool
+    started: bool
+
+
+def select_path(tree: Any, path: str) -> Any:
+    """Resolve dot-notation path into a nested dataclass / dict / list tree.
+
+    Numeric segments index into lists. Raises KeyError naming the failed
+    segment so the caller (CLI) can give a precise error to the user.
+    """
+    cur = tree
+    for part in path.split("."):
+        try:
+            if part.isdigit():
+                cur = cur[int(part)]
+            elif isinstance(cur, dict):
+                cur = cur[part]
+            else:
+                cur = getattr(cur, part)
+        except (AttributeError, IndexError, KeyError) as e:
+            raise KeyError(f"path segment {part!r} not found in select path {path!r}") from e
+    return cur

agent_runner/cli/__init__.py

@@ -0,0 +1,76 @@
+"""CLI entry — argparse subcommand dispatcher.
+
+Each subcommand lives in its own ``*_cmd.py`` file; this module just routes.
+The ``--config`` and ``--json`` flags can be placed before OR after the
+subcommand verb. To make this work without the subparser's defaults clobbering
+values supplied to the main parser, the main parser owns the real defaults
+while the subparser-shared parent declares the same flags with
+``argparse.SUPPRESS`` so they only mutate the namespace when explicitly
+supplied after the verb.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from agent_runner.cli import (
+    init_cmd,
+    install_cmd,
+    monitor_cmd,
+    peek_cmd,
+    round_cmd,
+    serve_cmd,
+    service_cmd,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-runner",
+        description="Restart-on-exit supervisor for autonomous CLI agents.",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=Path("./agent-runner.toml"),
+        help="Path to agent-runner.toml (default: ./agent-runner.toml)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="Machine-readable JSON output (where supported)"
+    )
+
+    # Parent parser shared by every subparser so the same flags can also be
+    # placed AFTER the verb. SUPPRESS keeps the subparser from overwriting
+    # values supplied to the main parser when the flag is omitted.
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument("--config", type=Path, default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    parent.add_argument(
+        "--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS
+    )
+
+    sub = parser.add_subparsers(dest="command", required=False)
+
+    init_cmd.add_parser(sub, parent)
+    install_cmd.add_parser(sub, parent)
+    service_cmd.add_parser(sub, parent)
+    peek_cmd.add_parser(sub, parent)
+    monitor_cmd.add_parser(sub, parent)
+    serve_cmd.add_parser(sub, parent)
+    round_cmd.add_parser(sub, parent)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

agent_runner/cli/__main__.py

@@ -0,0 +1,3 @@
+from agent_runner.cli import main
+
+raise SystemExit(main())

agent_runner/cli/common.py

@@ -0,0 +1,78 @@
+"""Shared CLI helpers — config loading + JSON formatting."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from agent_runner.config import Config, load_config
+
+
+def cfg_from_args(args) -> Config:
+    return load_config(args.config)
+
+
+def work_dir_from_args(args) -> Path:
+    """Resolve the project work_dir from --config's parent, falling back to cwd.
+
+    The api functions hardcode ``work_dir / "agent-runner.toml"`` for config loading,
+    so callers cannot rename the toml. Reject a mismatching filename loudly here
+    instead of letting api read the wrong file (or a missing file) silently.
+    """
+    cfg = getattr(args, "config", None)
+    if cfg is None:
+        return Path.cwd().resolve()
+    cfg_path = Path(cfg).resolve()
+    if cfg_path.name != "agent-runner.toml":
+        raise ValueError(
+            f"--config must point at a file named 'agent-runner.toml', got {cfg_path.name!r}"
+        )
+    return cfg_path.parent
+
+
+def emit(value: Any, *, json_mode: bool) -> None:
+    if json_mode:
+        print(json.dumps(_to_jsonable(value), indent=2, default=str))
+    else:
+        print(_pretty(value))
+
+
+def _to_jsonable(value: Any) -> Any:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {f.name: _to_jsonable(getattr(value, f.name)) for f in dataclasses.fields(value)}
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(x) for x in value]
+    if isinstance(value, dict):
+        return {k: _to_jsonable(v) for k, v in value.items()}
+    return value
+
+
+def _pretty(value: Any) -> str:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        lines: list[str] = [type(value).__name__ + ":"]
+        for f in dataclasses.fields(value):
+            v = getattr(value, f.name)
+            lines.append(f"  {f.name}: {_pretty_inline(v)}")
+        return "\n".join(lines)
+    return _pretty_inline(value)
+
+
+def _pretty_inline(value: Any) -> str:
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    return repr(value)
+
+
+def fail(msg: str, *, code: int = 1) -> int:
+    print(f"agent-runner: {msg}", file=sys.stderr)
+    return code

agent_runner/cli/init_cmd.py

@@ -0,0 +1,31 @@
+"""init subcommand — scaffold project."""
+
+from __future__ import annotations
+
+from agent_runner import api
+from agent_runner.cli.common import emit, fail, work_dir_from_args
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser("init", parents=[parent], help="Scaffold agent-runner project files")
+    p.add_argument("--force", action="store_true", help="Overwrite existing toml")
+    g = p.add_mutually_exclusive_group()
+    g.add_argument(
+        "--commit",
+        dest="commit",
+        action="store_true",
+        default=True,
+        help="git commit the new files (default)",
+    )
+    g.add_argument("--no-commit", dest="commit", action="store_false", help="Skip git commit")
+    p.set_defaults(func=cmd)
+
+
+def cmd(args) -> int:
+    work_dir = work_dir_from_args(args)
+    try:
+        result = api.init(work_dir, force=args.force, commit=args.commit)
+    except (FileExistsError, RuntimeError) as e:
+        return fail(str(e))
+    emit(result, json_mode=getattr(args, "json", False))
+    return 0

agent_runner/cli/install_cmd.py

@@ -0,0 +1,44 @@
+"""install / uninstall subcommands — manage systemd user units."""
+
+from __future__ import annotations
+
+from agent_runner import api
+from agent_runner.cli.common import emit, fail, work_dir_from_args
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser(
+        "install", parents=[parent], help="Generate systemd user unit, enable + start"
+    )
+    p.add_argument(
+        "--system",
+        action="store_true",
+        help="Install at system level (not yet supported in Phase 2)",
+    )
+    p.add_argument(
+        "--monitor",
+        action="store_true",
+        help="Also install monitor sidekick service for auto-stop on critical alerts",
+    )
+    p.set_defaults(func=cmd_install)
+
+    u = sub.add_parser(
+        "uninstall", parents=[parent], help="Stop, disable, and remove systemd user unit(s)"
+    )
+    u.set_defaults(func=cmd_uninstall)
+
+
+def cmd_install(args) -> int:
+    work_dir = work_dir_from_args(args)
+    try:
+        result = api.install(work_dir, system=args.system, with_monitor=args.monitor)
+    except (NotImplementedError, FileNotFoundError) as e:
+        return fail(str(e))
+    emit(result, json_mode=getattr(args, "json", False))
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    work_dir = work_dir_from_args(args)
+    api.uninstall(work_dir)
+    return 0

agent_runner/cli/monitor_cmd.py

@@ -0,0 +1,48 @@
+"""monitor subcommand — anomaly detection daemon (local or remote)."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from agent_runner import api
+from agent_runner.cli.common import _to_jsonable, work_dir_from_args
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser(
+        "monitor", parents=[parent], help="Anomaly detection daemon (local or remote via --host)"
+    )
+    p.add_argument(
+        "--host",
+        type=str,
+        default=None,
+        metavar="SSH-ALIAS",
+        help="Watch a remote agent-runner via ssh",
+    )
+    p.add_argument(
+        "--interval",
+        type=int,
+        default=None,
+        metavar="SECONDS",
+        help="Poll interval (default 30s, 60s for remote)",
+    )
+    p.set_defaults(func=cmd)
+
+
+def cmd(args) -> int:
+    interval = args.interval if args.interval is not None else (60 if args.host else 30)
+    json_mode = getattr(args, "json", False)
+    try:
+        work_dir = work_dir_from_args(args)
+        for alert in api.monitor_loop(work_dir, host=args.host, interval_s=interval):
+            if json_mode:
+                print(json.dumps(_to_jsonable(alert)))
+                sys.stdout.flush()
+            else:
+                tag = {"info": "[OK]", "warning": "[WARN]", "critical": "[CRIT]"}[alert.severity]
+                print(f"{tag} {alert.detector} — {alert.message}")
+                sys.stdout.flush()
+    except KeyboardInterrupt:
+        return 0
+    return 0

agent_runner/cli/peek_cmd.py

@@ -0,0 +1,81 @@
+"""peek and watch subcommands — snapshot + auto-refresh."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from agent_runner import api
+from agent_runner.cli.common import emit, fail, work_dir_from_args
+
+
+def _round_arg(s: str) -> int | str:
+    if s == "latest":
+        return s
+    try:
+        return int(s)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(f"--round expects int or 'latest', got {s!r}") from e
+
+
+def add_parser(sub, parent) -> None:
+    for verb, fn in (("peek", cmd_peek), ("watch", cmd_watch)):
+        p = sub.add_parser(
+            verb, parents=[parent], help=f"{verb} project state with optional drill-down"
+        )
+        p.add_argument(
+            "--round",
+            type=_round_arg,
+            default=None,
+            metavar="N",
+            help="Drill into round N (int or 'latest')",
+        )
+        p.add_argument("--log", action="store_true", help="Include current round's log tail")
+        p.add_argument(
+            "--events", type=int, default=None, metavar="N", help="Include last N events"
+        )
+        p.add_argument(
+            "--select",
+            type=str,
+            default=None,
+            help="Dot-path subtree to extract (e.g. system.disk_used_pct)",
+        )
+        if verb == "watch":
+            p.add_argument(
+                "--interval",
+                type=int,
+                default=2,
+                metavar="SECONDS",
+                help="Refresh interval (default 2)",
+            )
+        p.set_defaults(func=fn)
+
+
+def cmd_peek(args) -> int:
+    try:
+        result = api.peek(
+            work_dir_from_args(args),
+            round=args.round,
+            log=args.log,
+            events=args.events,
+            select=args.select,
+        )
+    except KeyError as e:
+        return fail(str(e))
+    except FileNotFoundError as e:
+        return fail(f"config not found: {e}")
+    emit(result, json_mode=getattr(args, "json", False))
+    return 0
+
+
+def cmd_watch(args) -> int:
+    while True:
+        sys.stdout.write("\x1b[2J\x1b[H")
+        rc = cmd_peek(args)
+        if rc != 0:
+            return rc
+        try:
+            time.sleep(args.interval)
+        except KeyboardInterrupt:
+            return 0

agent_runner/cli/round_cmd.py

@@ -0,0 +1,17 @@
+"""round subcommand — runs one supervisor round (used by serve and systemd)."""
+
+from __future__ import annotations
+
+from agent_runner.cli.common import cfg_from_args
+from agent_runner.runner import run_one_round
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser("round", parents=[parent], help="Run one round and exit")
+    p.set_defaults(func=cmd)
+
+
+def cmd(args) -> int:
+    cfg = cfg_from_args(args)
+    run_one_round(cfg)
+    return 0

agent_runner/cli/serve_cmd.py

@@ -0,0 +1,60 @@
+"""serve subcommand — long-running supervisor loop. THIN: <=60 LOC.
+
+Trap signals, write/cleanup PID files, run `round` subprocess in a loop.
+All real work delegated to `agent-runner round` (fresh import per round).
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess  # noqa: TID251
+import sys
+import time
+
+from agent_runner.cli.common import cfg_from_args
+from agent_runner.lifecycle import PIDFile, send_signal_to_pid
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser("serve", parents=[parent], help="Long-running supervisor loop")
+    p.add_argument("--once", action="store_true", help="Run a single round then exit (debug)")
+    p.set_defaults(func=cmd)
+
+
+def cmd(args) -> int:
+    cfg = cfg_from_args(args)
+    pid_file = PIDFile(cfg.runtime.log_dir / "serve.pid")
+    pid_file.write(os.getpid())
+    stop = {"requested": False}
+    round_pid_file = PIDFile(cfg.runtime.log_dir / "round.pid")
+
+    def graceful(_sig, _frame):
+        stop["requested"] = True
+
+    def cancel(_sig, _frame):
+        stop["requested"] = True
+        rp = round_pid_file.read()
+        if rp is not None:
+            send_signal_to_pid(-rp, signal.SIGINT)
+
+    signal.signal(signal.SIGTERM, graceful)
+    signal.signal(signal.SIGINT, graceful)
+    signal.signal(signal.SIGUSR1, cancel)
+
+    try:
+        while not stop["requested"]:
+            r = subprocess.run(
+                [sys.executable, "-m", "agent_runner.cli", "--config", str(args.config), "round"],
+            )
+            if args.once or stop["requested"]:
+                break
+            delay = (
+                cfg.runtime.restart_delay_s
+                if r.returncode == 0
+                else cfg.runtime.restart_delay_s * 2
+            )
+            time.sleep(delay)
+    finally:
+        pid_file.unlink()
+    return 0

agent_runner/cli/service_cmd.py

@@ -0,0 +1,54 @@
+"""service subcommands — start / stop / kill / cancel / restart / status."""
+
+from __future__ import annotations
+
+from agent_runner import api
+from agent_runner.cli.common import emit, work_dir_from_args
+
+
+def add_parser(sub, parent) -> None:
+    for verb, fn, help_text in (
+        ("start", cmd_start, "Start the service"),
+        ("stop", cmd_stop, "Graceful stop (waits for current round)"),
+        ("kill", cmd_kill, "Force terminate (5s grace then SIGKILL)"),
+        ("cancel", cmd_cancel, "Best-effort: SIGINT to claude (commit-and-exit hint)"),
+        ("restart", cmd_restart, "stop + start (use --force for kill semantics)"),
+        ("status", cmd_status, "Show current service state"),
+    ):
+        p = sub.add_parser(verb, parents=[parent], help=help_text)
+        if verb == "restart":
+            p.add_argument("--force", action="store_true", help="Use kill instead of stop")
+        p.set_defaults(func=fn)
+
+
+def cmd_start(args) -> int:
+    emit(api.start(work_dir_from_args(args)), json_mode=getattr(args, "json", False))
+    return 0
+
+
+def cmd_stop(args) -> int:
+    emit(api.stop(work_dir_from_args(args)), json_mode=getattr(args, "json", False))
+    return 0
+
+
+def cmd_kill(args) -> int:
+    emit(api.kill(work_dir_from_args(args)), json_mode=getattr(args, "json", False))
+    return 0
+
+
+def cmd_cancel(args) -> int:
+    api.cancel(work_dir_from_args(args))
+    return 0
+
+
+def cmd_restart(args) -> int:
+    emit(
+        api.restart(work_dir_from_args(args), force=args.force),
+        json_mode=getattr(args, "json", False),
+    )
+    return 0
+
+
+def cmd_status(args) -> int:
+    emit(api.status(work_dir_from_args(args)), json_mode=getattr(args, "json", False))
+    return 0