cli-agent-runner 0.1.1__tar.gz → 0.1.7__tar.gz

cli_agent_runner-0.1.7/.githooks/commit-msg

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Reject commit messages that contain AI-tool attribution.
+#
+# Rationale: this repository's history is curated to credit only the human
+# author. AI-tool trailers (Co-Authored-By: Claude, 🤖 Generated with ..., etc.)
+# create false "claude" / "anthropic" entries in GitHub's Contributors widget
+# and bloat commit log noise.
+#
+# Activate per clone:    git config core.hooksPath .githooks
+# Bypass (rarely needed): git commit --no-verify
+
+MSG_FILE="$1"
+
+# Strip git-comment lines before checking
+CONTENT=$(grep -v '^#' "$MSG_FILE" || true)
+
+# Case-insensitive regex; tab/space tolerant
+FORBIDDEN_REGEX='([Cc]o-[Aa]uthored-[Bb]y:|🤖|[Gg]enerated with [Cc]laude|[Gg]enerated with \[Cursor\]|noreply@anthropic\.com)'
+
+if printf '%s\n' "$CONTENT" | grep -E -q "$FORBIDDEN_REGEX"; then
+    echo "" >&2
+    echo "commit-msg hook: AI-tool attribution detected in commit message." >&2
+    echo "" >&2
+    echo "Offending lines:" >&2
+    printf '%s\n' "$CONTENT" | grep -E -n "$FORBIDDEN_REGEX" | sed 's/^/  /' >&2
+    echo "" >&2
+    echo "Strip Co-Authored-By trailers, 🤖, 'Generated with ...', and" >&2
+    echo "noreply@anthropic.com refs, then retry." >&2
+    echo "" >&2
+    echo "(Bypass: git commit --no-verify — use sparingly, requires explicit" >&2
+    echo " review since CI lint-commits job will also reject the push.)" >&2
+    exit 1
+fi

