cli-agent-runner 0.3.8__tar.gz → 0.3.10__tar.gz

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/.vulture-whitelist.py

@@ -15,15 +15,9 @@ buffer
 
 # agent_runner._plugin_manifest.PluginManifest
 name
-pre_round_hooks
-context_enrichers
 post_round_hooks
-serve_startup_hooks
-dirty_handlers
-spawn_hooks
-detectors
-event_kinds
-sigterm_cooperative
+cooperative_stop
+resume_flag
 
 # agent_runner._round_outcome.RoundOutcome
 mem_terminated
@@ -36,12 +30,6 @@ usage_capable_by_agent
 newest_usage_ts_by_agent
 backoff_exponent_by_agent
 
-# agent_runner._sandbox_probe.SandboxProbe
-achieved_tier
-landlock_abi
-seccomp
-unconfined_reason
-
 # agent_runner.agent_runtime.RunResult
 exit_code
 duration_s
@@ -131,11 +119,6 @@ unit_file
 rate_limit
 system_managed
 
-# agent_runner.api_types.SpawnDecision
-action
-defer_s
-reason
-
 # agent_runner.api_types.SystemMetrics
 mem_total_mb
 mem_available_mb
@@ -156,7 +139,6 @@ phase
 checks
 overlaps
 plan
-sandbox
 cgroup
 sigterm_grace
 
@@ -199,7 +181,6 @@ brake
 
 # agent_runner.config.models.PhaseOverride
 round_budget_s
-disable_pre_round_hooks
 prompt_files
 agent
 schedule
@@ -211,10 +192,6 @@ phase_policy
 
 # agent_runner.config.models.PluginsConfig
 disable
-spawn_override_allow
-sandbox
-pin
-raw
 
 # agent_runner.config.models.Profile
 agent
@@ -235,7 +212,6 @@ work_dir
 log_dir
 round_budget_s
 restart_delay_s
-disable_pre_round_hooks
 round_log_retention
 narrative_file
 transient_error_action
@@ -316,10 +292,6 @@ anomaly_repetitive_window
 anomaly_repetitive_threshold
 vcs
 
-# agent_runner.hooks.SpawnView
-argv
-env
-
 # agent_runner.hooks.VcsHookView
 dirty_action
 stash_idempotency_s

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/CHANGELOG.md

@@ -5,6 +5,26 @@ 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).
 
+## [0.3.10] - 2026-09-17
+
+### Added
+- Cross-round resume for `pi`: `PluginManifest.resume_flag` (pi = `--session-id`) lets a preset declare an idempotent session flag; `serve` mints one session id per phase and publishes it via `AGENT_RUNNER_RESUME_FLAG`/`AGENT_RUNNER_RESUME_SESSION_ID`, and the round child appends `[flag, id]` to its command. claude/gemini/codewhale/kimi are untouched (`resume_flag` stays `None`) — later release.
+- A new `session_resumed` event records when a round reuses a prior session id.
+- Boot guard: a preset whose static command already contains its `resume_flag` token now fails config load (agent-runner injects it per round; remove the static copy).
+
+No config migration — `resume_flag` is a manifest field, not a TOML key. `peek --json` schema stays `2.6`.
+
+## [0.3.9] - 2026-09-17
+
+### Changed
+- `PluginManifest` narrows to 3 fields (`name`, `post_round_hooks`, `cooperative_stop`) — dropped 6 zero-producer hook seams, the `DirtyHandler` seam (dirty-tree resolution is now plain core), the sandbox subsystem, and the owned-paths registry, all with zero real producers.
+- `sigterm_cooperative: bool` is now typed `cooperative_stop: Literal["SIGTERM", "SIGINT"] | None`: `claude` now drains on SIGINT (SIGTERM abandoned its turn), `gemini`/`pi` stay on SIGTERM; the hard-wall kill path stays SIGTERM-first regardless.
+- The `claude` builtin plugin's manifest/entry-point name changed from `claude_rate_limit` to `claude` (`agent-runner migrate` flags any `[plugins] disable` entry still naming the old value).
+- `peek --json` schema bumps to `2.6`.
+
+### Removed
+- `[plugins]` `sandbox`/`pin`/`spawn_override_allow`/`raw` config keys and `[runtime]`/`[phases.<name>]` `disable_pre_round_hooks` — run `agent-runner migrate` before upgrading.
+
 ## [0.3.8] - 2026-09-16
 
 ### Changed

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.8
+Version: 0.3.10
 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
