cli-agent-runner 0.1.0__tar.gz → 0.1.6__tar.gz

{cli_agent_runner-0.1.0 → cli_agent_runner-0.1.6}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Question or usage help
-    url: https://github.com/wan9yu/agent-runner/discussions
+    url: https://github.com/wan9yu/cli-agent-runner/discussions
     about: For usage questions, please open a discussion.

{cli_agent_runner-0.1.0 → cli_agent_runner-0.1.6}/.github/workflows/release.yml

@@ -56,3 +56,40 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           attestations: true
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: extract CHANGELOG section for this tag
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (found) exit
+              if ($0 ~ "\\[" ver "\\]") { found = 1; next }
+            }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "No CHANGELOG section for v$VERSION — using auto-generated notes." > release-notes.md
+          fi
+          echo "--- release-notes.md preview ---"
+          cat release-notes.md
+      - name: create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          gh release create "v$VERSION" \
+            --title "v$VERSION" \
+            --notes-file release-notes.md \
+            dist/*

cli_agent_runner-0.1.6/CHANGELOG.md

@@ -0,0 +1,235 @@
+# 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.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.0 → cli_agent_runner-0.1.6}/CONTRIBUTING.md

@@ -5,8 +5,8 @@ Thanks for your interest in contributing!
 ## Development setup
 
 ```bash
-git clone https://github.com/wan9yu/agent-runner.git
-cd agent-runner
+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]"
 ./build.sh check

{cli_agent_runner-0.1.0 → cli_agent_runner-0.1.6}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.0
+Version: 0.1.6
 Summary: Restart-on-exit supervisor for autonomous CLI agents
-Project-URL: Homepage, https://github.com/wan9yu/agent-runner
-Project-URL: Documentation, https://github.com/wan9yu/agent-runner#readme
-Project-URL: Repository, https://github.com/wan9yu/agent-runner
-Project-URL: Issues, https://github.com/wan9yu/agent-runner/issues
-Project-URL: Changelog, https://github.com/wan9yu/agent-runner/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
+Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme
+Project-URL: Repository, https://github.com/wan9yu/cli-agent-runner
+Project-URL: Issues, https://github.com/wan9yu/cli-agent-runner/issues
+Project-URL: Changelog, https://github.com/wan9yu/cli-agent-runner/blob/main/CHANGELOG.md
 Author-email: wangyu <wangyu@go2imagination.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 > **[中文](README.zh.md)** · English
 
-[![CI](https://github.com/wan9yu/agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/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/agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/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
 
@@ -56,15 +56,19 @@ OAuth burn loops, full disks, runaway memory.
 └──────────────────────────────────────────┘
 ```
 
-## Quick start
+## Install
 
 ```bash
-git clone https://github.com/wan9yu/agent-runner.git
-cd agent-runner
-python3 -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
+pip install cli-agent-runner
+```
+
+The installed CLI command is `agent-runner` (the PyPI distribution name is
+prefixed for namespace disambiguation; the import name and command are not).
+
+## Quick start
 
-# In your project directory:
+```bash
+cd your-project
 agent-runner init                 # scaffold agent-runner.toml + prompts/main.md
 $EDITOR agent-runner.toml         # point agent.command at your CLI
 agent-runner install --monitor    # systemd user units for serve + monitor
@@ -126,18 +130,17 @@ 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
-pytest -q --ignore=tests/e2e        # 207 unit + integration tests
-AGENT_RUNNER_E2E_PI=1 pytest tests/e2e/   # opt-in pi e2e (needs ssh alias `pi`)
-ruff check . && ruff format --check .
+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]"
+
+./build.sh check                          # full local-CI sweep
+./build.sh test                           # unit + integration only
+AGENT_RUNNER_E2E_PI=1 ./build.sh e2e      # opt-in pi e2e (needs ssh alias `pi`)
 ```
 
 Some `docs/*.md` blocks are generated from code — `./build.sh docs` rewrites

{cli_agent_runner-0.1.0 → cli_agent_runner-0.1.6}/README.md

@@ -1,6 +1,6 @@
 > **[中文](README.zh.md)** · English
 
-[![CI](https://github.com/wan9yu/agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/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/agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/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
 
@@ -19,15 +19,19 @@ OAuth burn loops, full disks, runaway memory.
 └──────────────────────────────────────────┘
 ```
 
-## Quick start
+## Install
 
 ```bash
-git clone https://github.com/wan9yu/agent-runner.git
-cd agent-runner
-python3 -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
+pip install cli-agent-runner
+```
+
+The installed CLI command is `agent-runner` (the PyPI distribution name is
+prefixed for namespace disambiguation; the import name and command are not).
+
+## Quick start
 
-# In your project directory:
+```bash
+cd your-project
 agent-runner init                 # scaffold agent-runner.toml + prompts/main.md
 $EDITOR agent-runner.toml         # point agent.command at your CLI
 agent-runner install --monitor    # systemd user units for serve + monitor
@@ -89,18 +93,17 @@ 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
-pytest -q --ignore=tests/e2e        # 207 unit + integration tests
-AGENT_RUNNER_E2E_PI=1 pytest tests/e2e/   # opt-in pi e2e (needs ssh alias `pi`)
-ruff check . && ruff format --check .
+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]"
+
+./build.sh check                          # full local-CI sweep
+./build.sh test                           # unit + integration only
+AGENT_RUNNER_E2E_PI=1 ./build.sh e2e      # opt-in pi e2e (needs ssh alias `pi`)
 ```
 
 Some `docs/*.md` blocks are generated from code — `./build.sh docs` rewrites

{cli_agent_runner-0.1.0 → cli_agent_runner-0.1.6}/README.zh.md

@@ -1,6 +1,6 @@
 > 中文 · **[English](README.md)**
 
-[![CI](https://github.com/wan9yu/agent-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/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/agent-runner/branch/main/graph/badge.svg)](https://codecov.io/gh/wan9yu/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
 
@@ -34,15 +34,19 @@ supervisor 重启 —— 这是核心模式。中间穿插 11 条防御，避开
 - `serve` 包住 round 形成长服务
 - `monitor` 可以从本机也可以远程通过 ssh 观测一台 pi 上的 supervisor
 
-## 上手
+## 安装
 
 ```bash
-git clone https://github.com/wan9yu/agent-runner.git
-cd agent-runner
-python3 -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
+pip install cli-agent-runner
+```
+
+CLI 命令仍是 `agent-runner`（PyPI 包名加 `cli-` 前缀只是为了规避命名冲突，
+导入名 `agent_runner` 和命令名都不变）。
+
+## 上手
 
-# 在你的项目目录里：
+```bash
+cd your-project
 agent-runner init                 # 生成 agent-runner.toml + prompts/main.md
 $EDITOR agent-runner.toml         # 把 agent.command 指向你的 CLI
 agent-runner install --monitor    # 装 systemd user unit（serve + monitor）
@@ -134,6 +138,11 @@ agent-runner monitor --json | jq -c   # 输出 JSON 给下游 consumer
 ## 开发
 
 ```bash
+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]"
+
 ./build.sh check    # lint + 单元 + 集成 + literate + docs 一致性，本地 CI 全套
 ./build.sh test     # 仅 230+ 单元 + 集成测试
 ./build.sh literate # 仅跑 quickstart.md 的可执行块
@@ -142,11 +151,6 @@ agent-runner monitor --json | jq -c   # 输出 JSON 给下游 consumer
 
 只支持 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.0 → cli_agent_runner-0.1.6}/SECURITY.md

@@ -7,7 +7,7 @@ The latest tagged release. We do not back-port security fixes to older versions.
 ## Reporting a vulnerability
 
 Please report security issues privately via GitHub Security Advisories:
-<https://github.com/wan9yu/agent-runner/security/advisories/new>
+<https://github.com/wan9yu/cli-agent-runner/security/advisories/new>
 
 If GitHub Security Advisories is not workable for you, email
 `wangyu@go2imagination.com` with the subject line `agent-runner security`.

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