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

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.1 → cli_agent_runner-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.1
+Version: 0.1.6
 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,7 +37,7 @@ 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
 
@@ -130,12 +130,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.6}/README.md

@@ -1,6 +1,6 @@
 > **[中文](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
 
@@ -93,12 +93,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.6}/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.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.1 → 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.1 → 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.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.1.6'
+__version_tuple__ = version_tuple = (0, 1, 6)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.6}/agent_runner/api.py

@@ -2,8 +2,8 @@
 
 Every CLI subcommand has a corresponding api function. CLI files do
 ``api.X(...)`` and format the returned dataclass for display. External
-agents (Phase 3 outer Claude Code) can `from agent_runner import api`
-and skip CLI text parsing entirely.
+callers can ``from agent_runner import api`` and skip CLI text parsing
+entirely.
 """
 
 from __future__ import annotations
@@ -83,7 +83,7 @@ def install(
     if work_dir is None:
         work_dir = Path.cwd()
     if system:
-        raise NotImplementedError("--system install not yet implemented in Phase 2")
+        raise NotImplementedError("--system install not yet implemented")
     cfg_path = work_dir / "agent-runner.toml"
     cfg = load_config(cfg_path)
     project = _project_name(work_dir)
@@ -295,12 +295,19 @@ def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
     events = monitor.parse_events_from_jsonl_files(src.events_files())
     metrics = monitor.parse_events_from_jsonl_files(src.metrics_files())
     log_tails = monitor.load_round_log_tails(src.rounds_dir())
-    return monitor.run_all_detectors(
+    builtin = monitor.run_all_detectors(
         events=events,
         metrics=metrics,
         log_tails=log_tails,
         round_timeout_s=cfg.runtime.round_timeout_s,
+        auth_fail_patterns=cfg.monitor.auth_fail_patterns,
+        auth_fail_hint=cfg.monitor.auth_fail_hint,
     )
+    if not monitor._PLUGIN_DETECTORS:
+        return builtin  # skip ProjectState assembly when no plugins to feed
+    state = monitor.assemble_project_state(src, project=_project_name(work_dir))
+    plugin = monitor.run_plugin_detectors(state)
+    return builtin + plugin
 
 
 def monitor_loop(
@@ -327,5 +334,6 @@ def monitor_loop(
                 project=_project_name(work_dir),
                 host=host,
                 log_dir=cfg.runtime.log_dir,
+                allowed_stop_names=cfg.monitor.auto_stop_on,
             )
         time.sleep(interval_s)

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.6}/agent_runner/api_types.py

@@ -1,7 +1,7 @@
 """Dataclasses for the Python API state tree.
 
 These are the public types that ``agent_runner.api`` returns and that
-``cli/`` formats. Phase 3 LLM/Critic will read these structures.
+``cli/`` formats. Plugins (hooks, context enrichers, detectors) consume them.
 
 All frozen — state is immutable, no in-place mutation.
 """
@@ -11,7 +11,15 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import StrEnum
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, Protocol, runtime_checkable
+
+Severity = Literal["info", "warning", "critical"]
+"""Alert / Detector severity level. ``critical`` is the only level that may
+trigger ``auto_action="stop_service"``."""
+
+AutoAction = Literal["none", "stop_service"]
+"""What the monitor does when this Alert fires. ``stop_service`` only takes
+effect if the detector's ``name`` is in ``cfg.monitor.auto_stop_on``."""
 
 
 class ServiceMode(StrEnum):
@@ -68,12 +76,53 @@ class ProjectState:
 
 @dataclass(frozen=True)
 class Alert:
-    severity: str
+    severity: Severity
     detector: str
     message: str
     context: dict[str, Any]
     ts: str
-    auto_action: str = "none"
+    auto_action: AutoAction = "none"
+
+
+@runtime_checkable
+class Detector(Protocol):
+    """Public plugin contract for monitor detectors.
+
+    Plugins implementing this Protocol can be registered via
+    ``monitor.register_detector`` (or auto-loaded via entry_points group
+    ``agent_runner.detectors``) and will be invoked alongside built-in
+    detectors during each monitor poll.
+
+    ``auto_action="stop_service"`` is honored only if the plugin's ``name``
+    appears in ``cfg.monitor.auto_stop_on`` — operators must explicitly
+    opt plugins into the auto-stop policy.
+    """
+
+    name: str
+    severity: Severity
+    auto_action: AutoAction
+
+    def detect(self, state: ProjectState) -> Alert | None: ...
+
+
+@dataclass(frozen=True)
+class RoundResult:
+    """Result of one ``run_one_round`` call.
+
+    Stable across 0.1.x for PostRoundHook consumers. Fields may be ADDED in
+    a minor; removed or retyped only on a major bump.
+    """
+
+    round_num: int
+    phase: str | None
+    started_at: str
+    ended_at: str
+    exit_code: int
+    duration_s: float
+    timed_out: bool
+    log_path: Path
+    dirty_files: list[str]
+    stashed: bool
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.6}/agent_runner/cli/common.py

@@ -9,7 +9,13 @@ from enum import Enum
 from pathlib import Path
 from typing import Any
 
+from agent_runner.api_types import ProjectState
 from agent_runner.config import Config, load_config
+from agent_runner.events import plugin_event_kinds
+from agent_runner.hooks import plugin_context_enrichers
+from agent_runner.monitor import plugin_detectors
+
+PEEK_SCHEMA_VERSION = "1.3"
 
 
 def cfg_from_args(args) -> Config:
@@ -36,7 +42,19 @@ def work_dir_from_args(args) -> Path:
 
 def emit(value: Any, *, json_mode: bool) -> None:
     if json_mode:
-        print(json.dumps(_to_jsonable(value), indent=2, default=str))
+        if isinstance(value, ProjectState):
+            wrapped = {
+                "schema_version": PEEK_SCHEMA_VERSION,
+                "plugins": {
+                    "event_kinds": plugin_event_kinds(),
+                    "context_enrichers": plugin_context_enrichers(),
+                    "detectors": plugin_detectors(),
+                },
+                **_to_jsonable(value),
+            }
+            print(json.dumps(wrapped, indent=2, default=str))
+        else:
+            print(json.dumps(_to_jsonable(value), indent=2, default=str))
     else:
         print(_pretty(value))
 

{cli_agent_runner-0.1.1 → cli_agent_runner-0.1.6}/agent_runner/cli/install_cmd.py

@@ -13,7 +13,7 @@ def add_parser(sub, parent) -> None:
     p.add_argument(
         "--system",
         action="store_true",
-        help="Install at system level (not yet supported in Phase 2)",
+        help="Install at system level (not yet supported)",
     )
     p.add_argument(
         "--monitor",