@@ -34,9 +34,6 @@ Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Requires-Dist: vulture>=2.13; extra == 'dev'
 Provides-Extra: e2e
 Requires-Dist: pytest>=8; extra == 'e2e'
-Provides-Extra: sandbox
-Requires-Dist: py-landlock==0.1.1; (sys_platform == 'linux') and extra == 'sandbox'
-Requires-Dist: pyseccomp==0.1.2; (sys_platform == 'linux') and extra == 'sandbox'
 Description-Content-Type: text/markdown
 
 > **[中文](README.zh.md)** · English

cli_agent_runner-0.3.10/agent_runner/__init__.py

@@ -0,0 +1,121 @@
+"""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"
+
+_PLUGIN_GROUP = "agent_runner.plugins"
+
+# Tracks the names passed to the most recent ``apply_plugin_disable`` call.
+# Surfaced via peek --json `plugins.disabled` for operator visibility.
+_DISABLED_PLUGIN_NAMES: list[str] = []
+
+
+_DISCOVERED_PLUGIN_ENTRIES: list[tuple[str, str]] = []  # (name, "module:attr"), populated once
+
+
+def _discover_plugin_manifests() -> None:
+    """Package-import-time step. Scans entry_points.txt ONLY (scan_entry_points) —
+    imports nothing, executes no plugin code.
+
+    Discovery goes through the ``entry_points.txt`` scanner (cheaper than a
+    fresh ``importlib.metadata.entry_points()`` scan per process; see
+    ``_plugin_scan``), with a hard fallback to ``importlib.metadata`` on any
+    parse failure.
+    """
+    import sys
+
+    from agent_runner._plugin_scan import scan_entry_points
+
+    global _DISCOVERED_PLUGIN_ENTRIES
+    _DISCOVERED_PLUGIN_ENTRIES = scan_entry_points(sys.path, _PLUGIN_GROUP)
+
+
+_discover_plugin_manifests()
+
+
+def load_and_register_plugins(plugins_cfg, log_dir=None) -> None:
+    """Called from config.loader.load_config once [plugins] is parsed. For
+    each discovered (name, value) NOT in plugins_cfg.disable and not already
+    registered, resolve module_path/attr_path, import + register_manifest. A
+    disabled name is never imported. A per-plugin failure isolates as a
+    UserWarning and skips that ONE plugin; it never aborts the whole load.
+
+    ``name`` here is always the entry-point name (the ``agent_runner.plugins``
+    pyproject.toml key) — it's the identifier known BEFORE import. It is NOT
+    necessarily ``PluginManifest.name`` (only known after import); for every
+    builtin the two are pinned equal by
+    ``test_entry_point_names_should_match_manifest_name``, but that is not
+    enforced here.
+
+    ``log_dir`` is accepted for call-site stability (config.loader threads it
+    through unconditionally) though this function no longer emits anything
+    itself.
+    """
+    import warnings
+
+    from agent_runner._plugin_manifest import loaded_manifest_names, register_manifest
+    from agent_runner._registry import resolve_entry_target
+
+    disable = set(plugins_cfg.disable)
+    already = set(loaded_manifest_names())
+    for name, value in _DISCOVERED_PLUGIN_ENTRIES:
+        if name in disable or name in already:
+            continue
+        # An entry-point value may carry a trailing extras marker
+        # (``module:attr [extra1,extra2]``); importlib.metadata.EntryPoint's
+        # own module/attr grammar excludes "[", so anything from the first
+        # "[" onward is always extras, never part of the path — strip it
+        # before resolving, or it glues onto attr_path and breaks getattr().
+        stripped = value.partition("[")[0].rstrip()
+        module_path, _, attr_path = stripped.partition(":")
+        try:
+            target = resolve_entry_target(module_path, attr_path)
+            register_manifest(target)
+        except Exception as e:  # noqa: BLE001 — a broken plugin must never crash the supervisor
+            warnings.warn(f"failed to load {_PLUGIN_GROUP} plugin {name!r}: {e}", stacklevel=3)
+
+
+def apply_plugin_disable(names: list[str]) -> None:
+    """Remove plugins matching ``names`` (manifest names) from all in-memory
+    registries.
+
+    Called after config-load to honor ``[plugins] disable``. Idempotent for
+    already-removed names. Emits a UserWarning for names that match no
+    loaded manifest (typo catcher; tolerates cross-env config drift).
+
+    A disabled name is never imported by ``load_and_register_plugins`` in the
+    first place, so this is belt-and-suspenders cleanup for anything that
+    reached the registries another way (e.g. a manifest registered directly
+    via ``register_manifest``, not through entry-point discovery).
+    """
+    import warnings
+
+    from agent_runner._plugin_manifest import unregister_by_name
+
+    if not names:
+        return
+
+    global _DISABLED_PLUGIN_NAMES
+    _DISABLED_PLUGIN_NAMES = list(names)
+
+    found = unregister_by_name(set(names))
+    unknown = set(names) - found
+    if unknown:
+        warnings.warn(
+            f"[plugins] disable references unknown plugin name(s): {sorted(unknown)}. "
+            f"(Names matched no loaded PluginManifest; check spelling or installed packages.)",
+            stacklevel=2,
+        )
+
+
+def disabled_plugin_names() -> list[str]:
+    """Names passed to the most recent ``apply_plugin_disable`` call.
+
+    Used by peek --json to surface ``plugins.disabled`` for operator visibility.
+    Returns the LIST (not set) preserving configured order.
+    """
+    return list(_DISABLED_PLUGIN_NAMES)

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_docgen.py

@@ -48,9 +48,8 @@ from agent_runner.monitor import AUTO_STOP_ALERTS, KNOWN_ALERT_KINDS
 # (toml_section_name, dataclass, nested_sub_sections). Nesting is an EXPLICIT
 # registry, not reflection, on two counts:
 #   - field name != TOML key: PhaseOverride.prompt_files is written as
-#     [phases.<name>.prompt] files=[...], and PluginsConfig.raw is a catch-all
-#     for unknown keys. Recursing generically would document TOML keys that do
-#     not exist.
+#     [phases.<name>.prompt] files=[...]. Recursing generically would document
+#     TOML keys that do not exist.
 #   - typing.get_type_hints() raises TypeError on PhasesConfig — its `list`
 #     field shadows the builtin, so `list[str] | None` resolves against
 #     None. Do not reach for it here.

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_emit/__init__.py

@@ -42,14 +42,6 @@ from agent_runner._emit.memory import (  # noqa: F401 — public re-export
     emit_round_oom_killed,
     emit_round_resumed,
 )
-from agent_runner._emit.plugins import (  # noqa: F401 — public re-export
-    emit_plugin_builtin_name_squat,
-    emit_plugin_checksum_mismatch,
-    emit_plugin_sandbox_degraded,
-    emit_plugin_sandbox_kill,
-    emit_plugin_spawn_decision,
-    emit_plugin_spawn_override_ignored,
-)
 from agent_runner._emit.rounds import (  # noqa: F401 — public re-export
     emit_fresh_eyes_round_triggered,
     emit_round_container_orphan_risk,
@@ -73,6 +65,7 @@ from agent_runner._emit.serve import (  # noqa: F401 — public re-export
     emit_schedule_paused,
     emit_schedule_phase_skipped,
     emit_schedule_resumed,
+    emit_session_resumed,
     emit_stalled_no_progress,
     emit_stop_file_detected,
 )
@@ -94,12 +87,6 @@ __all__ = [
     "emit_memory_high_engaged",
     "emit_memory_high_released",
     "emit_memory_high_write_failed",
-    "emit_plugin_builtin_name_squat",
-    "emit_plugin_checksum_mismatch",
-    "emit_plugin_sandbox_degraded",
-    "emit_plugin_sandbox_kill",
-    "emit_plugin_spawn_decision",
-    "emit_plugin_spawn_override_ignored",
     "emit_rate_limit_stop",
     "emit_round_cgroup_memory",
     "emit_round_container_orphan_risk",
@@ -118,6 +105,7 @@ __all__ = [
     "emit_schedule_paused",
     "emit_schedule_phase_skipped",
     "emit_schedule_resumed",
+    "emit_session_resumed",
     "emit_stale_index_lock_cleared",
     "emit_stalled_no_progress",
     "emit_stop_file_detected",

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_emit/serve.py

@@ -191,3 +191,15 @@ def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
     from agent_runner.events import SCHEDULE_RESUMED, emit
 
     emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
+
+
+def emit_session_resumed(log_dir: Path, *, session_id: str, phase: str = "") -> None:
+    """Emit session_resumed when serve resumes an existing agent session on a
+    non-first round of an epoch (the runtime property peek cannot show). ``phase``
+    is omitted when empty so the base (no-override) phase stays a clean payload."""
+    from agent_runner.events import SESSION_RESUMED, emit
+
+    fields = {"session_id": session_id}
+    if phase:
+        fields["phase"] = phase
+    emit(log_dir, SESSION_RESUMED, **fields)

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_monitor_registry.py

@@ -1,4 +1,4 @@
-"""Alert-kind catalog + the plugin detector registry.
+"""Alert-kind catalog.
 
 Pure bookkeeping: no filesystem I/O, no clock reads. Detector *logic* lives in
 ``_monitor_detectors``; state assembly in ``_monitor_state``; the cycle-edge
@@ -7,8 +7,7 @@ wiring (``run_all_detectors``/``on_alert``) in ``monitor.py``.
 
 from __future__ import annotations
 
-from agent_runner._registry import ensure_unique
-from agent_runner.api_types import Alert, Detector
+from agent_runner.api_types import Alert
 from agent_runner.config import _DEFAULT_AUTO_STOP_ON
 from agent_runner.events import (
     DETECTOR_ERROR,
@@ -82,17 +81,3 @@ def alert_identity(alert: Alert) -> str:
         return alert.detector
     parts = "|".join(f"{k}={alert.context.get(k)!r}" for k in fields)
     return f"{alert.detector}:{parts}"
-
-
-_PLUGIN_DETECTORS: list[Detector] = []
-
-
-def register_detector(detector: Detector) -> None:
-    """Register a plugin detector. Rejects duplicate names."""
-    ensure_unique(detector.name, _PLUGIN_DETECTORS, "detector")
-    _PLUGIN_DETECTORS.append(detector)
-
-
-def plugin_detectors() -> list[str]:
-    """Sorted list of registered plugin detector names (for peek --json)."""
-    return sorted(d.name for d in _PLUGIN_DETECTORS)

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_notify.py

@@ -78,14 +78,9 @@ def drain(fd: int) -> None:
     ``select()`` on it instantly ready -- an undrained fd busy-spins its
     caller at 100% CPU forever after the first wake, since a level-triggered
     fd stays readable until read. Advisory: the bytes carry no payload and are
-    discarded. Two callers: :meth:`Listener.wait` self-drains its own fd on the
-    wake branch (the pause/sleep waits ``_interruptible_sleep``/``_pause_poll``
-    are the consumers of a live ``Listener``); and the sandboxed-hook trampoline
-    (``_plugin_sandbox._run_child_process``, P3) drains the CALLER-OWNED wake fd
-    it was handed on the ``"woken"`` branch of its exit wait, before re-checking
-    ``should_stop()`` -- that fd is the serve listener's, watched by
-    ``wait_exit`` for the duration of the hook, so the trampoline must drain it
-    itself rather than leave the next wait instantly ready.
+    discarded. :meth:`Listener.wait` self-drains its own fd on the wake branch
+    (the pause/sleep waits ``_interruptible_sleep``/``_pause_poll`` are the
+    consumers of a live ``Listener``).
     """
     while True:
         try:

