cli-agent-runner 0.1.33__tar.gz → 0.1.35__tar.gz

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.35] - 2026-05-20
+
+### Removed
+- `claude_rate_limit_detector` plugin alias (0.1.20-era back-compat layer after the 0.1.23 rename to `claude_error_detector`). Hard-cut at both entry-point and config-mapping layers. See `docs/migrations/0.1.35.md` for the 1-line TOML migration.
+
+## [0.1.34] - 2026-05-20
+
+### Added
+- New verb `agent-runner events --kind K[,K2,...] [--window N] [--tail]` for event-stream observation. One-shot or streaming mode (JSON Lines output). Verbs: 13 → 14.
+- `SystemMetrics.agent_process_count: int` — `pgrep -xc` of agent binary basename, host-wide. Surfaces orphan agent processes in peek output.
+- `docs/plugins.md` worked example for custom monitor detector with plugin-emitted exempt flag — pattern for project-specific detectors that exclude exempt-by-design rounds.
+
+### Removed
+- `peek --select events.<kind>` selector (mis-placed in state-snapshot verb). Use `events --kind <kind>` instead. 1-line `s///` migration.
+
+See `docs/migrations/0.1.34.md`.
+
 ## [0.1.33] - 2026-05-19
 
 ### Added

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.33
+Version: 0.1.35
 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
@@ -80,14 +80,14 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 13 verbs
+## 16 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
-| `round` / `serve` | |
+| `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/README.md

@@ -43,14 +43,14 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 13 verbs
+## 16 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
-| `round` / `serve` | |
+| `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/README.zh.md

@@ -20,9 +20,9 @@ supervisor 重启 —— 这是核心模式。中间穿插 11 条防御，避开
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3：Witness（monitor）              │  9 个检测器 + 自动停服
+│ Layer 3：Witness（monitor）              │  11 个检测器 + 自动停服
 ├──────────────────────────────────────────┤
-│ Layer 2：Loop（serve，~60 LOC 薄壳）     │  捕获信号，循环拉起 round
+│ Layer 2：Loop（serve，~120 LOC 薄壳）    │  捕获信号，循环拉起 round
 ├──────────────────────────────────────────┤
 │ Layer 1：Round（round）                  │  跑一次 agent，跑完即退
 └──────────────────────────────────────────┘
@@ -57,14 +57,14 @@ agent-runner monitor              # 实时异常检测，OAuth/磁盘 critical
 
 完整上手流程：[`docs/quickstart.md`](docs/quickstart.md)。
 
