cli-agent-runner 0.3.1__tar.gz → 0.3.2__tar.gz

{cli_agent_runner-0.3.1 → cli_agent_runner-0.3.2}/.github/workflows/ci.yml

@@ -82,7 +82,12 @@ jobs:
           python-version: ${{ matrix.python }}
           cache: pip
       - name: install
-        run: pip install -e ".[dev]"
+        # [sandbox] pulls the pure-Python Landlock/seccomp bindings only on
+        # Linux (their sys_platform=='linux' markers make this a no-op on
+        # macOS), so the Linux legs exercise real seccomp enforcement in the
+        # kill-tests; test_kill_tests_not_skipped.py fails loudly if a
+        # capable runner ever skips them instead of asserting the denial.
+        run: pip install -e ".[dev,sandbox]"
       - name: ruff
         run: |
           ruff check .

{cli_agent_runner-0.3.1 → cli_agent_runner-0.3.2}/.vulture-whitelist.py

@@ -20,6 +20,7 @@ context_enrichers
 post_round_hooks
 serve_startup_hooks
 dirty_handlers
+spawn_hooks
 detectors
 event_kinds
 
@@ -34,6 +35,12 @@ 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
@@ -123,6 +130,11 @@ 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
@@ -143,6 +155,7 @@ phase
 checks
 overlaps
 plan
+sandbox
 
 # agent_runner.config.models.AgentConfig
 command
@@ -193,6 +206,9 @@ phase_policy
 
 # agent_runner.config.models.PluginsConfig
 disable
+spawn_override_allow
+sandbox
+pin
 raw
 
 # agent_runner.config.models.Profile
