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

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

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.33
+Version: 0.1.34
 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
+## 14 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.34}/README.md

@@ -43,14 +43,14 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 13 verbs
+## 14 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.34}/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.34'
+__version_tuple__ = version_tuple = (0, 1, 34)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.33 → cli_agent_runner-0.1.34}/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.34}/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.34/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.34/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.34}/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.34}/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.34}/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.34}/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.

cli_agent_runner-0.1.34/docs/migrations/0.1.34.md

@@ -0,0 +1,110 @@
+# 0.1.34 — `events` verb + plugin pattern + `agent_process_count`
+
+**Date**: 2026-05-20
+
+## What changed
+
+Three additive improvements + one hard-cut cleanup:
+
+1. **New `events` verb** for event-stream observation. One-shot query
+   (`--window N`) or streaming (`--tail`) modes. Multi-kind OR filter via
+   `--kind K[,K2,...]`. JSON Lines output, machine consumption ready.
+2. **`SystemMetrics.agent_process_count`** — `pgrep -xc <agent binary>`
+   snapshot, host-wide. Surfaces orphan agent processes in peek output.
+3. **`docs/plugins.md` worked example** for project-specific monitor
+   detectors with plugin-emitted exempt flag. Pattern reference for
+   detectors like "no-commit-rounds stuck" or "wall-time trend" that
+   need to exclude exempt-by-design rounds.
+4. **Removed `peek --select events.<kind>` selector** from 0.1.32. The
+   events.<kind> form was mis-placed in `peek` (state snapshot verb); the
+   new `events` verb owns event-stream queries. Other peek selectors
+   (`system.*`, `defenses`, `plugins.*`) unchanged.
+
+## Migration
+
+### Consumer using `peek --select events.<kind>` (added 0.1.32, 2 days ago)
+
+One-line `s///`:
+
+```diff
+- agent-runner peek --select events.agent_usage_recorded --window 5
++ agent-runner events --kind agent_usage_recorded --window 5
+```
+
+Same scope (current-month events.jsonl), same default window (10).
+
+### Why hard-cut instead of deprecation window
+
+Consumers are still in test-mode integration; the 0.1.32 selector shipped
+2 days ago. Hard-cutting now (before production lock-in) is cheaper than
+carrying back-compat indefinitely. Same rationale as 0.1.29 alias removal.
+
+## `events` verb usage
+
+```bash
+# One-shot: last 5 events of one kind (default window=10)
+agent-runner events --kind agent_usage_recorded --window 5
+
+# Multi-kind OR filter
+agent-runner events --kind round_end,hook_failed,transient_error_backoff_capped --window 20
+
+# Streaming: emit each new matching event as it fires; blocks until SIGINT
+agent-runner events --kind anomaly_repetitive_tool --tail
+```
+
+`--window N` and `--tail` are mutually exclusive (exit 2 on combination).
+Tail mode polls events.jsonl at 1s interval and follows next-month rollover
+via per-poll glob (no need to restart at month boundary).
+
+Pipe to `jq` for richer filtering / projection:
+
+```bash
+agent-runner events --kind transient_error_backoff_capped --tail \
+  | jq -c '{ts, classification, consecutive_count, applied_reset_at_epoch}'
+```
+
+## `agent_process_count` in peek output
+
+```bash
+agent-runner peek --json | jq .system.agent_process_count
+```
+
+Host-wide count of processes matching the agent binary basename
+(`pgrep -xc <basename of agent.command[0]>`). Catches orphan agent
+processes not parented by agent-runner — diagnostic value for "is there
+a stuck claude lingering?"
+
+If `pgrep` is unavailable or errors, count is reported as `0`.
+
+## Plugin authors: project-specific detectors
+
+See `docs/plugins.md` § "Worked example: project-specific monitor detector
+with plugin-emitted exempt flag" for an end-to-end pattern. Use it for:
+
+- No-commit-rounds stuck detection (count commits per round, exempt
+  short / nothing-to-do iterations)
+- Wall-time trend detection (avg recent vs older, exempt rounds where
+  trend signal is irrelevant)
+- Any other project-specific detector where some rounds should be
+  excluded from the detection criterion
+
+The pattern: plugin emits `<plugin>_round_exempt` event for exempt
+rounds; custom detector reads events.jsonl tail, builds exempt set,
+filters, applies its own logic.
+
+## What did NOT change
+
+- `events.jsonl` schema / event kinds — unchanged
+- All other `peek` selectors (`system.*`, `defenses`, `plugins.*`,
+  `current_round.*`, etc.) — unchanged
+- `agent-runner monitor` — unchanged (its detector loop is separate from
+  the new `events` verb)
+- Plugin extension points (`register_post_round_hook`,
+  `register_custom_detector`, etc.) — unchanged
+- Public Python API beyond the new field on SystemMetrics — unchanged
+- Config schema — no new TOML keys
+- `_BUILTIN_KINDS` — unchanged (no new event kinds in this release)
+
+## No consumer action required (except the 1-line `s///` above)
+
+If you don't use `peek --select events.<kind>`, no migration step.