-## 13 个动词
+## 16 个动词
 
 | 生命周期 | 观察 |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` —— 项目状态快照 |
 | `start` / `stop` / `kill` / `cancel` | `watch` —— peek 在刷新循环里 |
-| `restart` / `status` | `monitor` —— 9 个检测器 + 告警 + 自动停服 |
-| `round` / `serve` | |
+| `restart` / `status` | `monitor` —— 11 个检测器 + 告警 + 自动停服 |
+| `round` / `serve` / `upgrade` | `events` —— 查询 / 流式订阅 events.jsonl |
 
 **停服三动词**有清晰的语义分层：
 - `stop` —— 优雅，等当前 round 跑完再退（最常用）

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/__init__.py

@@ -20,11 +20,6 @@ _HOOK_GROUPS = (
 # Surfaced via peek --json `plugins.disabled` for operator visibility.
 _DISABLED_PLUGIN_NAMES: list[str] = []
 
-# Plugin name aliases for back-compat: old entry-point name -> canonical name.
-_PLUGIN_NAME_ALIASES: dict[str, str] = {
-    "claude_rate_limit_detector": "claude_error_detector",  # 0.1.20 -> 0.1.23 rename
-}
-
 
 def _load_plugins_from_group(group: str) -> None:
     """Discover and load entry_points in ``group``, isolating per-plugin failures.
@@ -98,9 +93,6 @@ def apply_plugin_disable(names: list[str]) -> None:
     if not names:
         return
 
-    # Translate aliases so old config names keep working
-    names = [_PLUGIN_NAME_ALIASES.get(n, n) for n in names]
-
     global _DISABLED_PLUGIN_NAMES
     _DISABLED_PLUGIN_NAMES = list(names)
 

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/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.33'
-__version_tuple__ = version_tuple = (0, 1, 33)
+__version__ = version = '0.1.35'
+__version_tuple__ = version_tuple = (0, 1, 35)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/api_types.py

@@ -56,6 +56,7 @@ class SystemMetrics:
     disk_free_gb: float = 0.0
     load_1m: float | None = None
     cpu_pct: float | None = None
+    agent_process_count: int = 0  # 0.1.34 — pgrep -xc <agent_binary>, host-wide
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/builtin_plugins/claude_rate_limit.py

@@ -7,10 +7,9 @@ with computed reset_at_epoch. Supervisor consumes the event.
 Also emits agent_usage_recorded per-round with token/cost data from the
 claude result event (0.1.24+).
 
-Naming history: was `claude_rate_limit_detector` in 0.1.20 (single-purpose
-rate-limit detector). Renamed + generalized to multi-classification in 0.1.23.
-Old plugin name `claude_rate_limit_detector` retained as entry-point alias
-via pyproject.toml.
+Module name is historical: the original 0.1.20 single-purpose
+rate-limit detector was generalized to multi-classification in 0.1.23
+(class + entry-point renamed to `claude_error_detector`; module path kept).
 """
 
 from __future__ import annotations

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/cli/__init__.py

@@ -17,6 +17,7 @@ from pathlib import Path
 
 from agent_runner import __version__
 from agent_runner.cli import (
+    events_cmd,
     init_cmd,
     install_cmd,
     monitor_cmd,
@@ -63,6 +64,7 @@ def _build_parser() -> argparse.ArgumentParser:
     install_cmd.add_parser(sub, parent)
     service_cmd.add_parser(sub, parent)
     peek_cmd.add_parser(sub, parent)
+    events_cmd.add_parser(sub, parent)
     monitor_cmd.add_parser(sub, parent)
     serve_cmd.add_parser(sub, parent)
     round_cmd.add_parser(sub, parent)

cli_agent_runner-0.1.35/agent_runner/cli/events_cmd.py

@@ -0,0 +1,188 @@
+"""agent-runner events — event-stream observation verb (0.1.34+).
+
+One-shot (--window N) or streaming (--tail) query against events.jsonl.
+JSON Lines output (one JSON object per line, no pretty-print).
+
+Current-month scope only. Tail mode follows month rollover via per-poll glob.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+# Sentinel for "user did not explicitly set --window" so we can detect
+# --window + --tail combinations. argparse mutually-exclusive group would
+# be cleaner but argparse doesn't support "exclusive only when X has value Y".
+_WINDOW_DEFAULT_SENTINEL = -1
+
+
+def _positive_int(s: str) -> int:
+    """Parse positive integer (duplicate of peek_cmd._positive_int; KISS)."""
+    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 _parse_kinds(raw: str) -> set[str]:
+    """Parse comma-separated kinds; strip whitespace; reject empty."""
+    parts = [k.strip() for k in (raw or "").split(",") if k.strip()]
+    return set(parts)
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser(
+        "events",
+        parents=[parent],
+        help="Query / stream events from events.jsonl by kind",
+    )
+    p.add_argument(
+        "--kind",
+        type=str,
+        required=True,
+        metavar="K[,K2,...]",
+        help="Comma-separated event kinds (OR-filtered). At least one required.",
+    )
+    p.add_argument(
+        "--window",
+        type=_positive_int,
+        default=_WINDOW_DEFAULT_SENTINEL,
+        metavar="N",
+        help="One-shot mode: emit last N matching events (default 10).",
+    )
+    p.add_argument(
+        "--tail",
+        action="store_true",
+        help=("Streaming mode: emit each new matching event as it fires (blocks until SIGINT)."),
+    )
+    p.set_defaults(func=cmd_events)
+
+
+def _resolve_log_dir(args) -> Path:
+    """Resolve log_dir from --config (used by both cmd_events and tests)."""
+    if getattr(args, "_log_dir_override", None) is not None:
+        return args._log_dir_override
+    from agent_runner.cli.common import work_dir_from_args
+    from agent_runner.config import load_config
+
+    cfg = load_config(work_dir_from_args(args) / "agent-runner.toml")
+    return cfg.runtime.log_dir
+
+
+def cmd_events(args) -> int:
+    kind_set = _parse_kinds(args.kind)
+    if not kind_set:
+        print(
+            "Error: --kind requires at least one non-empty event kind",
+            file=sys.stderr,
+        )
+        return 2
+
+    window_explicit = getattr(args, "_window_explicit", False) or (
+        args.window != _WINDOW_DEFAULT_SENTINEL
+    )
+    if args.tail and window_explicit:
+        print(
+            "Error: --window and --tail are mutually exclusive",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        log_dir = _resolve_log_dir(args)
+    except FileNotFoundError as e:
+        print(f"Error: config not found: {e}", file=sys.stderr)
+        return 1
+
+    if args.tail:
+        return _tail_events(log_dir, kind_set)
+
+    window = args.window if args.window != _WINDOW_DEFAULT_SENTINEL else 10
+    return _query_events(log_dir, kind_set, window)
+
+
+def _current_month_events_file(log_dir: Path) -> Path:
+    month = datetime.now(UTC).strftime("%Y-%m")
+    return log_dir / f"events-{month}.jsonl"
+
+
+def _query_events(log_dir: Path, kind_set: set[str], window: int) -> int:
+    """One-shot: read current-month events.jsonl, filter, print last N."""
+    events_file = _current_month_events_file(log_dir)
+    if not events_file.exists():
+        return 0
+
+    matches: list[str] = []
+    try:
+        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") in kind_set:
+                    matches.append(line)
+    except OSError as e:
+        print(f"Error: events file unreadable: {e}", file=sys.stderr)
+        return 1
+
+    for line in matches[-window:]:
+        print(line)
+    return 0
+
+
+def _tail_events(log_dir: Path, kind_set: set[str]) -> int:
+    """Streaming: poll current-month events.jsonl at 1s interval; emit each
+    new matching line as it fires. Blocks until SIGINT (KeyboardInterrupt).
+    Follows month rollover via per-poll glob.
+    """
+    last_size = 0
+    current_file: Path | None = None
+
+    def _handle_sigint(_signum, _frame):
+        raise KeyboardInterrupt()
+
+    signal.signal(signal.SIGINT, _handle_sigint)
+
+    try:
+        while True:
+            events_file = _current_month_events_file(log_dir)
+            if events_file != current_file:
+                # Month rollover OR first iteration: reset offset
+                current_file = events_file
+                last_size = events_file.stat().st_size if events_file.exists() else 0
+
+            if events_file.exists():
+                size = events_file.stat().st_size
+                if size > last_size:
+                    with events_file.open("r", encoding="utf-8") as f:
+                        f.seek(last_size)
+                        for line in f:
+                            line = line.strip()
+                            if not line:
+                                continue
+                            try:
+                                evt = json.loads(line)
+                            except json.JSONDecodeError:
+                                continue
+                            if evt.get("event") in kind_set:
+                                print(line, flush=True)
+                    last_size = size
+                elif size < last_size:
+                    # File truncated / rotated underneath us; reset
+                    last_size = 0
+            time.sleep(1.0)
+    except KeyboardInterrupt:
+        return 0

cli_agent_runner-0.1.35/agent_runner/cli/peek_cmd.py

@@ -0,0 +1,85 @@
+"""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=(
+                "Selector: dot-path (e.g. system.disk_used_pct) extracts a subtree from "
+                "peek state. For event-stream queries, use the dedicated `events` verb."
+            ),
+        )
+        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:
+    select = args.select
+    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

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/metrics.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import os
+import subprocess
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -16,7 +17,7 @@ import psutil
 from agent_runner.events import now_iso_ms
 
 
-def collect(disk_path: Path) -> dict[str, Any]:
+def collect(disk_path: Path, *, agent_binary: str | None = None) -> dict[str, Any]:
     vm = psutil.virtual_memory()
     du = psutil.disk_usage(str(disk_path))
     out: dict[str, Any] = {
@@ -38,15 +39,40 @@ def collect(disk_path: Path) -> dict[str, Any]:
         out["cpu_pct"] = round(psutil.cpu_percent(interval=None), 1)
     except Exception:
         pass
+    if agent_binary:
+        out["agent_process_count"] = _count_agent_processes(agent_binary)
     return out
 
 
+def _count_agent_processes(agent_binary: str) -> int:
+    """Run `pgrep -xc <agent_binary>`; return count or 0 on error.
+
+    Host-wide intentional — catches orphan agent processes not parented
+    by us, which is the diagnostic value of this metric.
+    """
+    try:
+        result = subprocess.run(
+            ["pgrep", "-xc", agent_binary],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+        # pgrep -c returns exit 1 with output "0" when no matches; exit 0
+        # with count otherwise. Both are valid; non-int output → 0.
+        if result.returncode in (0, 1):
+            return int(result.stdout.strip() or "0")
+    except (subprocess.SubprocessError, ValueError, FileNotFoundError, OSError):
+        pass
+    return 0
+
+
 def log_metrics(
     log_dir: Path,
     *,
     event: str = "periodic",
     round_num: int | None = None,
     phase: str | None = None,
+    agent_binary: str | None = None,
 ) -> None:
     """Append one metrics sample to metrics-YYYY-MM.jsonl (UTC).
 
@@ -59,7 +85,7 @@ def log_metrics(
     payload: dict[str, Any] = {
         "ts": now_iso_ms(),
         "event": event,
-        **collect(log_dir),
+        **collect(log_dir, agent_binary=agent_binary),
     }
     if round_num is not None:
         payload["round_num"] = round_num

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/monitor.py

@@ -515,6 +515,7 @@ def assemble_project_state(source: StateSource, *, project: str) -> ProjectState
         disk_free_gb=float(latest.get("disk_free_gb", 0.0)),
         load_1m=latest.get("load_1m"),
         cpu_pct=latest.get("cpu_pct"),
+        agent_process_count=int(latest.get("agent_process_count", 0)),
     )
     return ProjectState(
         project=project,

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/agent_runner/runner.py

@@ -441,7 +441,14 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
     context_store.atomic_write_json(log_dir / context_store.CONTEXT_FILE, enriched_ctx)
 
     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)
+    _agent_binary = Path(cfg.agent.command[0]).name if cfg.agent.command else None
+    metrics.log_metrics(
+        log_dir,
+        event="round_start",
+        round_num=round_num,
+        phase=phase,
+        agent_binary=_agent_binary,
+    )
 
     prompt = _api_assemble_prompt(cfg, phase=phase, context=enriched_ctx)
 
@@ -564,7 +571,13 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
             phase_index=phase_idx,
         ),
     )
-    metrics.log_metrics(log_dir, event="round_end", round_num=round_num, phase=phase)
+    metrics.log_metrics(
+        log_dir,
+        event="round_end",
+        round_num=round_num,
+        phase=phase,
+        agent_binary=_agent_binary,
+    )
     events.emit(log_dir, "round_end", round_num=round_num)
 
     round_result = RoundResult(

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.35}/docs/commands.md

@@ -20,6 +20,7 @@ are shared between `peek`, `watch`, and `monitor`.
 | `status` | Show current service state |
 | `peek` | peek project state with optional drill-down |
 | `watch` | watch project state with optional drill-down |
+| `events` | Query / stream events from events.jsonl by kind |
 | `monitor` | Anomaly detection, narrate/events stream, or HTTP progress page |
 | `serve` | Long-running supervisor loop |
 | `round` | Run one round and exit |
@@ -87,12 +88,29 @@ agent-runner peek
 agent-runner peek --json
 agent-runner peek --select system.disk_used_pct
 agent-runner peek --select defenses
-agent-runner peek --select events.agent_usage_recorded --window 5    # 0.1.32+: native event-kind query
-agent-runner peek --select events.transient_error_detected --window 20
 agent-runner peek --round 42 --log         # drill into round 42, include log tail
 agent-runner peek --events 50              # last 50 events
 ```
 