{cli_agent_runner-0.3.8 → cli_agent_runner-0.3.10}/agent_runner/_observe.py

@@ -155,7 +155,7 @@ def _poll_once(
         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())
-    builtin = monitor.run_all_detectors(
+    return monitor.run_all_detectors(
         events=events,
         metrics=metrics,
         log_tails=log_tails,
@@ -167,11 +167,6 @@ def _poll_once(
         host_health_cfg=cfg.monitor.host_health,
         log_dir=cfg.runtime.log_dir,
     )
-    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(

cli_agent_runner-0.3.10/agent_runner/_plugin_manifest.py

@@ -0,0 +1,207 @@
+"""The plugin ABI: one typed, declared capability manifest per plugin, read
+by the loader (agent_runner/__init__.py::load_and_register_plugins) instead
+of relying on import-time register_*() side effects. One entry-point group,
+`agent_runner.plugins`, each entry resolving to a module-level
+`PLUGIN = PluginManifest(...)`.
+"""
+
+from __future__ import annotations
+
+import signal
+from dataclasses import dataclass
+from typing import Literal
+
+from agent_runner._registry import ensure_unique
+from agent_runner.hooks import PostRoundHook
+
+# THE single, pinned string->signal.Signals table for cooperative_stop. Nothing
+# else in the codebase may turn a cooperative-stop string into a signal (no
+# `getattr(signal, arbitrary_string)`, which could reach SIGKILL=zero-grace or
+# SIGSTOP=freeze). Keys ARE the full set of legal cooperative_stop values, so
+# __post_init__ validates against these same keys.
+_COOPERATIVE_SIGNALS: dict[str, signal.Signals] = {
+    "SIGTERM": signal.SIGTERM,
+    "SIGINT": signal.SIGINT,
+}
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """A plugin's complete, declared capability set. `name` is the plugin's
+    own identity — `[plugins] disable` keys on THIS, not on any individual
+    hook's own `.name`."""
+
+    name: str
+    post_round_hooks: tuple[PostRoundHook, ...] = ()
+    cooperative_stop: Literal["SIGTERM", "SIGINT"] | None = None
+    """How this preset's CLI cooperatively drains/cleans up when the supervisor
+    stops the round: the signal it drains on (``"SIGTERM"`` = gemini/pi,
+    ``"SIGINT"`` = claude/codex), or ``None`` = no cooperative drain (the hard
+    path). Source-verified per preset, NEVER assumed from a CLI's general
+    reputation. Resolved to a ``signal.Signals`` ONLY by
+    ``resolve_cooperative_signal``; a ``None`` cooperative_stop maps to
+    SIGTERM-first at the reap site (today's behavior), never "skip the first
+    signal"."""
+
+    resume_flag: str | None = None
+    """The flag that carries a supervisor-chosen session id on EVERY round for a
+    CLI whose session flag is IDEMPOTENT (create-or-resume). pi = "--session-id".
+    ``None`` = no resume (today's cold start). Resolved ONLY by
+    ``resolve_resume_flag``; ``__post_init__`` rejects an empty string. Source-
+    verified per preset (pi's --session-id is idempotent), NEVER assumed."""
+
+    def __post_init__(self) -> None:
+        # Errors-unlikely-by-construction: an unknown signal name (or a
+        # freeze/zero-grace one like SIGSTOP/SIGKILL) is unrepresentable -- it
+        # raises at construction, not at kill time.
+        if self.cooperative_stop is not None and self.cooperative_stop not in _COOPERATIVE_SIGNALS:
+            raise ValueError(
+                "cooperative_stop must be one of {None, 'SIGTERM', 'SIGINT'}, "
+                f"got {self.cooperative_stop!r}"
+            )
+        if self.resume_flag is not None and not self.resume_flag:
+            raise ValueError(
+                f"resume_flag must be None or a non-empty flag string, got {self.resume_flag!r}"
+            )
+
+
+_LOADED_MANIFESTS: list[PluginManifest] = []
+
+
+def loaded_manifest_names() -> list[str]:
+    """Names of every currently-registered manifest (order-preserving).
+    Mirrors the ``list(_LOADED_MANIFESTS)`` pattern; used by the loader for
+    idempotent re-load skipping."""
+    return [m.name for m in _LOADED_MANIFESTS]
+
+
+def _cooperative_stop_for_name(agent_binary: str | None) -> str | None:
+    """The ``cooperative_stop`` field of the registered manifest named
+    `agent_binary`, or None when no such manifest is registered (or it declares
+    no cooperative stop). The single registry lookup the resolvers below share."""
+    for m in _LOADED_MANIFESTS:
+        if m.name == agent_binary:
+            return m.cooperative_stop
+    return None
+
+
+def cooperative_stop_by_name() -> dict[str, str]:
+    """`{manifest name: cooperative_stop signal name}` for every registered
+    manifest declaring a cooperative_stop (order-preserving). Mirrors
+    loaded_manifest_names; used by peek/doctor -- an operator sees not just
+    WHICH presets cooperate but the SIGNAL each drains on."""
+    return {m.name: m.cooperative_stop for m in _LOADED_MANIFESTS if m.cooperative_stop is not None}
+
+
+def is_cooperative_agent(agent_binary: str | None) -> bool:
+    """Whether the agent's preset declares a cooperative_stop. Routes through
+    the same single-scan `resolve_cooperative_signal` uses: `cooperative_stop`
+    is always in {None, "SIGTERM", "SIGINT"} (`__post_init__`-guaranteed) and
+    `_COOPERATIVE_SIGNALS` keys are exactly {"SIGTERM", "SIGINT"}, so a
+    resolved signal exists iff the named manifest declares a cooperative_stop."""
+    return resolve_cooperative_signal(agent_binary) is not None
+
+
+def resolve_cooperative_signal(agent_binary: str | None) -> signal.Signals | None:
+    """The signal the agent named `agent_binary` cooperatively drains on, or
+    None when its preset declares no cooperative_stop. THE ONLY place a
+    cooperative_stop string becomes a ``signal.Signals`` (via the pinned
+    ``_COOPERATIVE_SIGNALS`` table) -- sibling to resolve_sigterm_grace_s, and
+    the SIGNAL half of the same anti-skew single-source: serve resolves it once
+    per phase from its own registry and publishes the result via env, so the
+    round child never re-derives (and skews) it."""
+    return _COOPERATIVE_SIGNALS.get(_cooperative_stop_for_name(agent_binary))
+
+
+def resolve_resume_flag(agent_binary: str | None) -> str | None:
+    """The resume flag the agent named `agent_binary` declares, or None when no
+    such manifest is registered (or it declares no resume). THE registry lookup
+    for resume -- sibling to resolve_cooperative_signal, the SAME
+    ``m.name == agent_binary`` join (so it stays correct whenever a preset's
+    manifest name is kept equal to its agent binary). serve resolves it once
+    per phase and publishes the id via env so the round child never
+    re-derives. No signal table: the flag string IS what serve publishes and
+    the child appends, so the scan IS the resolve."""
+    for m in _LOADED_MANIFESTS:
+        if m.name == agent_binary:
+            return m.resume_flag
+    return None
+
+
+def cooperative_signal_from_name(name: str | None) -> signal.Signals | None:
+    """Map a published cooperative-stop signal NAME (e.g. from
+    AGENT_RUNNER_COOPERATIVE_STOP_SIGNAL) back to a ``signal.Signals`` through
+    the SAME pinned ``_COOPERATIVE_SIGNALS`` table. An unknown/absent name -> None
+    (the reap site then defaults to SIGTERM-first, today's behavior). Never
+    getattr(signal, ...): a leaked/hostile "SIGKILL"/"SIGSTOP" is simply not a
+    table key and falls back safely."""
+    return _COOPERATIVE_SIGNALS.get(name) if name is not None else None
+
+
+def resolve_sigterm_grace_s(agent_binary: str | None, sigterm_grace_s: int) -> int:
+    """The SIGTERM->SIGKILL grace this round's agent actually gets:
+    `sigterm_grace_s` (config's [agent] sigterm_grace_s, boot-capped at
+    _ROUND_TERM_GRACE_S) when `agent_binary` names a manifest declaring a
+    cooperative_stop, else agent_runtime.REAP_GRACE_S (5s) unchanged. One
+    function, two callers: cli.serve_cmd._apply_reap_grace_env (what the agent
+    actually gets) and doctor/peek (what an operator sees)."""
+    from agent_runner.agent_runtime import REAP_GRACE_S
+
+    if is_cooperative_agent(agent_binary):
+        return sigterm_grace_s
+    return REAP_GRACE_S
+
+
+def register_manifest(manifest: PluginManifest) -> None:
+    """Register every capability a manifest declares into its own registry.
+    No import-time side effects — the loader calls this explicitly after
+    resolving a plugin's `PLUGIN` attribute.
+
+    Raises ``ValueError`` up front if ``manifest.name`` collides with an
+    already-registered manifest's ``.name`` — this is checked HERE, not by
+    the underlying registries' own ``ensure_unique`` calls below, which only
+    catch two manifests sharing one of THEIR sub-capabilities' ``.name``
+    (e.g. two different plugins each declaring a post_round_hook named
+    ``"foo"``); they have no visibility into the manifest's own top-level name, so two
+    manifests named e.g. ``"codewhale"`` with disjoint capability names would
+    otherwise both register, and ``unregister_by_name``/``[plugins] disable``
+    would then strip both when the operator meant to disable one.
+
+    Appends to ``_LOADED_MANIFESTS`` only after every sub-registration
+    succeeds — a duplicate CAPABILITY-name registration (e.g. a stray
+    double-scan) raises via the underlying registries' own ``ensure_unique``
+    checks before the manifest is recorded, so a failed call leaves no
+    partial trace for ``unregister_by_name`` to later find and no-op
+    against. This guarantee covers ``_LOADED_MANIFESTS`` only: a failure
+    partway through the loop below (e.g. the 3rd of 5 declared
+    post_round_hooks raises) still leaves the first 2 registered in their
+    own per-family registry — matching the prior import-time register_*()
+    semantics, where a mid-module exception left every earlier top-level
+    call's side effect in place too.
+    """
+    ensure_unique(manifest.name, _LOADED_MANIFESTS, "plugin manifest")
+
+    from agent_runner import hooks
+
+    for h in manifest.post_round_hooks:
+        hooks.register_post_round_hook(h)
+    _LOADED_MANIFESTS.append(manifest)
+
+
+def _remove_by_identity(registry: list, items: tuple) -> None:
+    registry[:] = [x for x in registry if x not in items]
+
+
+def unregister_by_name(names: set[str]) -> set[str]:
+    """Remove every capability declared by manifests whose `.name` is in
+    `names`. Returns the subset of `names` actually matched (for the
+    caller's unknown-name warning)."""
+    from agent_runner import hooks
+
+    found: set[str] = set()
+    for manifest in list(_LOADED_MANIFESTS):
+        if manifest.name not in names:
+            continue
+        found.add(manifest.name)
+        _remove_by_identity(hooks._POST_ROUND_HOOKS, manifest.post_round_hooks)
+    return found

cli_agent_runner-0.3.10/agent_runner/_registry.py

@@ -0,0 +1,38 @@
+"""Shared registry helpers for plugin-extension surfaces.
+
+The `name`-keyed unique-registration check (:func:`ensure_unique`) is shared
+across every hook family in :mod:`agent_runner.hooks` (post_round_hooks) and
+by :mod:`agent_runner._plugin_manifest`'s own manifest-name check. This
+module is its single source of truth.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def resolve_entry_target(module_path: str, attr_path: str) -> Any:
+    """Import ``module_path`` and walk ``attr_path`` (dot-separated, empty
+    segments ignored) via ``getattr``, returning the final target — the
+    module itself when ``attr_path`` is empty.
+
+    The single resolution recipe for an entry-point's ``module:attr`` value,
+    used by the plugin loader (``agent_runner.load_and_register_plugins``).
+    """
+    import importlib
+
+    target: Any = importlib.import_module(module_path)
+    for attr in filter(None, attr_path.split(".")):
+        target = getattr(target, attr)
+    return target
+
+
+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. ``"post_round_hook"``,
+    ``"plugin manifest"``).
+    """
+    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.3.8 → cli_agent_runner-0.3.10}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.8'
-__version_tuple__ = version_tuple = (0, 3, 8)
+__version__ = version = '0.3.10'
+__version_tuple__ = version_tuple = (0, 3, 10)
 
 __commit_id__ = commit_id = None