agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/plugins/_cli.py

@@ -0,0 +1,244 @@
+"""Entry-point loaders for CLI plugins.
+
+``agent_env.cli_plugins`` entries must resolve to top-level click commands/groups;
+``agent_env.cli_root_options`` entries to ``click.Option`` instances that attach to the
+root ``agent-env`` group. Broken plugins warn and are skipped; core names win over plugins;
+two different root options on the same flag are both left off and reported as a conflict.
+Full contract in the README ("Extending the CLI (plugins)").
+"""
+
+import sys
+from contextlib import redirect_stdout
+from importlib.metadata import EntryPoint, entry_points
+from typing import Any
+from weakref import WeakKeyDictionary
+
+import click
+from click.core import ParameterSource
+
+from agent_env.plugins import _report, _requirements
+from agent_env.plugins._discovery import discovery_error, dist_name, identity, sort_key
+from agent_env.plugins._inventory import Claimant, Contribution, Diagnostic
+
+CLI_PLUGINS_GROUP = "agent_env.cli_plugins"
+CLI_ROOT_OPTIONS_GROUP = "agent_env.cli_root_options"
+
+
+# What each loader did, per root group, so `agent-env plugin` can report it without reloading.
+_OUTCOMES: WeakKeyDictionary[click.Group, dict[tuple[str, str], list[Contribution]]] = WeakKeyDictionary()
+# Each entry-point group whose installed metadata could not be read, per root group.
+_DISCOVERY_ERRORS: WeakKeyDictionary[click.Group, dict[str, Diagnostic]] = WeakKeyDictionary()
+# Where each guarded root option came from, for the warning and the record when its callback fails.
+_SOURCES: WeakKeyDictionary[click.Option, tuple[EntryPoint, str]] = WeakKeyDictionary()
+
+
+def cli_contributions(group: click.Group) -> dict[tuple[str, str], list[Contribution]]:
+    """The CLI entry points loaded onto ``group``, by (distribution, version), with their outcome."""
+    return {key: list(found) for key, found in _OUTCOMES.get(group, {}).items()}
+
+
+def cli_discovery_errors(group: click.Group) -> dict[str, Diagnostic]:
+    """The CLI entry-point groups that could not be read while loading onto ``group``, with why."""
+    return dict(_DISCOVERY_ERRORS.get(group, {}))
+
+
+def load_cli_plugins(group: click.Group) -> None:
+    """Register installed ``agent_env.cli_plugins`` entry points onto ``group``."""
+    added_by: dict[str, tuple[str, EntryPoint]] = {}
+    for ep, origin, plugin in _discover(group, CLI_PLUGINS_GROUP, "CLI plugin"):
+        if _incompatible(group, ep, CLI_PLUGINS_GROUP, origin):
+            continue
+        try:
+            command = _load(ep)
+        except (Exception, SystemExit) as exc:
+            _warn(f"{origin} failed to load and was skipped: {exc!r}")
+            _record(group, ep, CLI_PLUGINS_GROUP, "failed", code=_report.LOAD_FAILED,
+                    reason=f"failed to load: {exc!r}")
+            continue
+        if not isinstance(command, click.Command):
+            _warn(f"{origin} is not a click.Command and was skipped")
+            _record(group, ep, CLI_PLUGINS_GROUP, "failed", code=_report.INVALID_PLUGIN,
+                    reason="is not a click.Command")
+            continue
+        # The entry-point name, as in every group: what the report, --help and the user all use.
+        name = ep.name
+        if name in group.commands:
+            _warn(f"{origin} clashes with existing command {name!r} and was skipped")
+            if name in added_by:
+                owner, owner_ep = added_by[name]
+                _record(group, ep, CLI_PLUGINS_GROUP, "skipped", code=_report.NAME_CONFLICT,
+                        reason=f"clashes with existing command {name!r} from plugin {owner}",
+                        conflicts_with=(_claimant(owner_ep),))
+            else:
+                _record(group, ep, CLI_PLUGINS_GROUP, "skipped", code=_report.BUILTIN_NAME,
+                        reason=f"clashes with existing command {name!r}")
+            continue
+        try:
+            group.add_command(command, name=name)
+        except Exception as exc:
+            _warn(f"{origin} could not be registered and was skipped: {exc!r}")
+            _record(group, ep, CLI_PLUGINS_GROUP, "failed", code=_report.INVALID_PLUGIN,
+                    reason=f"could not be registered: {exc!r}")
+            continue
+        added_by[name] = (plugin, ep)
+        _record(group, ep, CLI_PLUGINS_GROUP, "active")
+
+
+def load_cli_root_options(group: click.Group) -> None:
+    """Attach installed ``agent_env.cli_root_options`` entry points to ``group``.
+
+    Each must be an optional ``click.Option`` with ``expose_value=False``: it is parsed before
+    the subcommand and acts through its callback (which click also invokes with ``None`` when
+    the flag is absent), never through the root callback's arguments. A flag core already owns
+    is skipped with a warning. Different options on the same flag are all left off and recorded
+    as a conflict: a collision never silently picks a winner, and the CLI still starts, so
+    `plugin remove` can fix it. One option object exported twice, even by two packages, is one
+    callback, so it is attached once.
+    """
+    core_flags = set(group.context_settings.get("help_option_names") or ["--help"])
+    core_flags.update(flag for param in group.params for flag in (*param.opts, *param.secondary_opts))
+    candidates: list[tuple[EntryPoint, str, str, click.Option]] = []
+    for ep, origin, plugin in _discover(group, CLI_ROOT_OPTIONS_GROUP, "CLI root option"):
+        if _incompatible(group, ep, CLI_ROOT_OPTIONS_GROUP, origin):
+            continue
+        try:
+            option = _load(ep)
+        except (Exception, SystemExit) as exc:
+            _warn(f"{origin} failed to load and was skipped: {exc!r}")
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "failed", code=_report.LOAD_FAILED,
+                    reason=f"failed to load: {exc!r}")
+            continue
+        if not isinstance(option, click.Option):
+            _warn(f"{origin} is not a click.Option and was skipped")
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "failed", code=_report.INVALID_PLUGIN,
+                    reason="is not a click.Option")
+            continue
+        if option.expose_value or option.required:
+            _warn(f"{origin} must be optional with expose_value=False and was skipped")
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "failed", code=_report.INVALID_PLUGIN,
+                    reason="must be optional with expose_value=False")
+            continue
+        clash = sorted(set(_flags(option)) & core_flags)
+        if clash:
+            _warn(f"{origin} clashes with core root option {clash[0]!r} and was skipped")
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "skipped", code=_report.BUILTIN_NAME,
+                    reason=f"clashes with core root option {clash[0]!r}")
+            continue
+        candidates.append((ep, origin, plugin, option))
+    for ep, origin, _, option in candidates:
+        # Other option objects on one of its flags; the same object listed twice is not a rival.
+        rivals = [(other_ep, other_plugin, set(_flags(other)) & set(_flags(option)))
+                  for other_ep, _, other_plugin, other in candidates if other is not option]
+        rivals = [(other_ep, other_plugin, shared) for other_ep, other_plugin, shared in rivals if shared]
+        if rivals:
+            flags = ", ".join(repr(flag) for flag in sorted(set().union(*(shared for *_, shared in rivals))))
+            reason = f"root option {flags} is also registered by {' and '.join(p for _, p, _ in rivals)}"
+            _warn(f"{origin} was not attached: {reason}")
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "conflict", code=_report.NAME_CONFLICT, reason=reason,
+                    conflicts_with=tuple(_claimant(other_ep) for other_ep, _, _ in rivals))
+            continue
+        if option in group.params:
+            _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "active", code=_report.ALREADY_ATTACHED,
+                    reason="the same option object is already attached")
+            continue
+        _guard(option, ep, origin)
+        group.params.append(option)
+        _record(group, ep, CLI_ROOT_OPTIONS_GROUP, "active")
+
+
+def _incompatible(group: click.Group, ep: EntryPoint, kind: str, origin: str) -> bool:
+    """Record and warn about ``ep`` when its distribution's requirements exclude the installed agent-env."""
+    unmet = _requirements.incompatibility(getattr(ep, "dist", None))
+    if unmet is None:
+        return False
+    _warn(f"{origin} was skipped: it {unmet}")
+    _record(group, ep, kind, "failed", code=_report.INCOMPATIBLE_CORE, reason=unmet)
+    return True
+
+
+def _flags(option: click.Option) -> tuple[str, ...]:
+    return (*option.opts, *option.secondary_opts)
+
+
+def _claimant(ep: EntryPoint) -> Claimant:
+    return Claimant(*identity(ep), getattr(ep, "value", "") or "")
+
+
+def _guard(option: click.Option, ep: EntryPoint, origin: str) -> None:
+    """Wrap ``option``'s callback so that, if it raises while the flag is absent, it is skipped and
+    recorded as failed: click calls it on every invocation, so it would otherwise stop every
+    command, `plugin remove` included. A flag the user gave still raises. What it prints with the
+    flag absent goes to stderr, so it cannot corrupt a command's `--json`. The option object stays
+    the plugin's own, so code holding it still finds it in the root group's params."""
+    _SOURCES[option] = (ep, origin)
+    callback = option.callback
+    if callback is None or getattr(callback, "_agent_env_guard", False):
+        return
+
+    def call(ctx: click.Context, param: click.Parameter, value: Any) -> Any:
+        given = ctx.get_parameter_source(param.name) if param.name else None
+        absent = given in (None, ParameterSource.DEFAULT)
+        try:
+            if not absent:
+                return callback(ctx, param, value)
+            with redirect_stdout(sys.stderr):
+                return callback(ctx, param, value)
+        except (Exception, SystemExit) as exc:
+            source, where = _SOURCES.get(param, (ep, origin))
+            if not absent:
+                if isinstance(exc, (click.ClickException, click.exceptions.Exit, click.exceptions.Abort)):
+                    raise
+                via = f" (set by ${param.envvar})" if given == ParameterSource.ENVIRONMENT and param.envvar else ""
+                raise click.ClickException(f"{where}{via} failed: {exc!r}") from exc
+            _warn(f"{where} failed with its flag absent and was skipped: {exc!r}")
+            _mark(ctx.find_root().command, source, f"its callback failed with the flag absent: {exc!r}")
+            return None
+
+    call._agent_env_guard = True  # type: ignore[attr-defined]
+    option.callback = call
+
+
+def _mark(group: click.Group, ep: EntryPoint, reason: str) -> None:
+    """Record an attached root option as failed after all."""
+    found = _OUTCOMES.get(group, {}).get(identity(ep), [])
+    for i, c in enumerate(found):
+        if (c.group, c.name) == (CLI_ROOT_OPTIONS_GROUP, ep.name):
+            found[i] = Contribution(c.group, c.name, c.value, "failed", code=_report.LOAD_FAILED, reason=reason)
+
+
+def _discover(group: click.Group, group_name: str, label: str) -> list[tuple[EntryPoint, str, str]]:
+    """``(entry point, origin for messages, plugin label)`` per installed entry point, by name."""
+    try:
+        eps = sorted(entry_points(group=group_name), key=sort_key)
+    except Exception as exc:
+        reason = discovery_error(exc)
+        _warn(f"{label} discovery failed; none loaded: {reason}")
+        _DISCOVERY_ERRORS.setdefault(group, {})[group_name] = Diagnostic(_report.ENTRY_POINTS_UNREADABLE, reason)
+        return []
+    found = []
+    for ep in eps:
+        dist = dist_name(ep)
+        plugin = f"{ep.name!r}" + (f" from {dist!r}" if dist else "")
+        found.append((ep, f"{label} {plugin}", plugin))
+    return found
+
+
+def _load(ep: EntryPoint) -> Any:
+    # What a plugin prints while it is imported must not land in a command's stdout, e.g. --json.
+    with redirect_stdout(sys.stderr):
+        return ep.load()
+
+
+def _record(
+    group: click.Group, ep: EntryPoint, kind: str, status: str, *, code: str | None = None, reason: str | None = None,
+    conflicts_with: tuple[Claimant, ...] = (),
+) -> None:
+    contribution = Contribution(
+        kind, ep.name, getattr(ep, "value", "") or "", status, code=code, reason=reason, conflicts_with=conflicts_with
+    )
+    _OUTCOMES.setdefault(group, {}).setdefault(identity(ep), []).append(contribution)
+
+
+def _warn(message: str) -> None:
+    # Logging isn't configured yet at import time; warn on stderr instead.
+    click.echo(f"Warning: {message}", err=True)