+### `agent-runner events --kind K[,K2,...] [--window N] [--tail]`
+
+Query or stream events.jsonl by kind. Output is always JSON Lines (one event
+JSON per line). Current-month events.jsonl scope only.
+
+```bash
+# One-shot: last 5 usage records
+agent-runner events --kind agent_usage_recorded --window 5
+
+# Multi-kind OR filter
+agent-runner events --kind round_end,hook_failed --window 20
+
+# Streaming: emit each new matching event as it fires; blocks until SIGINT
+agent-runner events --kind transient_error_backoff_capped --tail
+```
+
+`--window N` and `--tail` are mutually exclusive. Exit codes: 0 normal,
+2 invalid arguments, 1 unreadable events file.
+
 ### `agent-runner watch [--interval N] [peek-flags]`
 
 `peek` in a clear-and-refresh loop. Default 2s interval. Stop with Ctrl-C.
@@ -115,7 +133,7 @@ agent-runner monitor --json | jq -c        # pipe alerts to a downstream consume
 
 ## 中文摘要
 
-13 个动词：`init / install / uninstall / start / stop / kill / cancel / restart / status / round / serve / peek / watch / monitor`。
+16 个动词：`init / install / uninstall / start / stop / kill / cancel / restart / status / round / serve / upgrade / peek / watch / events / monitor`。
 
 观察类（peek/watch/monitor）三视角对称，全部共用 `--round / --log / --events / --select / --json` 下钻参数。