@@ -289,6 +305,10 @@ 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.1 → cli_agent_runner-0.3.2}/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.2] - 2026-09-14
+
+### Added
+- Opt-in confinement for third-party plugin code (the hooks the supervisor runs in its own process — NOT the agent): a per-call Landlock+seccomp trampoline around third-party spawn hooks and dirty handlers, behind the `[sandbox]` extra. `[plugins] sandbox = require|prefer|off` (default `prefer`: run unconfined but announce it; `require` refuses boot when the sandbox can't engage). Built-in plugins are trusted by module provenance, not by name.
+- Checksum pinning: `[plugins.pin]` verifies a third-party plugin's sha256 before import and fails closed on a mismatch; `doctor` prints each third-party plugin's computed hash to paste in.
+- A `SpawnHook` plugin family that can defer or skip a round's spawn, gated by `[plugins] spawn_override_allow` (empty by default — no plugin alters a spawn until named).
+- `peek --json` (schema `2.2`) and `doctor` report the achieved sandbox tier, `libseccomp` presence, and per-plugin pin status, naming only the families actually confined.
+- New events: `plugin_checksum_mismatch`, `plugin_sandbox_degraded`, `plugin_sandbox_kill`, `plugin_spawn_decision`, `plugin_spawn_override_ignored`, `plugin_builtin_name_squat`.
+
 ## [0.3.1] - 2026-09-14
 
 ### Added

{cli_agent_runner-0.3.1 → cli_agent_runner-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.1
+Version: 0.3.2
 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,6 +34,9 @@ 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.2/agent_runner/__init__.py

@@ -0,0 +1,224 @@
+"""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 _entry_point_module_path(value: str) -> str:
+    """The resolvable module-path portion of an entry-point ``value``
+    (``"module.path:attr [extras]"``), with any ``:attr`` suffix and trailing
+    extras marker stripped.
+
+    Shared by ``load_and_register_plugins``'s import resolution and
+    ``doctor``'s per-plugin checksum print (``cli/doctor_cmd.py``) — the
+    checksum print and the actual import MUST resolve the identical module,
+    or an operator's pinned digest would silently protect the wrong file.
+    """
+    return value.partition("[")[0].rstrip().partition(":")[0]
+
+
+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 — the
+    load-bearing fix: verification now has a Config to gate on. 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, so it's what
+    ``_admit_third_party`` gates on (pin lookup) and what ``doctor`` prints a
+    checksum against. 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 a third-party
+    plugin has no such guarantee — which is fine, since admission never reads
+    the manifest name at all.
+
+    Builtin trust is decided by ``is_builtin_provenance(name, module_path)`` —
+    a reserved name AND a module genuinely under
+    ``agent_runner.builtin_plugins``. A reserved name alone is NOT enough: a
+    name-squatter (reserved name, foreign module) is treated as third-party,
+    flows through ``_admit_third_party``, and raises a loud
+    ``plugin_builtin_name_squat`` signal. Only genuine builtins skip the gate.
+
+    Every non-builtin entry passes through ``_admit_third_party`` BEFORE import
+    — a pin mismatch or an unpinned plugin under ``sandbox = "require"`` refuses
+    to import that ONE plugin (fail-closed; never loads unconfined).
+    """
+    import warnings
+
+    from agent_runner._plugin_manifest import loaded_manifest_names, register_manifest
+    from agent_runner._registry import (
+        BUILTIN_PLUGIN_NAMES,
+        is_builtin_provenance,
+        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(":")
+        # Builtin trust is keyed on PROVENANCE (module genuinely under
+        # agent_runner.builtin_plugins), never on the entry-point NAME alone —
+        # a reserved name is collidable, so a third-party package shipping an
+        # entry named e.g. "pi" is a name-squatter, not a builtin.
+        is_builtin = is_builtin_provenance(name, module_path)
+        if not is_builtin:
+            if name in BUILTIN_PLUGIN_NAMES:
+                _warn_builtin_name_squat(name, module_path, log_dir)
+            if not _admit_third_party(name, module_path, plugins_cfg, log_dir):
+                continue
+        try:
+            target = resolve_entry_target(module_path, attr_path)
+            register_manifest(
+                target, builtin=is_builtin, module_path=module_path, attr_path=attr_path
+            )
+        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 _warn_builtin_name_squat(name: str, module_path: str, log_dir) -> None:
+    """A discovered entry point claims a RESERVED builtin name while resolving
+    to a non-core module — a name-squatter. Builtin trust is denied (the entry
+    still flows through ``_admit_third_party``'s pin/sandbox gate); this makes
+    the claim LOUD (a warning always, plus an auditable event when a log_dir is
+    available) rather than a silent trust bypass."""
+    import warnings
+
+    warnings.warn(
+        f"{_PLUGIN_GROUP} entry {name!r} claims a reserved builtin name but resolves to "
+        f"non-core module {module_path!r}; treating as third-party (pin/sandbox gate applies)",
+        stacklevel=4,
+    )
+    if log_dir is not None:
+        from agent_runner.api import emit_plugin_builtin_name_squat
+
+        emit_plugin_builtin_name_squat(log_dir, name=name, module_path=module_path)
+
+
+def _admit_third_party(name: str, module_path: str, plugins_cfg, log_dir) -> bool:
+    """Fail-closed pin/sandbox gate for a non-builtin plugin (any entry lacking
+    genuine builtin provenance, INCLUDING a reserved-name squatter). Returns
+    False to refuse (and emit) — skipping this ONE plugin; every other
+    discovered entry still loads.
+
+    Both ``name`` and ``pins``' keys are entry-point names — see
+    ``load_and_register_plugins``'s docstring. Runs BEFORE
+    ``importlib.import_module``, so no plugin code executes for a refused
+    entry.
+    """
+    from agent_runner._plugin_checksum import verify_pin
+    from agent_runner._sandbox_probe import probe_sandbox_capability
+    from agent_runner.api import emit_plugin_checksum_mismatch, emit_plugin_sandbox_degraded
+
+    try:
+        verdict, actual = verify_pin(name, module_path, plugins_cfg.pin)
+    except Exception:  # noqa: BLE001 — unresolvable/unreadable module == refuse (fail closed)
+        verdict, actual = "mismatch", "sha256:unreadable"
+    if verdict == "mismatch":
+        if log_dir is not None:
+            emit_plugin_checksum_mismatch(
+                log_dir,
+                name=name,
+                expected=plugins_cfg.pin.get(name, ""),
+                actual=actual or "sha256:unreadable",
+            )
+        return False
+    if verdict == "unpinned" and plugins_cfg.sandbox == "require":
+        if log_dir is not None:
+            probe = probe_sandbox_capability()
+            emit_plugin_sandbox_degraded(
+                log_dir,
+                requested="require",
+                achieved_tier=probe.achieved_tier,
+                reason=f"{name}: unpinned third-party plugin under sandbox=require",
+            )
+        return False
+    return True
+
+
+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).
+
+    Known limitation: vcs_state._PLUGIN_OWNED_PATHS lacks per-plugin name
+    attribution today, so owned-paths are NOT filtered here. Disabled plugin's
+    paths remain registered (mostly inert).
+    """
+    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.1 → cli_agent_runner-0.3.2}/agent_runner/_emit/__init__.py

@@ -39,6 +39,14 @@ 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,
@@ -80,6 +88,12 @@ __all__ = [
     "emit_mem_loop",
     "emit_mem_loop_persistent",
     "emit_mem_pressure_deferred_to_cgroup",
+    "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",

cli_agent_runner-0.3.2/agent_runner/_emit/plugins.py

@@ -0,0 +1,76 @@
+"""Event emission wrappers -- plugin-security domain (sandbox trampoline).
+Re-exported from ``agent_runner._emit`` (the package facade) -- see its docstring."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def emit_plugin_sandbox_kill(
+    log_dir: Path, *, hook: str, signal: int, syscall: str | None = None
+) -> None:
+    """Emit when a trampoline child died by signal (seccomp KILL_PROCESS) -- a
+    denied syscall. Distinct from the caller's own hook_failed isolation, which
+    also fires: this event names the DENIAL specifically."""
+    from agent_runner.events import PLUGIN_SANDBOX_KILL, emit
+
+    emit(log_dir, PLUGIN_SANDBOX_KILL, hook=hook, signal=signal, syscall=syscall)
+
+
+def emit_plugin_spawn_decision(
+    log_dir: Path, *, hook: str, action: str, defer_s: int, reason: str
+) -> None:
+    """Emit the collapsed pre-spawn verdict the serve admission gate acted on --
+    ``defer`` or ``skip`` (a ``proceed`` is the silent default, no event). ``hook``
+    is the winning hook by the collapse's own precedence (skip > max-defer)."""
+    from agent_runner.events import PLUGIN_SPAWN_DECISION, emit
+
+    emit(log_dir, PLUGIN_SPAWN_DECISION, hook=hook, action=action, defer_s=defer_s, reason=reason)
+
+
+def emit_plugin_spawn_override_ignored(log_dir: Path, *, hook: str, action: str) -> None:
+    """Emit when a spawn hook returned a non-``proceed`` verdict but is NOT in
+    ``[plugins] spawn_override_allow`` -- its blocking power is denied (the
+    decision is downgraded to ``proceed`` before the collapse). Blocking a round
+    is an operator-granted capability, so an un-listed hook's ``defer``/``skip``
+    is audited here rather than honored silently."""
+    from agent_runner.events import PLUGIN_SPAWN_OVERRIDE_IGNORED, emit
+
+    emit(log_dir, PLUGIN_SPAWN_OVERRIDE_IGNORED, hook=hook, action=action)
+
+
+def emit_plugin_builtin_name_squat(log_dir: Path, *, name: str, module_path: str) -> None:
+    """Emit when a discovered entry point claims a RESERVED builtin name while
+    resolving to a module OUTSIDE the core ``agent_runner.builtin_plugins``
+    namespace -- a name-squatter. Builtin trust is denied: the entry falls
+    through to the third-party pin/sandbox gate. This event makes the claim
+    auditable rather than silent."""
+    from agent_runner.events import PLUGIN_BUILTIN_NAME_SQUAT, emit
+
+    emit(log_dir, PLUGIN_BUILTIN_NAME_SQUAT, name=name, module_path=module_path)
+
+
+def emit_plugin_checksum_mismatch(log_dir: Path, *, name: str, expected: str, actual: str) -> None:
+    """Emit when a third-party plugin's computed sha256 doesn't match its
+    ``[plugins.pin]`` entry (or the pin is unreadable) -- the loader refuses
+    to import that ONE plugin when this fires; it never loads unconfined."""
+    from agent_runner.events import PLUGIN_CHECKSUM_MISMATCH, emit
+
+    emit(log_dir, PLUGIN_CHECKSUM_MISMATCH, name=name, expected=expected, actual=actual)
+
+
+def emit_plugin_sandbox_degraded(
+    log_dir: Path, *, requested: str, achieved_tier: str, reason: str
+) -> None:
+    """Emit when a plugin loads (or would run) at a WEAKER tier than
+    ``requested`` -- e.g. an unpinned third-party plugin refused under
+    ``sandbox = "require"``, or a ``"prefer"`` load proceeding unconfined."""
+    from agent_runner.events import PLUGIN_SANDBOX_DEGRADED, emit
+
+    emit(
+        log_dir,
+        PLUGIN_SANDBOX_DEGRADED,
+        requested=requested,
+        achieved_tier=achieved_tier,
+        reason=reason,
+    )

{cli_agent_runner-0.3.1 → cli_agent_runner-0.3.2}/agent_runner/_observe.py

@@ -61,12 +61,20 @@ def peek(
     log: bool = False,
     events: int | None = None,
     select: str | None = None,
+    cfg: Any = None,
 ) -> ProjectState | Any:
-    """Build a ProjectState snapshot. With select, return that subtree."""
+    """Build a ProjectState snapshot. With select, return that subtree.
+
+    ``cfg`` (an already-loaded ``Config``) lets a caller that has loaded config
+    once — ``cli.peek_cmd.cmd_peek`` does, for the ``emit`` block — pass it in so
+    ``peek`` does not re-``load_config`` (which re-runs plugin load/checksum/probe)
+    a second time per invocation. ``None`` loads it here (the default, unchanged
+    for every other caller)."""
     from agent_runner import round_view
 
     work_dir = project if isinstance(project, Path) else Path.cwd()
-    cfg = load_config(work_dir / "agent-runner.toml")
+    if cfg is None:
+        cfg = load_config(work_dir / "agent-runner.toml")
     log_dir = cfg.runtime.log_dir
     src = monitor.LocalSource(log_dir=log_dir)
     base_state = monitor.assemble_project_state(src, project=_project_name(work_dir))

cli_agent_runner-0.3.2/agent_runner/_plugin_checksum.py

@@ -0,0 +1,62 @@
+"""sha256 pinning of a plugin's declared entry-point module FILE (coarse but
+deterministic — one file, one read). Fail-closed: an unresolvable/unreadable
+module raises, and the loader turns that into a refusal, same as a mismatch.
+
+Keyed on the entry-point NAME (the ``agent_runner.plugins`` group's own
+pyproject.toml key), not ``PluginManifest.name`` — a third-party plugin
+hasn't been imported yet at pin-check time, so its manifest name isn't even
+known; the entry-point name is the only stable, pre-import identifier an
+operator can write into ``[plugins.pin]``. See
+``agent_runner.__init__._admit_third_party`` for the call site.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from typing import Literal
+
+PinVerdict = Literal["verified", "mismatch", "unpinned"]
+
+_CHECKSUM_CACHE: dict[str, str] = {}
+"""Process-wide memo of ``module_path -> digest``, keyed post-resolution.
+A ``doctor``/``peek --json`` invocation hashes each pinned third-party file
+twice (once at load via ``verify_pin``, once for the snapshot print) — this
+avoids the second read of the SAME file in the SAME process. Never
+invalidated (a process's view of its own already-imported modules doesn't
+change mid-run); the comparison logic below is untouched."""
+
+
+def compute_plugin_checksum(module_path: str) -> str:
+    """sha256 of the resolved module's source FILE, as ``"sha256:<64hex>"``.
+
+    This exact recipe (sha256 of the raw bytes of ``find_spec(module_path)
+    .origin``) is also what ``doctor`` prints and what ``verify_pin`` checks
+    against — an operator copy-pastes doctor's printed digest straight into
+    ``[plugins.pin]``, so all three MUST compute the identical value.
+    """
+    cached = _CHECKSUM_CACHE.get(module_path)
+    if cached is not None:
+        return cached
+    spec = importlib.util.find_spec(module_path)
+    if spec is None or spec.origin is None:
+        raise ModuleNotFoundError(f"cannot resolve module file for {module_path!r}")
+    with open(spec.origin, "rb") as f:
+        digest = hashlib.sha256(f.read()).hexdigest()
+    checksum = f"sha256:{digest}"
+    _CHECKSUM_CACHE[module_path] = checksum
+    return checksum
+
+
+def verify_pin(name: str, module_path: str, pins: dict[str, str]) -> tuple[PinVerdict, str | None]:
+    """Returns ``(verdict, actual)`` where ``actual`` is the computed
+    ``"sha256:<hex>"`` digest of the module file, or ``None`` when the name is
+    unpinned (no digest is computed in that case). The caller reuses ``actual``
+    for the mismatch event instead of hashing the file a second time.
+
+    ``name`` is the entry-point name (the ``[plugins.pin]`` key an operator
+    writes), NOT ``PluginManifest.name`` — see module docstring."""
+    if name not in pins:
+        return "unpinned", None
+    actual = compute_plugin_checksum(module_path)
+    return ("verified" if actual == pins[name] else "mismatch"), actual

{cli_agent_runner-0.3.1 → cli_agent_runner-0.3.2}/agent_runner/_plugin_manifest.py

@@ -1,6 +1,6 @@
 """The plugin ABI: one typed, declared capability manifest per plugin, read
-by the loader (agent_runner/__init__.py::_load_plugin_manifests) instead of
-relying on import-time register_*() side effects. One entry-point group,
+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(...)`.
 """
@@ -17,6 +17,7 @@ from agent_runner.hooks import (
     PostRoundHook,
     PreRoundHook,
     ServeStartupHook,
+    SpawnHook,
 )
 
 
@@ -32,6 +33,7 @@ class PluginManifest:
     post_round_hooks: tuple[PostRoundHook, ...] = ()
     serve_startup_hooks: tuple[ServeStartupHook, ...] = ()
     dirty_handlers: tuple[DirtyHandler, ...] = ()
+    spawn_hooks: tuple[SpawnHook, ...] = ()
     detectors: tuple[Detector, ...] = ()
     event_kinds: tuple[str, ...] = ()
 
@@ -39,11 +41,38 @@ class PluginManifest:
 _LOADED_MANIFESTS: list[PluginManifest] = []
 
 
-def register_manifest(manifest: PluginManifest) -> None:
+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 and by doctor for third-party hash listing."""
+    return [m.name for m in _LOADED_MANIFESTS]
+
+
+def register_manifest(
+    manifest: PluginManifest,
+    *,
+    builtin: bool = False,
+    module_path: str = "",
+    attr_path: str = "",
+) -> 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.
 
+    ``builtin`` records whether this manifest is a GENUINE builtin (verified by
+    ``is_builtin_provenance`` at the load path) — it is threaded to
+    ``register_dirty_handler`` so ``dispatch_dirty`` can grant in-process trust
+    by handler-object identity rather than by the collidable manifest name.
+    Defaults to False (fail-closed): any manifest registered outside the
+    verified load path — a direct ``register_manifest`` call, a test — is
+    treated as third-party and sandboxed.
+
+    ``module_path``/``attr_path`` are the DISCOVERED entry point's resolvable
+    location (``module:attr``); the loader threads them here so the trampoline
+    re-imports a third-party dirty handler / spawn hook from that exact path,
+    never from the collidable ``manifest.name`` — an entry-point name != the
+    manifest name (legal for third-party plugins) then still resolves.
+
     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
@@ -79,7 +108,13 @@ def register_manifest(manifest: PluginManifest) -> None:
     for h in manifest.serve_startup_hooks:
         hooks.register_serve_startup_hook(h)
     for d in manifest.dirty_handlers:
-        hooks.register_dirty_handler(d)
+        hooks.register_dirty_handler(
+            d, owner=manifest.name, builtin=builtin, module_path=module_path, attr_path=attr_path
+        )
+    for s in manifest.spawn_hooks:
+        hooks.register_spawn_hook(
+            s, owner=manifest.name, builtin=builtin, module_path=module_path, attr_path=attr_path
+        )
     for det in manifest.detectors:
         monitor.register_detector(det)
     for kind in manifest.event_kinds:
@@ -107,6 +142,15 @@ def unregister_by_name(names: set[str]) -> set[str]:
         _remove_by_identity(hooks._POST_ROUND_HOOKS, manifest.post_round_hooks)
         _remove_by_identity(hooks._SERVE_STARTUP_HOOKS, manifest.serve_startup_hooks)
         _remove_by_identity(hooks._DIRTY_HANDLERS, manifest.dirty_handlers)
+        for h in manifest.dirty_handlers:
+            hooks._DIRTY_HANDLER_OWNER.pop(id(h), None)
+            hooks._DIRTY_HANDLER_BUILTIN.pop(id(h), None)
+            hooks._DIRTY_HANDLER_MODULE.pop(id(h), None)
+        _remove_by_identity(hooks._SPAWN_HOOKS, manifest.spawn_hooks)
+        for h in manifest.spawn_hooks:
+            hooks._SPAWN_HOOK_OWNER.pop(id(h), None)
+            hooks._SPAWN_HOOK_BUILTIN.pop(id(h), None)
+            hooks._SPAWN_HOOK_MODULE.pop(id(h), None)
         _remove_by_identity(monitor._PLUGIN_DETECTORS, manifest.detectors)
         for kind in manifest.event_kinds:
             events._PLUGIN_KINDS.pop(kind, None)