cli_agent_runner-0.1.7/.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-flight runs on the same PR ref when a new push lands.
+# Push-to-main runs always complete (cancel-in-progress only on PRs).
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint-commits:
+    name: lint commit messages (no AI-tool attribution)
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # PR: scan only new commits the PR introduces (base..head).
+          # Push to main: scan the just-pushed commits (before..after).
+          # fetch-depth=0 ensures both refs are available.
+          fetch-depth: 0
+      - name: scan new commit messages
+        env:
+          GH_EVENT: ${{ github.event_name }}
+          BEFORE_SHA: ${{ github.event.before }}
+          BASE_REF: ${{ github.event.pull_request.base.sha }}
+          HEAD_REF: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          if [ "$GH_EVENT" = "pull_request" ]; then
+            RANGE="${BASE_REF}..${HEAD_REF}"
+          else
+            # push event; before is 0..0 on first push or branch creation
+            if [ -z "${BEFORE_SHA:-}" ] || [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              RANGE="HEAD~1..HEAD"
+            else
+              RANGE="${BEFORE_SHA}..HEAD"
+            fi
+          fi
+          echo "Scanning commit-message bodies in $RANGE"
+          # Collect messages joined by NUL bytes; grep -P for fixed alternation.
+          BODIES=$(git log --format='%B%x00' "$RANGE" || true)
+          if [ -z "$BODIES" ]; then
+            echo "  (no commits in range)"
+            exit 0
+          fi
+          PATTERN='(Co-Authored-By:|🤖|Generated with Claude|Generated with \[Cursor\]|noreply@anthropic\.com)'
+          if printf '%s' "$BODIES" | grep -i -E -q "$PATTERN"; then
+            echo "::error::AI-tool attribution detected in new commit messages."
+            echo "Offending lines:"
+            printf '%s' "$BODIES" | grep -i -n -E "$PATTERN" || true
+            echo ""
+            echo "Strip Co-Authored-By trailers, 🤖, 'Generated with ...',"
+            echo "and noreply@anthropic.com refs, then force-push the fixed range."
+            exit 1
+          fi
+          echo "  clean"
+
+  test:
+    name: test py${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest]
+    # Steps below mirror ./build.sh check, inlined for per-step Actions UI
+    # granularity AND because coverage requires extra pytest flags not in
+    # the local `test` task. CONTRIBUTING.md states the parity intentionally.
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: install
+        run: pip install -e ".[dev]"
+      - name: ruff
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: tests with coverage
+        run: pytest -q --ignore=tests/e2e --ignore=tests/literate --cov --cov-report=xml --cov-report=term
+      - name: docs CI gate
+        run: |
+          python -m agent_runner._docgen
+          git diff --exit-code docs/
+      - name: literate quickstart
+        run: pytest tests/literate/ -q
+      - name: upload coverage
+        if: matrix.python == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

cli_agent_runner-0.1.7/CHANGELOG.md

@@ -0,0 +1,293 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.7] - 2026-05-13
+
+### Migration for existing 0.1.6 users (DOWNSTREAM CONSUMERS READ THIS)
+
+If you maintain an `agent-runner.toml` by hand (rather than via `agent-runner init`),
+you must add an `[agent.env]` block to preserve the Claude self-update suppression
+that 0.1.6 injected implicitly. **Without this, mid-loop self-updates can race with
+the supervisor.**
+
+Add to your `agent-runner.toml`:
+
+```toml
+[agent.env]
+DISABLE_AUTOUPDATER = "1"
+CLAUDE_CODE_EFFORT_LEVEL = "xhigh"
+```
+
+Or regenerate cleanly:
+
+```bash
+agent-runner init --preset claude --force
+```
+
+Plugin authors (Argus Gateway, etc.): no public API was renamed or removed
+from your import surface. The deleted symbols (`agent_runner.agent_runtime.CRITICAL_ENV_DEFAULTS`,
+`agent_runner.agent_runtime.merge_critical_envs`) were internal — not part of
+the documented plugin API. A new public-API contract test
+(`tests/contract/test_public_api_surface.py`) locks in `api_types`, `events`,
+`hooks`, `monitor`, `detector_helpers` import surfaces so future refactors
+can't silently drop names you rely on.
+
+### Added
+- `agent-runner init --preset {claude,aider}` selects between bundled CLI presets
+  (default: `claude`). New preset directory: `agent_runner/presets/`.
+- `[agent.env]` TOML block — per-CLI env injections, replacing the hardcoded
+  `CRITICAL_ENV_DEFAULTS` constant. Empty dict by default.
+- `docs/recipes/aider.md` — aider integration recipe.
+- `tests/contract/test_public_api_surface.py` — public-API surface snapshot for
+  plugin authors.
+
+### Changed
+- Core code (`agent_runtime.py`, `config.py`, `runner.py`, `scaffold.py`,
+  `defenses.py`) is now truly provider-agnostic: zero hardcoded Claude defaults.
+  Claude remains the reference example throughout the docs, but its specifics
+  live in `agent_runner/presets/claude.toml` (shipped as package data).
+- `MonitorConfig.auth_fail_hint` default is now empty string; per-CLI hint
+  comes from the preset.
+- `PEEK_SCHEMA_VERSION` bumped 1.3 → 1.4. `InitResult` gains `preset: str` field.
+- `agent_runner/defenses.py` `critical_envs_injection` row now reads from
+  `cfg.agent.env.keys()` (not the deleted constant); state is "active" iff
+  the config defines any env injections, else "off".
+
+### Removed
+- `agent_runner.agent_runtime.CRITICAL_ENV_DEFAULTS` constant.
+- `agent_runner.agent_runtime.merge_critical_envs()` function.
+- `agent_runner.config._DEFAULT_AUTH_HINT` constant's Claude-specific default
+  string (replaced with `""`; per-CLI hint now in preset files).
+
+## [0.1.6] - 2026-05-12
+
+Zero-feature maintenance release — internal cleanup pass after the 0.1.x plugin
+extension surface completed in 0.1.5. No runtime behavior change for users
+without plugins; plugin authors written against 0.1.5 keep working unchanged.
+
+### Changed
+- Public `Alert.severity` / `Alert.auto_action` and `Detector.severity` /
+  `Detector.auto_action` are now typed with `Severity = Literal["info", "warning",
+  "critical"]` and `AutoAction = Literal["none", "stop_service"]` aliases
+  exported from `agent_runner.api_types`. Plain-string values continue to work
+- `__version__` is read from the hatch-vcs generated `_version.py` instead of a
+  hardcoded constant; released packages report the actual release version
+- Internal duplication reduced: shared `agent_runner._registry.ensure_unique`
+  for hooks + detectors registries; `cli/common.emit()` plugin-namespace imports
+  hoisted to module top; `events.parse_iso_ms` centralizes the ISO-8601 trailing-`Z`
+  parsing workaround; `MonitorConfig.auto_stop_on` default now references the
+  `_DEFAULT_AUTO_STOP_ON` constant
+- `monitor.dual_source_silence` is now TOCTOU-safe (uses `try/except
+  FileNotFoundError` instead of `exists()` + `stat()`)
+- `api._poll_once` short-circuits when no plugin detectors are registered,
+  skipping `assemble_project_state` (saves a file read per local poll and an
+  SSH round-trip per remote poll)
+- `agent_runner/__init__.py` plugin loaders share a single
+  `_load_plugins_from_group` helper
+- `monitor._alert` no longer asserts builtin detector names against
+  `KNOWN_ALERT_KINDS` (assertion was redundant and would crash under
+  `python -O`); test + docgen layers continue to validate the builtin name set
+
+### Removed
+- `agent_runner.critic` — empty Protocol stub for an unimplemented Critic
+  concept that was retired during the framework-first redesign
+- `[llm]` commented block from the scaffold TOML template and its corresponding
+  section in `docs/configuration.md` — unused placeholder
+- Legacy phase nomenclature from source docstrings, error messages, and CLI
+  help text; `tests/invariants/test_phase2_*.py` files renamed to drop the
+  `phase2_` prefix
+
+### Backward compatibility
+- Existing `agent-runner.toml` files continue to load (the removed `[llm]`
+  block was never parsed by the supervisor)
+- Plugin code written for 0.1.5 continues to work — Protocol contracts and
+  `peek --json` schema 1.3 unchanged
+
+## [0.1.5] - 2026-05-12
+
+### Added
+- `agent_runner.api_types.Detector` — public Protocol for plugin detectors
+  (attributes `name`, `severity`, `auto_action`; method `detect(state) -> Alert | None`).
+  `@runtime_checkable` — plugin classes structurally satisfying the shape are accepted
+- `agent_runner.monitor.register_detector(detector)` and `plugin_detectors()` — public
+  registration API + sorted list of currently-registered detector names
+- `agent_runner.monitor.run_plugin_detectors(state)` — invokes each registered plugin
+  detector with the assembled `ProjectState`; per-detector exceptions surface as
+  `UserWarning` (round continues)
+- `agent_runner` package now also discovers and loads entry_points in group
+  `agent_runner.detectors` at first import; failures degrade to `UserWarning`
+- `agent_runner.detector_helpers` module — three production-tested helpers for
+  plugin detector authors:
+  - `cumulative_window_check(events, *, kind, window_s, min_count)` —
+    sliding-window event counter; robust against wall-clock skew at boundaries
+  - `dual_source_silence(scheduler_log, round_log, threshold_s)` — both-source
+    silence check; avoids false positives during long rounds when only the
+    scheduler log is stale
+  - `phase_filter(state, *, exclude_phases)` — skip detection during phases
+    that intentionally produce no commits (e.g., retrospective rounds)
+- `MonitorConfig.auto_stop_on: list[str]` — explicit allow-list of detector
+  names whose `stop_service` action is honored. Defaults to
+  `["oauth_fail", "disk_critical"]` (builtin pair); operators must add plugin
+  detector names to opt them into auto-stop
+- `monitor.on_alert` gains `allowed_stop_names: list[str] | None` keyword
+  argument; backward-compatible default falls back to the legacy builtin pair
+- `peek --json` schema bumped to `"1.3"`; new `plugins.detectors: list[str]`
+  surfaces what's registered
+- `docs/plugins.md` gains a Detector Protocol chapter + DetectorHelpers
+  chapter with worked examples for each helper
+
+### Changed
+- `agent_runner.api._poll_once` now concatenates builtin detector alerts
+  with plugin detector alerts (`run_plugin_detectors(state)`) before returning
+- `agent_runner.api.monitor_loop` threads `cfg.monitor.auto_stop_on` into
+  `monitor.on_alert` for strict gating
+- `tests/invariants/test_peek_schema_version.py` tightened to require
+  `schema_version >= "1.3"` and the `plugins.detectors` list shape
+
+### Backward compatibility
+- Zero plugins installed → monitor behavior identical to 0.1.4
+- Existing 9 builtin detectors keep their current signatures unchanged
+- Existing `agent-runner.toml` files load without modification; default
+  `auto_stop_on` matches the previously-implicit behavior
+- `on_alert(...)` callers without the new kwarg continue to work via the
+  default `["oauth_fail", "disk_critical"]` allow-list
+
+## [0.1.4] - 2026-05-12
+
+### Added
+- `agent_runner.hooks` module — three Protocol-typed plugin extension points:
+  `PreRoundHook` (runs after lock acquire, before context write),
+  `ContextEnricher` (returns a per-plugin slice stitched into `round-context.json`
+  under `base_context[enricher.name]`), and `PostRoundHook` (runs after agent exit,
+  before `round_end` event)
+- `agent_runner.hooks.HookContext` — narrow runtime context passed to all hooks
+  (`work_dir`, `log_dir`, `project`, `round_num`, `phase`, `agent_name`); does NOT
+  expose the full `Config` so internal refactors remain safe
+- `agent_runner.hooks.register_pre_round_hook` / `register_context_enricher` /
+  `register_post_round_hook` — public registration API; rejects duplicate `name`
+- `agent_runner.hooks.plugin_context_enrichers()` — sorted list of registered
+  enricher names, surfaced via `peek --json`
+- `agent_runner.api_types.RoundResult` — promoted from `runner.py`; superset of
+  the prior internal fields plus `phase`, `started_at`, `ended_at`, `log_path` for
+  stable `PostRoundHook` consumption
+- `agent_runner` package now also discovers and loads three new entry_points groups
+  at first import: `agent_runner.pre_round_hooks`, `agent_runner.context_enrichers`,
+  `agent_runner.post_round_hooks`; plugin failures degrade to a `UserWarning`
+- Built-in event kind `hook_failed` — emitted by the runner whenever a plugin hook
+  raises; payload includes `{hook_name, hook_kind, error_type, error_message, traceback}`
+  with traceback truncated to 2KB (head 1KB + tail 1KB joined by `[truncated]`)
+- `peek --json` schema bumped to `"1.2"`; new `plugins.context_enrichers: list[str]`
+- `docs/plugins.md` — new chapter with end-to-end ContextEnricher example
+- New invariant `tests/invariants/test_round_result_stable.py` guards `RoundResult`
+  field set + types across future minors
+
+### Changed
+- `agent_runner.runner.run_one_round` integrates hooks at three checkpoints; each
+  call is wrapped in `try/except` and surfaces failures via `hook_failed`
+- `tests/invariants/test_peek_schema_version.py` tightened to require
+  `schema_version >= "1.2"` and the `plugins.context_enrichers` list shape
+
+### Backward compatibility
+- Zero plugins installed → runner behavior identical to 0.1.3
+- `RoundResult` field set is a superset; every prior field is preserved
+- Existing 0.1.x user `agent-runner.toml` files load without modification
+
+## [0.1.3] - 2026-05-12
+
+### Added
+- `agent_runner.events.register_event_kind(name, *, source)` — public API for plugins to register custom event kinds
+- `agent_runner.events.plugin_event_kinds()` — sorted list of currently-registered plugin event kind names
+- `agent_runner` package now discovers and loads entry_points in group `agent_runner.event_kinds` at first import; plugin failures degrade to a `UserWarning` instead of crashing the supervisor
+- `peek --json` schema bumped to `"1.1"`; new top-level `plugins.event_kinds: list[str]` surfaces what's registered
+- `docs/plugins.md` — plugin authoring stub covering the entry_points convention and the event-kind example
+
+### Changed
+- `agent_runner.events.KNOWN_EVENT_KINDS` is now a read-only union view (built-in + plugin) instead of a `frozenset`; `in` and iteration semantics preserved
+- `tests/invariants/test_event_kind_registry.py` rewritten to validate the built-in/plugin split and the registration conflict rules
+- `tests/invariants/test_peek_schema_version.py` tightened to require `schema_version >= "1.1"` and the `plugins.event_kinds` list shape
+
+### Backward compatibility
+- Every existing `from agent_runner.events import KNOWN_EVENT_KINDS` import continues to work
+- Every existing `events.emit(...)` callsite continues to work with the same kind strings
+- Existing 0.1.x user `agent-runner.toml` files load without modification
+
+## [0.1.2] - 2026-05-12
+
+### Added
+- `cfg.agent.name` — optional provider identifier; defaults to `None` (consumers may fall back to `command[0]`)
+- `cfg.prompt.context_injection_mode` — `prepend` (default) / `file` / `none`; controls how round-context reaches the agent
+- `cfg.monitor.auth_fail_patterns` and `cfg.monitor.auth_fail_hint` — generalize the OAuth-fail detector for any provider
+- `cfg.plugins` — placeholder for 0.1.3+ plugin enable/disable; parsed-but-unused in 0.1.2
+- `peek --json` now emits top-level `schema_version: "1.0"` and `plugins: {}` namespace
+
+### Changed
+- `startup_check` prompt-smoke error text reframed away from provider-specific wording
+- `scaffold.py` generated TOML annotates `[agent]` block as the reference; encourages swapping for other CLIs
+- Public docs (architecture, quickstart, configuration) reframed: the reference agent is one of many supported CLIs
+- `monitor.detect_oauth_fail` now reads patterns + hint from `cfg.monitor` (SSOT migrated from a hardcoded module constant to `MonitorConfig`)
+
+### Backward compatibility
+- All defaults preserve the existing prepend-mode behavior
+- Existing `agent-runner.toml` files continue to load without modification
+- Existing tests pass without modification
+
+## [0.1.1] — 2026-05-12
+
+Post-release polish: PyPI install path is documented as the primary entry,
+the repository was renamed for naming parity with the distribution, and the
+release workflow now auto-creates GitHub Releases.
+
+### Changed
+- README + README.zh now show `pip install cli-agent-runner` as the primary
+  install path; the previous `git clone` flow moved to the Development section.
+- Repository renamed from `wan9yu/agent-runner` to `wan9yu/cli-agent-runner`
+  for parity with the PyPI distribution name. All in-tree URL references
+  updated; GitHub redirects keep old links working.
+
+### Build & CI
+- Release workflow now creates a GitHub Release after PyPI publish, attaches
+  the sdist + wheel as release artifacts, and pulls release notes from the
+  matching CHANGELOG section.
+
+## [0.1.0] — 2026-05-12
+
+Initial public release on PyPI as `cli-agent-runner`.
+
+### Added
+- Three-layer model: Round / Loop / Witness.
+- 13 CLI verbs: `init`, `install`, `uninstall`, `start`, `stop`, `kill`,
+  `cancel`, `restart`, `status`, `round`, `serve`, `peek`, `watch`, `monitor`.
+- 11 named defenses (round timeout, process group isolation, orphan stash
+  with SHA lock, set-diff classification, smoke check, flock concurrency,
+  atomic state writes, event kind registry, and others).
+- 9 monitor detectors (`timeout_rate`, `hung`, `orphan_chain`,
+  `disk_warning`, `disk_critical`, `mem_pressure`, `smoke_fail_rate`,
+  `oauth_fail`, `network_fail`); `oauth_fail` and `disk_critical` auto-stop
+  the service.
+- Local-only and remote (via ssh) monitor modes.
+- Auto-generated docs (`./build.sh docs`) for defenses table, detectors,
+  events, config schema, CLI verbs.
+- Literate quickstart: `docs/quickstart.md` is executed as a pytest test.
+- Python public API (`from agent_runner import api`) mirroring CLI verbs.
+- Phase 3 reservation: `[llm]` config section + `agent_runner.critic`
+  Protocol stubs (no implementation).
+
+### Documentation
+- English README + full Chinese `README.zh.md`.
+- 5 user-facing docs: quickstart, commands, configuration, runbook, architecture.
+
+### Build & CI
+- GitHub Actions matrix: Python 3.11/3.12/3.13 × ubuntu / macos.
+- Codecov-uploaded coverage from one canonical matrix cell.
+- Tag-triggered release publishing to PyPI via Trusted Publishing OIDC,
+  gated by a manual approval on the `pypi` GitHub environment.
+
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/wan9yu/cli-agent-runner/releases/tag/v0.1.1
+[0.1.0]: https://github.com/wan9yu/cli-agent-runner/releases/tag/v0.1.0

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.7}/CONTRIBUTING.md

