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

agent_runner/config.py

@@ -0,0 +1,92 @@
+"""TOML config loader with dataclass-based validation."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    command: list[str]
+    prompt_arg_template: list[str]
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    work_dir: Path
+    log_dir: Path
+    round_timeout_s: int = 1800
+    restart_delay_s: int = 3
+
+
+@dataclass(frozen=True)
+class PromptConfig:
+    file: Path
+    inject_context: bool = True
+
+
+@dataclass(frozen=True)
+class VcsConfig:
+    orphan_action: str = "stash"
+    stash_idempotency_s: int = 5
+
+
+@dataclass(frozen=True)
+class Config:
+    agent: AgentConfig
+    runtime: RuntimeConfig
+    prompt: PromptConfig
+    vcs: VcsConfig = field(default_factory=VcsConfig)
+    phases: list[str] | None = None
+
+
+def _require(d: dict, *path: str) -> object:
+    cur: object = d
+    for p in path:
+        if not isinstance(cur, dict) or p not in cur:
+            raise ValueError(f"missing required field: {'.'.join(path)}")
+        cur = cur[p]
+    return cur
+
+
+def _expand_path(s: str, project_name: str) -> Path:
+    return Path(s.replace("{project}", project_name)).expanduser()
+
+
+def load_config(toml_path: Path) -> Config:
+    if not toml_path.exists():
+        raise FileNotFoundError(f"config not found: {toml_path}")
+    with toml_path.open("rb") as f:
+        raw = tomllib.load(f)
+
+    agent = AgentConfig(
+        command=list(_require(raw, "agent", "command")),
+        prompt_arg_template=list(_require(raw, "agent", "prompt_arg_template")),
+    )
+    raw_work_dir = str(_require(raw, "runtime", "work_dir"))
+    work_dir = _expand_path(raw_work_dir, "").resolve()
+    project_name = work_dir.name or "default"
+
+    runtime_d = raw.get("runtime", {})
+    runtime = RuntimeConfig(
+        work_dir=work_dir,
+        log_dir=_expand_path(str(_require(raw, "runtime", "log_dir")), project_name),
+        round_timeout_s=int(runtime_d.get("round_timeout_s", 1800)),
+        restart_delay_s=int(runtime_d.get("restart_delay_s", 3)),
+    )
+    prompt_d = raw.get("prompt", {})
+    prompt = PromptConfig(
+        file=_expand_path(str(_require(raw, "prompt", "file")), project_name),
+        inject_context=bool(prompt_d.get("inject_context", True)),
+    )
+    vcs_d = raw.get("vcs", {})
+    vcs = VcsConfig(
+        orphan_action=str(vcs_d.get("orphan_action", "stash")),
+        stash_idempotency_s=int(vcs_d.get("stash_idempotency_s", 5)),
+    )
+    phases_d = raw.get("phases", {})
+    phases = list(phases_d["list"]) if "list" in phases_d else None
+
+    return Config(agent=agent, runtime=runtime, prompt=prompt, vcs=vcs, phases=phases)

agent_runner/context_store.py

@@ -0,0 +1,117 @@
+"""Persistent JSON state — status / round-context / orphan-state, atomic writes."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+STATUS_FILE = "status.json"
+CONTEXT_FILE = "round-context.json"
+ORPHAN_FILE = "orphan-state.json"
+
+
+@dataclass(frozen=True)
+class Status:
+    round_num: int
+    running: bool
+    last_completed_at: str | None = None
+    last_exit_code: int | None = None
+    last_duration_s: float | None = None
+    current_phase: str | None = None
+    phase_index: int = 0
+
+
+@dataclass(frozen=True)
+class OrphanState:
+    round_num: int
+    files: list[str]
+    stashed_ref: str | None
+    stash_message: str | None
+    timestamp: str
+    phase: str | None = None
+
+
+def atomic_write_json(path: Path, payload: dict[str, Any] | list[Any]) -> None:
+    """Write JSON atomically: tmp file in same dir, fsync, rename."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2, ensure_ascii=False)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def read_json(path: Path) -> dict[str, Any] | None:
+    """Read + parse JSON; return None on missing file or parse failure.
+
+    Single TOCTOU-free read replaces three near-identical exists+read patterns.
+    """
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def write_status(log_dir: Path, status: Status) -> None:
+    payload = {k: v for k, v in asdict(status).items() if v is not None or isinstance(v, bool)}
+    atomic_write_json(log_dir / STATUS_FILE, payload)
+
+
+def read_status(log_dir: Path) -> Status | None:
+    data = read_json(log_dir / STATUS_FILE)
+    if data is None:
+        return None
+    try:
+        return Status(**data)
+    except TypeError:
+        return None
+
+
+def write_round_context(
+    log_dir: Path,
+    *,
+    round_num: int,
+    started_at: str,
+    phase: str | None = None,
+    previous: dict[str, Any] | None = None,
+    orphan_stash: dict[str, Any] | None = None,
+) -> None:
+    ctx: dict[str, Any] = {"round_num": round_num, "started_at": started_at}
+    if phase is not None:
+        ctx["phase"] = phase
+    if previous is not None:
+        ctx["previous"] = previous
+    if orphan_stash is not None:
+        ctx["orphan_stash"] = orphan_stash
+    atomic_write_json(log_dir / CONTEXT_FILE, ctx)
+
+
+def read_round_context(log_dir: Path) -> dict[str, Any] | None:
+    return read_json(log_dir / CONTEXT_FILE)
+
+
+def write_orphan_state(log_dir: Path, state: OrphanState) -> None:
+    atomic_write_json(log_dir / ORPHAN_FILE, asdict(state))
+
+
+def read_orphan_state(log_dir: Path) -> OrphanState | None:
+    data = read_json(log_dir / ORPHAN_FILE)
+    if data is None:
+        return None
+    try:
+        return OrphanState(**data)
+    except TypeError:
+        return None
+
+
+def clear_orphan_state(log_dir: Path) -> None:
+    (log_dir / ORPHAN_FILE).unlink(missing_ok=True)

agent_runner/critic.py

@@ -0,0 +1,33 @@
+"""Phase 3 critic interface — empty stub in Phase 2.
+
+A Critic analyses the current ProjectState (recent rounds, defenses, events)
+and emits Findings: drift / dark-code / inefficiency observations that should
+be fed into the next round's prompt context or recorded for the operator.
+
+Phase 3 implements concrete Critics (LLM-backed, invariant-runner, etc.).
+Phase 2 ships only the Protocols so the rest of the system can reference
+the type without committing to an implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from agent_runner.api_types import ProjectState
+
+
+@runtime_checkable
+class Finding(Protocol):
+    """A single observation emitted by a Critic."""
+
+    severity: str  # "info" | "warning" | "critical"
+    detector: str  # critic-defined identifier
+    message: str
+    suggested_action: str | None
+
+
+@runtime_checkable
+class Critic(Protocol):
+    """Phase 3 implements: analyse a ProjectState snapshot, return findings."""
+
+    def analyze(self, state: ProjectState) -> list[Finding]: ...

