cli-agent-runner 0.1.30__tar.gz → 0.1.32__tar.gz

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.32] - 2026-05-18
+
+### Added
+- `[monitor] round_progress_interval_s` — heartbeat `round_progress` event during a live round (log_size_kb, last_write_age_s, wall_age_s). Default 0 = disabled.
+- `agent-runner peek --select events.<kind> [--window N]` — native selector for events.jsonl query (replaces `tail -F | grep | jq` patterns). Current-month only.
+- `[monitor.host_health]` config section — `mem_avail_min_mb` / `disk_warning_pct` / `disk_critical_pct` thresholds for `mem_pressure` / `disk_warning` / `disk_critical` detectors. Defaults preserve prior behavior.
+- New monitor detector `anomaly_repetitive_active` (notify) — alerts when `anomaly_repetitive_tool` events fire in recent rounds. Detector count 10 → 11.
+
+See `docs/migrations/0.1.32.md`.
+
+## [0.1.31] - 2026-05-18
+
+### Added
+- `[runtime] max_grace_after_result_s` — kill subprocess that emits `type=result` then sits silent for N seconds (0 = disabled). New `round_grace_kill` event distinguishes from regular `round_timeout_kill`.
+- `[monitor] anomaly_repetitive_window` + `anomaly_repetitive_threshold` — claude plugin emits `anomaly_repetitive_tool` event when same (tool, target) appears ≥threshold times in window-sized tool stream. Specific scar pattern; both 0 = disabled.
+- `[runtime] dry_run` boolean exposed via `HookContext.dry_run` for plugin authors to skip side-effect actions when set.
+- Documentation: TOML changes require daemon restart (no hot-reload); phase rotation indexing clarification.
+
+See `docs/migrations/0.1.31.md`.
+
 ## [0.1.30] - 2026-05-18
 
 ### Fixed

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.30
+Version: 0.1.32
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme
@@ -49,7 +49,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  10 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -86,7 +86,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 10 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` | |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
@@ -106,10 +106,11 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
-## Monitor: 10 detectors
+## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`.
+`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`,
+`anomaly_repetitive_active`.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/README.md

@@ -12,7 +12,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  10 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -49,7 +49,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 10 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` | |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
@@ -69,10 +69,11 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
-## Monitor: 10 detectors
+## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`.
+`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`,
+`anomaly_repetitive_active`.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/_emit.py