@@ -9,6 +9,7 @@ git clone https://github.com/wan9yu/cli-agent-runner.git
 cd cli-agent-runner
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
+git config core.hooksPath .githooks    # enables the commit-msg lint hook
 ./build.sh check
 ```
 
@@ -16,6 +17,13 @@ pip install -e ".[dev]"
 + integration tests, the literate quickstart, and the docs CI gate. It's
 what GitHub Actions runs on every push and PR.
 
+`git config core.hooksPath .githooks` activates the in-repo
+[`.githooks/commit-msg`](.githooks/commit-msg) hook which rejects commit
+messages containing `Co-Authored-By:` trailers, robot emojis, or other
+AI-tool attribution patterns. The same check runs in CI (`lint-commits`
+job) and as a pytest invariant (`tests/invariants/test_no_ai_signatures.py`)
+— defense in depth.
+
 ## Workflow
 
 1. Open an issue first for non-trivial changes — saves wasted work on both sides.

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.1
+Version: 0.1.7
 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
@@ -37,14 +37,15 @@ Description-Content-Type: text/markdown
 
 > **[中文](README.zh.md)** · English
 
-[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Python](https://img.shields.io/pypi/pyversions/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Downloads](https://img.shields.io/pypi/dm/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner)
 
 # agent-runner
 
-A restart-on-exit supervisor for autonomous CLI agents. Spawn an agent (Claude
-Code, a custom CLI, anything) round-after-round under defenses that prevent
-the failure modes that bite in production: stuck rounds, orphan commits,
-OAuth burn loops, full disks, runaway memory.
+A restart-on-exit supervisor for autonomous coding CLIs. Tested with Claude
+Code and aider out of the box; any prompt-arg CLI via custom config. Spawn
+the agent round-after-round under defenses that prevent the failure modes
+that bite in production: stuck rounds, orphan commits, OAuth burn loops,
+full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
@@ -130,12 +131,6 @@ agent-runner monitor --json | jq -c   # pipe to downstream consumers
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
 
-## Status
-
-Phase 2 (operator surface) shipped. Phase 3 (LLM-augmented Critic) reserved —
-`[llm]` config block and `agent_runner.critic` Protocol stubs are in place,
-implementation TBD.
-
 ## Development
 
 ```bash

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.7}/README.md