agent_runner/defenses.py

@@ -0,0 +1,111 @@
+"""Structured catalog of supervisor defenses.
+
+Each defense is a tuple of (current value, what historical incident it codifies,
+which invariant test guards it, current health). This is the single source of
+truth — peek/status/start banner all import from here.
+
+Adding a new defense = one entry here + auto-surfaces everywhere via the API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from agent_runner.agent_runtime import CRITICAL_ENV_DEFAULTS
+from agent_runner.config import Config
+
+
+@dataclass(frozen=True)
+class Defense:
+    name: str
+    value: Any
+    codifies: str | None
+    guarded_by: Path | None
+    current_state: str  # "active" | "degraded" | "off"
+
+
+def catalog(cfg: Config) -> list[Defense]:
+    """Return the 11-entry defense catalog parameterised by current config."""
+    return [
+        Defense(
+            name="round_timeout_s",
+            value=cfg.runtime.round_timeout_s,
+            codifies="R1128 — TaskOutput polling loop 60min, scheduler grace fails to trigger",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="process_group_isolation",
+            value="start_new_session=True",
+            codifies="#307 — process group reaping for descendant cleanup",
+            guarded_by=Path("tests/unit/test_agent_runtime.py"),
+            current_state="active",
+        ),
+        Defense(
+            name="sigterm_reaper",
+            value="install_sigterm_reaper",
+            codifies="R725 — SIGTERM-during-round dual-claude race",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="orphan_stash_idempotency_s",
+            value=cfg.vcs.stash_idempotency_s,
+            codifies="R820 — same-second 3 phantom stashes",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="sha_locked_stash",
+            value="drop/pop accept SHA only",
+            codifies="§9 IMMUTABLE — batch drop by index breaks under concurrent stash",
+            guarded_by=Path("tests/invariants/test_stash_uses_sha_not_index.py"),
+            current_state="active",
+        ),
+        Defense(
+            name="set_diff_classification",
+            value="set_diff_vs_head",
+            codifies="R2110 — rotation-only diff via +-line scan misclassifies",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="critical_envs_injection",
+            value=list(CRITICAL_ENV_DEFAULTS.keys()),
+            codifies=(
+                "DISABLE_AUTOUPDATER + CLAUDE_CODE_EFFORT_LEVEL stop claude self-updates mid-loop"
+            ),
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="startup_smoke_check",
+            value="6 checks (config / log_dir / agent_cli / git / prompt_file / prompt_smoke)",
+            codifies="R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="flock_concurrency",
+            value="agent-runner.lock",
+            codifies="Phase 1 design — prevent concurrent supervisors corrupting state",
+            guarded_by=None,
+            current_state="active",
+        ),
+        Defense(
+            name="atomic_state_writes",
+            value="tmp + fsync + rename",
+            codifies="Data integrity — crashes never leave half-written state files",
+            guarded_by=Path("tests/invariants/test_atomic_write_enforced.py"),
+            current_state="active",
+        ),
+        Defense(
+            name="event_kind_registry",
+            value="KNOWN_EVENT_KINDS frozenset (14 kinds)",
+            codifies="Prevent events.emit() typos / unregistered kinds slipping past CI",
+            guarded_by=Path("tests/invariants/test_event_kind_registry.py"),
+            current_state="active",
+        ),
+    ]

agent_runner/events.py

@@ -0,0 +1,53 @@
+"""Structured event emitter — JSON Lines, monthly UTC naming."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+KNOWN_EVENT_KINDS = frozenset(
+    {
+        "round_start",
+        "agent_spawn",
+        "agent_exit",
+        "dirty_detected",
+        "orphan_stashed",
+        "orphan_idempotent_skip",
+        "orphan_stash_failed",
+        "round_timeout_kill",
+        "sigterm_received",
+        "status_recovered",
+        "smoke_check_failed",
+        "round_end",
+        # Phase 2 monitor events
+        "monitor_alert_emitted",  # any detector fired (info/warning)
+        "monitor_auto_stop_triggered",  # critical alert triggered service stop
+    }
+)
+
+
+def now_iso_ms() -> str:
+    """UTC ISO-8601 timestamp with millisecond precision and trailing 'Z'.
+
+    Shared helper — also used by metrics.py and runner.py for matching format.
+    """
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def emit(log_dir: Path, kind: str, **fields: Any) -> None:
+    """Append one event line to events-YYYY-MM.jsonl (UTC).
+
+    Caller must ensure ``log_dir`` exists (runner.run_one_round does this once
+    per round; tests use the ``tmp_log_dir`` fixture which creates it).
+    """
+    if kind not in KNOWN_EVENT_KINDS:
+        raise ValueError(f"unknown event kind: {kind!r}")
+    now = datetime.now(UTC)
+    month = now.strftime("%Y-%m")
+    ts = now.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    path = log_dir / f"events-{month}.jsonl"
+    payload = {"ts": ts, "event": kind, **fields}
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(payload, ensure_ascii=False) + "\n")