agent_env/plugins/_discovery.py

@@ -0,0 +1,97 @@
+"""Reading installed entry points: which distribution claims which name in each plugin group.
+
+Internal: the public contract is ``agent_env.plugins``. Discovery reads installed metadata only
+and imports no plugin code; ``_registration`` imports a group's plugins when its registry is built.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib.metadata import EntryPoint, distributions, entry_points
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Plugin:
+    """Where an entry-point registration came from."""
+
+    name: str
+    value: str
+    dist: str
+    version: str
+
+    def __str__(self) -> str:
+        source = f"{self.dist} {self.version}".strip() or "an unreadable distribution"
+        return f"{self.name!r} from {source} ({self.value})"
+
+
+def claims(group: str) -> dict[str, list[tuple[Plugin, EntryPoint]]]:
+    """Every distinct claim per entry-point name in ``group``, in a deterministic order."""
+    eps = sorted(entry_points(group=group), key=sort_key)
+    found: dict[str, list[tuple[Plugin, EntryPoint]]] = {}
+    for ep in eps:
+        plugin = Plugin(ep.name, getattr(ep, "value", "") or "", dist_name(ep), dist_version(ep))
+        seen = found.setdefault(ep.name, [])
+        # The same distribution found twice on the path is one registration, not a conflict.
+        if all((p.dist, p.value) != (plugin.dist, plugin.value) for p, _ in seen):
+            seen.append((plugin, ep))
+    return found
+
+
+def discover(group: str) -> dict[str, list[tuple[Plugin, EntryPoint]]]:
+    """``claims(group)``, or none with a warning when installed metadata cannot be read."""
+    try:
+        return claims(group)
+    except Exception:
+        logger.warning("Entry-point discovery for %s failed; no plugins loaded", group, exc_info=True)
+        return {}
+
+
+def discovery_error(exc: Exception) -> str:
+    """``exc`` from reading installed entry points, naming the distributions that cannot be read."""
+    unreadable = []
+    with suppress(Exception):
+        for dist in distributions():
+            try:
+                _ = dist.entry_points  # parses entry_points.txt
+            except Exception:
+                unreadable.append(str(getattr(dist, "_path", None) or "a distribution with no path"))
+    where = f" (unreadable entry points: {', '.join(unreadable)})" if unreadable else ""
+    return f"{type(exc).__name__}: {exc}{where}"
+
+
+def identity(ep: EntryPoint) -> tuple[str, str]:
+    """The (name, version) a contribution is listed under. A distribution with unreadable metadata
+    is named by where it is installed, so two such packages are not merged."""
+    name, version = dist_name(ep), dist_version(ep)
+    if name:
+        return name, version
+    try:
+        where = getattr(getattr(ep, "dist", None), "_path", None)
+    except Exception:
+        where = None
+    return (f"(unreadable metadata: {Path(where).name})" if where else "(unreadable metadata)"), version
+
+
+def sort_key(ep: EntryPoint) -> tuple[str, str, str]:
+    # ep.value tie-breaks even when both colliding dists have unreadable metadata.
+    return (ep.name, dist_name(ep), getattr(ep, "value", "") or "")
+
+
+def dist_name(ep: EntryPoint) -> str:
+    # Tolerates corrupt/missing distribution metadata — the name is only a label.
+    try:
+        return getattr(getattr(ep, "dist", None), "name", "") or ""
+    except Exception:
+        return ""
+
+
+def dist_version(ep: EntryPoint) -> str:
+    try:
+        return getattr(getattr(ep, "dist", None), "version", "") or ""
+    except Exception:
+        return ""

agent_env/plugins/_inventory.py

@@ -0,0 +1,262 @@
+"""``agent_env.plugins.inventory``: every installed plugin's contributions, and what became of each.
+
+Internal: the public names are re-exported from ``agent_env.plugins``. The registries are built on
+a throwaway Config that reads the caller's document, so the Config in use keeps its registries and
+its ``load_failures()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import KW_ONLY, dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Literal, Optional
+
+from agent_env.config import runtime
+from agent_env.config import snapshot as config_snapshot
+from agent_env.config.errors import ConfigError
+from agent_env.plugins import _discovery, _registration, _report, _requirements
+
+Status = Literal["active", "replaced", "failed", "skipped", "conflict", "blocked", "unloaded"]
+
+# Statuses a group-level error does not override: each already says why the name is missing.
+_SETTLED = frozenset({"failed", "skipped", "conflict"})
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Why a group, the config or entry-point discovery failed."""
+
+    code: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Claimant:
+    """Another entry point that claims the same name."""
+
+    package: str
+    version: str
+    value: str
+
+
+@dataclass(frozen=True)
+class Replacement:
+    """The config that registers a different class under a contribution's name."""
+
+    file: Optional[Path]
+    table: str
+    impl: str
+
+
+@dataclass(frozen=True)
+class Contribution:
+    """One entry point a distribution declares, and what became of it. ``code`` says why it has
+    its status, and is set exactly when ``reason`` is."""
+
+    group: str
+    name: str
+    value: str
+    status: Status
+    _: KW_ONLY
+    code: Optional[str] = None
+    reason: Optional[str] = None
+    replaced_by: Optional[Replacement] = None
+    conflicts_with: tuple[Claimant, ...] = ()
+
+
+@dataclass(frozen=True)
+class Distribution:
+    """An installed distribution that declares entry points in the type groups."""
+
+    name: str
+    version: str
+    contributions: tuple[Contribution, ...]
+
+
+@dataclass(frozen=True)
+class Inventory:
+    """Every installed plugin distribution, and the error each group's real build would raise."""
+
+    distributions: tuple[Distribution, ...]
+    # With load=False, only what metadata proves: that no config file was found.
+    group_errors: Mapping[str, Diagnostic]
+    # Groups whose installed entry points could not be read, so none of their plugins is listed.
+    discovery_errors: Mapping[str, Diagnostic]
+    config_path: Optional[Path]
+    config_error: Optional[Diagnostic]
+    loaded: bool
+
+
+for _public in (Claimant, Contribution, Diagnostic, Distribution, Inventory, Replacement):
+    _public.__module__ = "agent_env.plugins"
+
+
+def _groups() -> dict[str, tuple[Callable[[], Any], Callable[[runtime.Config], Any]]]:
+    """Per group: its built-in names, and how the probe builds it."""
+    # Imported here, not at the top: every registry imports agent_env.plugins, and so this module.
+    from agent_env.artifact.registry import ARTIFACT_REGISTRY
+    from agent_env.env import registry as env_registry
+    from agent_env.explorer.plugin import load_plugins
+    from agent_env.providers.env_providers import env_provider
+    from agent_env.providers.sandbox_providers.sandbox_provider import _BUILTIN_SANDBOX_PROVIDERS
+    from agent_env.providers.env_state.env_state_provider import _BUILTIN_STATE_PROVIDERS
+    from agent_env.task_step import registry as task_step_registry
+
+    return {
+        _registration.ENVS: (env_registry._builtin_registry, lambda probe: probe.env_registry()),
+        _registration.ARTIFACTS: (lambda: ARTIFACT_REGISTRY, lambda probe: probe.artifact_registry()),
+        _registration.TASK_STEPS: (task_step_registry._builtin_registry, lambda probe: probe.task_step_registry()),
+        _registration.SANDBOX_PROVIDERS: (lambda: _BUILTIN_SANDBOX_PROVIDERS, lambda probe: probe.sandbox_registry()),
+        _registration.STATE_PROVIDERS: (lambda: _BUILTIN_STATE_PROVIDERS, lambda probe: probe.state_registry()),
+        _registration.ENV_PROVIDERS: (env_provider._builtin_env_providers, lambda probe: probe.env_provider_registry()),
+        _registration.EXPLORER_PLUGINS: (dict, lambda probe: load_plugins(source=probe)),
+    }
+
+
+def inventory(config: Optional[runtime.Config] = None, *, load: bool = True) -> Inventory:
+    """Every installed distribution declaring entry points in the type groups, with a status per
+    contribution.
+
+    ``load=False`` reads installed metadata only: no plugin code runs, and a status that needs a
+    build (``active``, ``replaced``, ``failed``) is reported as ``unloaded``. ``load=True`` imports
+    the plugins, constructs the explorer plugins, and builds each group on a throwaway Config that
+    reads ``config``'s document (default: the process Config). ``config`` keeps its registries and
+    its ``load_failures()``; like any registry build, this pins its document first if nothing has
+    yet. Importing or constructing a plugin can still have process-wide effects, such as a package
+    that sets ``AGENT_ENV_CONFIG`` on import.
+    """
+    base = config or runtime.get_config()
+    try:
+        document = base._document()
+        missing = None
+    except ConfigError as exc:
+        # No config file was found: every real build raises this before merging anything, so the
+        # plugins are checked against an empty document and then blocked.
+        document, missing = config_snapshot.Snapshot(path=None, _document={}), exc
+    if missing is not None:
+        config_error = Diagnostic(_report.CONFIG_NOT_FOUND, str(missing))
+    elif document.error is not None:
+        config_error = Diagnostic(_report.CONFIG_UNREADABLE, str(document.error))
+    else:
+        config_error = None
+    # A malformed document is used as it is, so each build raises its parse error where a real one does.
+    probe = _registration.InventoryProbe(_snapshot=document) if load else None
+    group_errors: dict[str, Diagnostic] = {}
+    discovery_errors: dict[str, Diagnostic] = {}
+    by_distribution: dict[tuple[str, str], list[Contribution]] = {}
+    groups = _groups()
+    for group, (builtins_of, build) in groups.items():
+        try:
+            claims = _discovery.claims(group)
+        except Exception as exc:
+            discovery_errors[group] = Diagnostic(_report.ENTRY_POINTS_UNREADABLE, _discovery.discovery_error(exc))
+            continue
+        if not claims:
+            continue
+        builtins = frozenset(builtins_of())
+        registrations = None
+        if probe is not None:
+            try:
+                build(probe)
+            except (Exception, SystemExit) as exc:
+                group_errors[group] = Diagnostic(_build_error_code(exc, document), f"{type(exc).__name__}: {exc}")
+            registrations = probe.registrations.get(group)
+        if missing is not None:
+            group_errors[group] = Diagnostic(_report.CONFIG_NOT_FOUND, f"{type(missing).__name__}: {missing}")
+        for name, found in claims.items():
+            for plugin, ep in found:
+                contribution = _classify(group, name, plugin, ep, found, builtins, registrations, document.path)
+                if group in group_errors and contribution.status not in _SETTLED:
+                    error = group_errors[group]
+                    contribution = Contribution(
+                        group, name, plugin.value, "blocked", code=error.code, reason=error.reason
+                    )
+                by_distribution.setdefault(_discovery.identity(ep), []).append(contribution)
+    order = list(groups)
+    distributions = tuple(
+        Distribution(dist, version, tuple(sorted(found, key=lambda c: (order.index(c.group), c.name))))
+        for (dist, version), found in sorted(by_distribution.items(), key=lambda item: (item[0][0].lower(), item[0][1]))
+    )
+    return Inventory(
+        distributions=distributions,
+        group_errors=MappingProxyType(group_errors),
+        discovery_errors=MappingProxyType(discovery_errors),
+        config_path=document.path,
+        config_error=config_error,
+        loaded=load,
+    )
+
+
+def _classify(
+    group: str,
+    name: str,
+    plugin: _discovery.Plugin,
+    ep: Any,
+    found: list[tuple[_discovery.Plugin, Any]],
+    builtins: frozenset[str],
+    registrations: Optional[_registration.Registrations],
+    config_path: Optional[Path],
+) -> Contribution:
+    # Same precedence as merge: a built-in name is skipped for every claimant, before conflicts.
+    if name in builtins:
+        return Contribution(
+            group, name, plugin.value, "skipped", code=_report.BUILTIN_NAME, reason="clashes with a built-in"
+        )
+    # Read from metadata, so it is reported without loading. A claim that cannot load claims nothing,
+    # so it takes no part in a conflict, as in a build.
+    if (unmet := _requirements.incompatibility(getattr(ep, "dist", None))) is not None:
+        return Contribution(group, name, plugin.value, "failed", code=_report.INCOMPATIBLE_CORE, reason=unmet)
+    found = _usable(found)
+    if len(found) > 1:
+        others = [(other, other_ep) for other, other_ep in found if other != plugin]
+        alone = all((other.dist, other.version) == (plugin.dist, plugin.version) for other, _ in found)
+        who = "; ".join(str(other) for other, _ in others)
+        return Contribution(
+            group, name, plugin.value, "conflict", code=_report.NAME_CONFLICT,
+            reason=(f"this package declares the name more than once: {who}; report it to its author" if alone
+                    else f"also registered by {who}; remove all but one with `agent-env plugin remove <package>`"),
+            conflicts_with=tuple(_claimant(other, other_ep) for other, other_ep in others),
+        )
+    if registrations is None:
+        return Contribution(
+            group, name, plugin.value, "unloaded", code=_report.NOT_LOADED, reason="not imported (installed metadata only)"
+        )
+    if name in registrations.added:
+        return Contribution(group, name, plugin.value, "active")
+    if name in registrations.released:
+        table, impl, replacement = registrations.released[name]
+        if replacement is registrations.classes.get(name):
+            return Contribution(group, name, plugin.value, "active")
+        where = f"[{table}] of {config_path}" if config_path else f"[{table}]"
+        return Contribution(
+            group, name, plugin.value, "replaced", code=_report.REPLACED_BY_CONFIG,
+            reason=f"config names {impl!r} in {where}", replaced_by=Replacement(config_path, table, impl),
+        )
+    if name in registrations.failures:
+        reason = registrations.failures[name].removeprefix(f"registered by {plugin} but ")
+        return Contribution(group, name, plugin.value, "failed", code=registrations.codes[name], reason=reason)
+    # Unreachable while every registry records what it did; visible, not silent, if not.
+    return Contribution(
+        group, name, plugin.value, "unloaded", code=_report.STATUS_UNKNOWN, reason="its status could not be determined"
+    )
+
+
+def _usable(found: list[tuple[_discovery.Plugin, Any]]) -> list[tuple[_discovery.Plugin, Any]]:
+    """The claims whose requirements admit this agent-env; the others cannot load."""
+    return [(p, ep) for p, ep in found if _requirements.incompatibility(getattr(ep, "dist", None)) is None]
+
+
+def _claimant(plugin: _discovery.Plugin, ep: Any) -> Claimant:
+    package, version = _discovery.identity(ep)
+    return Claimant(package, version, plugin.value)
+
+
+def _build_error_code(exc: BaseException, document: config_snapshot.Snapshot) -> str:
+    """The code for what a group's build raised."""
+    if document.error is not None and exc is document.error:
+        return _report.CONFIG_UNREADABLE
+    if isinstance(exc, ConfigError):
+        return _report.CONFIG_INVALID
+    return _report.GROUP_BUILD_FAILED