@@ -1,13 +1,14 @@
 > **[中文](README.zh.md)** · English
 
-[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Python](https://img.shields.io/pypi/pyversions/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Downloads](https://img.shields.io/pypi/dm/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner)
 
 # agent-runner
 
-A restart-on-exit supervisor for autonomous CLI agents. Spawn an agent (Claude
-Code, a custom CLI, anything) round-after-round under defenses that prevent
-the failure modes that bite in production: stuck rounds, orphan commits,
-OAuth burn loops, full disks, runaway memory.
+A restart-on-exit supervisor for autonomous coding CLIs. Tested with Claude
+Code and aider out of the box; any prompt-arg CLI via custom config. Spawn
+the agent round-after-round under defenses that prevent the failure modes
+that bite in production: stuck rounds, orphan commits, OAuth burn loops,
+full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
@@ -93,12 +94,6 @@ agent-runner monitor --json | jq -c   # pipe to downstream consumers
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
 
-## Status
-
-Phase 2 (operator surface) shipped. Phase 3 (LLM-augmented Critic) reserved —
-`[llm]` config block and `agent_runner.critic` Protocol stubs are in place,
-implementation TBD.
-
 ## Development
 
 ```bash

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.7}/README.zh.md

@@ -1,6 +1,6 @@
 > 中文 · **[English](README.md)**
 
-[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Python](https://img.shields.io/pypi/pyversions/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![CI](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/cli-agent-runner/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![Downloads](https://img.shields.io/pypi/dm/cli-agent-runner.svg)](https://pypi.org/project/cli-agent-runner/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![codecov](https://codecov.io/gh/wan9yu/cli-agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/cli-agent-runner)
 
 # agent-runner
 
@@ -151,11 +151,6 @@ pip install -e ".[dev]"
 
 只支持 POSIX（Linux / macOS）。Python 3.11+。x86_64 与 aarch64 都跑过。
 
-## 项目状态
-
-Phase 2（运维界面）已发。Phase 3（LLM Critic）留了接口：`[llm]` 配置段 +
-`agent_runner.critic` Protocol stubs，实现待定。
-
 ## License
 
 [Apache License 2.0](LICENSE).

cli_agent_runner-0.1.7/agent_runner/__init__.py

@@ -0,0 +1,54 @@
+"""Agent Runner — restart-on-exit supervisor for autonomous CLI agents."""
+
+from __future__ import annotations
+
+try:
+    from agent_runner._version import __version__
+except ImportError:  # editable install before hatch-vcs has generated _version.py
+    __version__ = "0.0.0+unknown"
+
+_HOOK_GROUPS = (
+    "agent_runner.pre_round_hooks",
+    "agent_runner.context_enrichers",
+    "agent_runner.post_round_hooks",
+)
+
+
+def _load_plugins_from_group(group: str) -> None:
+    """Discover and load entry_points in ``group``, isolating per-plugin failures.
+
+    Called at package import. A broken plugin must not crash the supervisor;
+    each failure surfaces as a ``UserWarning``.
+    """
+    import warnings
+    from importlib.metadata import entry_points
+
+    for ep in entry_points(group=group):
+        try:
+            ep.load()
+        except Exception as e:
+            warnings.warn(
+                f"failed to load {group} plugin {ep.name!r}: {e}",
+                stacklevel=3,
+            )
+
+
+def _load_event_kind_plugins() -> None:
+    """Load plugins that register custom event kinds via ``events.register_event_kind``."""
+    _load_plugins_from_group("agent_runner.event_kinds")
+
+
+def _load_hook_plugins() -> None:
+    """Load plugins that register pre_round / context_enricher / post_round hooks."""
+    for group in _HOOK_GROUPS:
+        _load_plugins_from_group(group)
+
+
+def _load_detector_plugins() -> None:
+    """Load plugins that register custom monitor detectors via ``monitor.register_detector``."""
+    _load_plugins_from_group("agent_runner.detectors")
+
+
+_load_event_kind_plugins()
+_load_hook_plugins()
+_load_detector_plugins()

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.7}/agent_runner/_docgen.py

@@ -16,6 +16,7 @@ from pathlib import Path
 from agent_runner.config import (
     AgentConfig,
     Config,
+    MonitorConfig,
     PromptConfig,
     RuntimeConfig,
     VcsConfig,
@@ -29,6 +30,7 @@ _SECTIONS = [
     ("runtime", RuntimeConfig),
     ("prompt", PromptConfig),
     ("vcs", VcsConfig),
+    ("monitor", MonitorConfig),
 ]
 
 

cli_agent_runner-0.1.7/agent_runner/_registry.py

@@ -0,0 +1,23 @@
+"""Shared registry helpers for plugin-extension surfaces.
+
+The `name`-keyed unique-registration check is identical across hooks
+(:mod:`agent_runner.hooks`) and detectors (:mod:`agent_runner.monitor`).
+This module is its single source of truth.
+
+Event-kind registration in :mod:`agent_runner.events` has DIFFERENT
+semantics (idempotent for same-source re-registration, conflict on
+different-source) and stays in that module.
+"""
+
+from __future__ import annotations
+
+
+def ensure_unique(name: str, existing: list, kind: str) -> None:
+    """Raise ValueError if any item in ``existing`` already has ``.name == name``.
+
+    ``kind`` is a short label embedded in the error message (e.g. ``"detector"``,
+    ``"context_enricher"``).
+    """
+    for item in existing:
+        if getattr(item, "name", None) == name:
+            raise ValueError(f"{kind} {name!r} already registered; refusing to add a second")

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