agent_runner/lifecycle.py

@@ -0,0 +1,67 @@
+"""Service-lifecycle primitives: PID files, signal sending, service-mode detection.
+
+Used by ``cli/serve_cmd.py`` (writes serve.pid) and ``cli/service_cmd.py``
+(reads PID + signals it for stop/kill/cancel). Also tells callers whether the
+project is managed by systemd-user or a plain serve process.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_runner.api_types import ServiceMode
+
+
+@dataclass(frozen=True)
+class PIDFile:
+    path: Path
+
+    def write(self, pid: int) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(str(pid))
+
+    def read(self) -> int | None:
+        try:
+            return int(self.path.read_text().strip())
+        except (FileNotFoundError, ValueError):
+            return None
+
+    def unlink(self) -> None:
+        self.path.unlink(missing_ok=True)
+
+
+def pid_alive(pid: int) -> bool:
+    """True iff the process exists and we have permission to signal it."""
+    try:
+        os.kill(pid, 0)
+    except (ProcessLookupError, PermissionError):
+        return False
+    except OSError:
+        return False
+    return True
+
+
+def send_signal_to_pid(pid: int, sig: int) -> bool:
+    """Send ``sig`` to ``pid``. Returns True on success, False if pid gone / forbidden."""
+    try:
+        os.kill(pid, sig)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def _user_systemd_dir() -> Path:
+    """Patchable in tests."""
+    return Path.home() / ".config" / "systemd" / "user"
+
+
+def detect_service_mode(project: str, *, log_dir: Path) -> ServiceMode:
+    """Decide how this project is managed: systemd unit, plain pidfile, or nothing."""
+    unit = _user_systemd_dir() / f"agent-runner@{project}.service"
+    if unit.exists():
+        return ServiceMode.SYSTEMD_USER
+    if (log_dir / "serve.pid").exists():
+        return ServiceMode.PID_FILE
+    return ServiceMode.NONE

agent_runner/metrics.py

@@ -0,0 +1,69 @@
+"""Cross-platform metrics — mem (system) + disk (log_dir partition) + load + cpu.
+
+Same monthly UTC naming convention as events.jsonl.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import psutil
+
+from agent_runner.events import now_iso_ms
+
+
+def collect(disk_path: Path) -> dict[str, Any]:
+    vm = psutil.virtual_memory()
+    du = psutil.disk_usage(str(disk_path))
+    out: dict[str, Any] = {
+        "mem_total_mb": vm.total // (1024 * 1024),
+        "mem_available_mb": vm.available // (1024 * 1024),
+        "mem_used_pct": round(vm.percent, 1),
+        "disk_total_gb": round(du.total / (1024**3), 1),
+        "disk_free_gb": round(du.free / (1024**3), 1),
+        "disk_used_pct": round(du.percent, 1),
+    }
+    try:
+        load = os.getloadavg()
+        out["load_1m"] = round(load[0], 2)
+        out["load_5m"] = round(load[1], 2)
+        out["load_15m"] = round(load[2], 2)
+    except (AttributeError, OSError):
+        pass
+    try:
+        out["cpu_pct"] = round(psutil.cpu_percent(interval=None), 1)
+    except Exception:
+        pass
+    return out
+
+
+def log_metrics(
+    log_dir: Path,
+    *,
+    event: str = "periodic",
+    round_num: int | None = None,
+    phase: str | None = None,
+) -> None:
+    """Append one metrics sample to metrics-YYYY-MM.jsonl (UTC).
+
+    Caller must ensure ``log_dir`` exists. Disk-usage stats are sampled from
+    ``log_dir``'s partition (callers that wanted a different mount can reach
+    for psutil directly — single-mount is the only real-world case so far).
+    """
+    month = datetime.now(UTC).strftime("%Y-%m")
+    path = log_dir / f"metrics-{month}.jsonl"
+    payload: dict[str, Any] = {
+        "ts": now_iso_ms(),
+        "event": event,
+        **collect(log_dir),
+    }
+    if round_num is not None:
+        payload["round_num"] = round_num
+    if phase is not None:
+        payload["phase"] = phase
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(payload, ensure_ascii=False) + "\n")