@@ -15,9 +15,12 @@ from pathlib import Path
 
 __all__ = [
     "emit_agent_usage_recorded",
+    "emit_anomaly_repetitive_tool",
     "emit_fresh_eyes_round_triggered",
     "emit_max_rounds_reached",
     "emit_rate_limit_stop",
+    "emit_round_grace_kill",
+    "emit_round_progress",
     "emit_round_substrate_after",
     "emit_round_substrate_before",
     "emit_stop_file_detected",
@@ -199,6 +202,78 @@ def emit_agent_usage_recorded(
     )
 
 
+def emit_round_progress(
+    log_dir: Path,
+    *,
+    round_num: int,
+    log_size_kb: int,
+    last_write_age_s: int,
+    wall_age_s: int,
+) -> None:
+    """Mid-round heartbeat event when round_progress_interval_s > 0.
+
+    Emitted periodically during a live round to surface visibility on long
+    rounds: log_size_kb shows writing activity; last_write_age_s and wall_age_s
+    together distinguish "agent thinking" from "agent stuck".
+    """
+    from agent_runner.events import ROUND_PROGRESS, emit
+
+    emit(
+        log_dir,
+        ROUND_PROGRESS,
+        round_num=round_num,
+        log_size_kb=log_size_kb,
+        last_write_age_s=last_write_age_s,
+        wall_age_s=wall_age_s,
+    )
+
+
+def emit_round_grace_kill(
+    log_dir: Path,
+    *,
+    round_num: int,
+    grace_s: int,
+) -> None:
+    """Emit when subprocess killed because grace-after-result timer expired.
+
+    Subprocess emitted type=result in JSONL log then sat silent for longer
+    than max_grace_after_result_s seconds. Distinguishes from round_timeout_kill
+    (wall-clock exceeded without result event).
+    """
+    from agent_runner.events import ROUND_GRACE_KILL, emit
+
+    emit(log_dir, ROUND_GRACE_KILL, round_num=round_num, grace_s=grace_s)
+
+
+def emit_anomaly_repetitive_tool(
+    log_dir: Path,
+    *,
+    round_num: int,
+    tool_name: str,
+    target: str | None,
+    count: int,
+    window: int,
+) -> None:
+    """Emit when claude plugin detects the same (tool, target) tuple repeated
+    >= threshold times in a sliding window of tool-call events.
+
+    Claude-only (gemini JSONL stats summary does not expose per-tool events).
+    Default OFF: both anomaly_repetitive_window and anomaly_repetitive_threshold
+    must be > 0 in [monitor] config to activate.
+    """
+    from agent_runner.events import ANOMALY_REPETITIVE_TOOL, emit
+
+    emit(
+        log_dir,
+        ANOMALY_REPETITIVE_TOOL,
+        round_num=round_num,
+        tool_name=tool_name,
+        target=target,
+        count=count,
+        window=window,
+    )
+
+
 def emit_transient_error_backoff_capped(
     log_dir: Path,
     *,

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.30'
-__version_tuple__ = version_tuple = (0, 1, 30)
+__version__ = version = '0.1.32'
+__version_tuple__ = version_tuple = (0, 1, 32)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/agent_runtime.py

@@ -27,6 +27,7 @@ class RunResult:
     duration_s: float
     timed_out: bool
     pid: int
+    killed_for_grace: bool = False
 
 
 def _build_argv(command: list[str], prompt_arg_template: list[str], prompt: str) -> list[str]:
@@ -53,6 +54,12 @@ def _kill_pgroup(proc: subprocess.Popen) -> None:
         pass
 
 
+# Exact compact bytes — matches claude CLI's no-whitespace JSONL output.
+# A future CLI variant emitting `{"type": "result", ...}` (with space) would
+# bypass this scan; revisit if that happens.
+_RESULT_MARKER = b'"type":"result"'
+
+
 def run(
     *,
     command: list[str],
@@ -61,16 +68,29 @@ def run(
     timeout_s: int,
     log_path: Path,
     env_extra: dict[str, str],
+    max_grace_after_result_s: int = 0,
+    progress_callback: Callable[[dict], None] | None = None,
+    progress_interval_s: int = 0,
 ) -> RunResult:
     """Spawn the agent subprocess and wait for exit or timeout.
 
     Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
+
+    max_grace_after_result_s: when > 0, start a countdown after the first
+    type=result event is detected in the log; kill if subprocess is still
+    running after this many seconds (HUNG defense). 0 = disabled.
+
+    progress_callback: when not None and progress_interval_s > 0, called every
+    progress_interval_s seconds with a dict of log stats (log_size_kb,
+    last_write_age_s, wall_age_s). Keeps agent_runtime event-free; callers
+    build the callback to emit events.
     """
     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()
+    last_progress_at = start
     proc = subprocess.Popen(
         argv,
         env=env,
@@ -79,6 +99,7 @@ def run(
         stderr=subprocess.STDOUT,
         start_new_session=True,
     )
+    result_seen_at: float | None = None
     try:
         while True:
             ret = proc.poll()
@@ -93,6 +114,45 @@ def run(
                 return RunResult(
                     exit_code=exit_code, duration_s=duration, timed_out=True, pid=proc.pid
                 )
+            # Grace kill: result emitted but subprocess still running
+            if max_grace_after_result_s > 0:
+                if result_seen_at is None:
+                    # Cheap check: byte-scan log for marker substring
+                    try:
+                        with log_path.open("rb") as f:
+                            if _RESULT_MARKER in f.read():
+                                result_seen_at = now
+                    except OSError:
+                        pass  # log not flushed yet; check next tick
+                if result_seen_at is not None and now - result_seen_at > max_grace_after_result_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,
+                        killed_for_grace=True,
+                    )
+            # Progress heartbeat: call back if interval elapsed
+            if progress_callback is not None and progress_interval_s > 0:
+                if now - last_progress_at >= progress_interval_s:
+                    try:
+                        st = log_path.stat()
+                        log_size_kb = st.st_size // 1024
+                        last_write_age_s = max(0, int(now - st.st_mtime))
+                    except OSError:
+                        log_size_kb = 0
+                        last_write_age_s = 0
+                    progress_callback(
+                        {
+                            "log_size_kb": log_size_kb,
+                            "last_write_age_s": last_write_age_s,
+                            "wall_age_s": int(now - start),
+                        }
+                    )
+                    last_progress_at = now
             time.sleep(0.2)
     finally:
         log_file.close()

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/api.py

@@ -455,6 +455,9 @@ def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
         auth_fail_patterns=cfg.monitor.auth_fail_patterns,
         auth_fail_hint=cfg.monitor.auth_fail_hint,
         phases_overrides=cfg.phases.overrides if cfg.phases.overrides else None,
+        mem_avail_min_mb=cfg.monitor.host_health.mem_avail_min_mb,
+        disk_warning_pct=cfg.monitor.host_health.disk_warning_pct,
+        disk_critical_pct=cfg.monitor.host_health.disk_critical_pct,
     )
     if not monitor._PLUGIN_DETECTORS:
         return builtin  # skip ProjectState assembly when no plugins to feed
@@ -725,9 +728,12 @@ def check_self_terminated_sentinel(log_dir: Path) -> bool:
 # Preserves the public import surface: `from agent_runner.api import emit_*` continues to work.
 from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-export
     emit_agent_usage_recorded,
+    emit_anomaly_repetitive_tool,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
+    emit_round_grace_kill,
+    emit_round_progress,
     emit_round_substrate_after,
     emit_round_substrate_before,
     emit_stop_file_detected,

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/api_types.py

@@ -157,6 +157,7 @@ class RoundResult:
     log_path: Path
     dirty_files: list[str]
     stashed: bool
+    killed_for_grace: bool = False
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.1.30 → cli_agent_runner-0.1.32}/agent_runner/builtin_plugins/claude_rate_limit.py

@@ -23,6 +23,7 @@ from typing import Any
 
 from agent_runner.api import (
     emit_agent_usage_recorded,
+    emit_anomaly_repetitive_tool,
     emit_transient_error_detected,
 )
 from agent_runner.builtin_plugins._constants import (
@@ -45,7 +46,11 @@ class ClaudeErrorDetector:
         log_path = ctx.agent_log_path
         if log_path is None or not log_path.exists():
             return
-        parsed = _parse_claude_log(log_path)
+        parsed = _parse_claude_log(
+            log_path,
+            anomaly_window=ctx.anomaly_repetitive_window,
+            anomaly_threshold=ctx.anomaly_repetitive_threshold,
+        )
 
         if parsed.get("transient_error"):
             te = parsed["transient_error"]
@@ -60,18 +65,68 @@ class ClaudeErrorDetector:
                 **parsed["usage"],
             )
 
+        if parsed.get("anomaly"):
+            emit_anomaly_repetitive_tool(ctx.log_dir, round_num=ctx.round_num, **parsed["anomaly"])
+
+
+def _extract_tool_target(tool_input: Any) -> str | None:
+    """Best-effort primary-input extraction for repetition detection."""
+    if not isinstance(tool_input, dict):
+        return None
+    for key in ("file_path", "path", "pattern", "command"):
+        v = tool_input.get(key)
+        if isinstance(v, str):
+            return v[:100]  # truncate long commands
+    return None
+
+
+def _detect_repetitive_tool(
+    tool_calls: list[tuple[str, str | None]],
+    *,
+    window: int,
+    threshold: int,
+) -> dict | None:
+    """Slide a window of size ``window`` over tool_calls; return anomaly dict
+    when any (tool_name, target) tuple appears >= threshold times."""
+    if window <= 0 or threshold <= 0 or len(tool_calls) < threshold:
+        return None
+    from collections import Counter
 
-def _parse_claude_log(log_path: Path) -> dict[str, Any]:
+    n = len(tool_calls)
+    for start in range(max(0, n - window), n - threshold + 1):
+        window_slice = tool_calls[start : start + window]
+        if not window_slice:
+            continue
+        counts = Counter(window_slice)
+        most_common_tuple, most_common_count = counts.most_common(1)[0]
+        if most_common_count >= threshold:
+            return {
+                "tool_name": most_common_tuple[0],
+                "target": most_common_tuple[1],
+                "count": most_common_count,
+                "window": window,
+            }
+    return None
+
+
+def _parse_claude_log(
+    log_path: Path,
+    *,
+    anomaly_window: int = 0,
+    anomaly_threshold: int = 0,
+) -> dict[str, Any]:
     """Scan last _TAIL_LINES for rate_limit/result/assistant events.
 
-    Returns dict with optional 'transient_error' and 'usage' keys.
+    Returns dict with optional 'transient_error', 'usage', and 'anomaly' keys.
+    anomaly_window/anomaly_threshold: when both > 0, slide a window over
+    (tool_name, target) tuples; populate 'anomaly' if threshold reached.
     """
     with log_path.open("r", encoding="utf-8", errors="replace") as f:
         tail = deque(f, maxlen=_TAIL_LINES)
     rate_limit_info: dict | None = None
     result_event: dict | None = None
     assistant_model: str | None = None
-    tool_call_count = 0
+    tool_calls: list[tuple[str, str | None]] = []
     for line in tail:
         line = line.strip()
         if not line:
@@ -94,9 +149,11 @@ def _parse_claude_log(log_path: Path) -> dict[str, Any]:
                 assistant_model = str(model_val)
             content = msg.get("content", []) if isinstance(msg, dict) else []
             if isinstance(content, list):
-                tool_call_count += sum(
-                    1 for c in content if isinstance(c, dict) and c.get("type") == "tool_use"
-                )
+                for c in content:
+                    if isinstance(c, dict) and c.get("type") == "tool_use":
+                        tool_calls.append(
+                            (str(c.get("name", "?")), _extract_tool_target(c.get("input", {})))
+                        )
 
     out: dict[str, Any] = {}
 
@@ -106,11 +163,17 @@ def _parse_claude_log(log_path: Path) -> dict[str, Any]:
 
     if result_event is not None:
         usage_payload = _extract_usage(
-            result_event, model=assistant_model, tool_call_count=tool_call_count
+            result_event, model=assistant_model, tool_call_count=len(tool_calls)
         )
         if usage_payload is not None:
             out["usage"] = usage_payload
 
+    anomaly = _detect_repetitive_tool(
+        tool_calls, window=anomaly_window, threshold=anomaly_threshold
+    )
+    if anomaly is not None:
+        out["anomaly"] = anomaly
+
     return out
 
 

cli_agent_runner-0.1.32/agent_runner/cli/peek_cmd.py

@@ -0,0 +1,156 @@
+"""peek and watch subcommands — snapshot + auto-refresh."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from agent_runner import api
+from agent_runner.cli.common import emit, fail, work_dir_from_args
+from agent_runner.config import load_config
+
+
+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 _positive_int(s: str) -> int:
+    try:
+        n = int(s)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(f"expects positive int, got {s!r}") from e
+    if n <= 0:
+        raise argparse.ArgumentTypeError(f"expects positive int (> 0), got {n}")
+    return n
+
+
+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=(
+                "Selector: 'events.<kind>' queries events.jsonl (current month); "
+                "dot-path (e.g. system.disk_used_pct) extracts a subtree from peek state."
+            ),
+        )
+        p.add_argument(
+            "--window",
+            type=_positive_int,
+            default=10,
+            metavar="N",
+            help="Max entries returned by --select events.<kind> (default 10, must be > 0).",
+        )
+        if verb == "watch":
+            p.add_argument(
+                "--interval",
+                type=int,
+                default=2,
+                metavar="SECONDS",
+                help="Refresh interval (default 2)",
+            )
+        p.set_defaults(func=fn)
+
+
+def _run_events_select(
+    log_dir: Path, *, kind: str, window: int, month_tag: str | None = None
+) -> list[dict]:
+    """Read current-month events.jsonl and return last ``window`` events of ``kind``.
+
+    Only the current month's file is scanned (documented limitation).
+    Returns an empty list when the file is missing or no matching events found.
+    """
+    if month_tag is None:
+        month_tag = datetime.now(UTC).strftime("%Y-%m")
+    events_file = log_dir / f"events-{month_tag}.jsonl"
+    if not events_file.exists():
+        return []
+
+    matches: list[dict] = []
+    with events_file.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                evt = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if evt.get("event") == kind:
+                matches.append(evt)
+
+    return matches[-window:]
+
+
+def cmd_peek(args) -> int:
+    select = args.select
+    # Intercept events.<kind> selector before passing to regular peek logic.
+    if select is not None and select.startswith("events."):
+        kind = select[len("events.") :]
+        if not kind:
+            print("Error: --select events.<kind> requires a non-empty kind", file=sys.stderr)
+            return 2
+        try:
+            cfg = load_config(work_dir_from_args(args) / "agent-runner.toml")
+        except FileNotFoundError as e:
+            return fail(f"config not found: {e}")
+        log_dir = cfg.runtime.log_dir
+        window = getattr(args, "window", 10) or 10
+        matches = _run_events_select(log_dir, kind=kind, window=window)
+        if getattr(args, "json", False):
+            print(json.dumps(matches, default=str))
+        else:
+            for m in matches:
+                print(json.dumps(m, default=str))
+        return 0
+
+    try:
+        result = api.peek(
+            work_dir_from_args(args),
+            round=args.round,
+            log=args.log,
+            events=args.events,
+            select=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