agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/config/errors.py

@@ -0,0 +1,13 @@
+"""Errors for the ``.agentenv/config.toml`` configuration surface."""
+
+
+class ConfigError(ValueError):
+    """Raised when the ``.agentenv/config.toml`` (or a backend/section selection) is invalid."""
+
+    pass
+
+
+class EmptySecretBundleError(ConfigError, KeyError):
+    """Empty secret bundle — also a KeyError so key-tolerant callers keep degrading."""
+
+    __str__ = Exception.__str__  # KeyError.__str__ would repr-quote the message

agent_env/config/loader.py

@@ -0,0 +1,245 @@
+"""Loader for the ``.agentenv/config.toml`` config surface.
+
+Turns a store section (an ``impl`` dotted path + a ``config`` table) into a
+constructed store: resolve ``env:`` / ``secret:`` references (each with an optional
+``?default``), import the class, guard it against the target ABC, and call
+``from_config``. Secret values never live in the toml, only references. See the
+README for the schema and examples.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import logging
+import os
+import re
+import tomllib
+from importlib.metadata import PackageNotFoundError, metadata
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from packaging.requirements import Requirement
+
+from agent_env.config.errors import ConfigError
+
+logger = logging.getLogger(__name__)
+
+DISTRIBUTION = "agentenv-framework"
+_CANNOT_IMPORT_NAME = re.compile(r"cannot import name '([\w.]+)' from '([\w.]+)'")
+_NAME_SEPARATORS = re.compile(r"[-_.]+")
+_CONFIG_DIR = ".agentenv"
+_CONFIG_FILE = "config.toml"
+ENV_CONFIG_PATH = "AGENT_ENV_CONFIG"
+
+SecretResolver = Callable[[str], Optional[str]]
+
+ENV_REF_PREFIX = "env:"
+SECRET_REF_PREFIX = "secret:"
+
+# The keys a seam table may hold: the class, and the kwargs it is built with.
+SEAM_KEYS = ("impl", "config")
+
+
+def discover_config_path(start: Optional[Path] = None) -> Optional[Path]:
+    """Locate the config.toml: ``AGENT_ENV_CONFIG`` wins, else the nearest
+    ``.agentenv/config.toml`` walking up from ``start`` (CWD by default).
+
+    An explicit ``AGENT_ENV_CONFIG`` override must point to an existing file —
+    fail loud rather than silently drop the whole config (and derive local-store
+    paths from a non-existent directory) on a typo'd override path."""
+    override = os.getenv(ENV_CONFIG_PATH)
+    if override:
+        path = Path(override)
+        if not path.is_file():
+            raise ConfigError(f"{ENV_CONFIG_PATH}={override!r} does not point to an existing file")
+        return path
+    for candidate in _walk_up_candidates(start):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _walk_up_candidates(start: Optional[Path] = None) -> list[Path]:
+    here = (start or Path.cwd()).resolve()
+    return [directory / _CONFIG_DIR / _CONFIG_FILE for directory in (here, *here.parents)]
+
+
+def config_search_path(start: Optional[Path] = None) -> list[tuple[Path, str]]:
+    """Every path ``discover_config_path`` would consider, in order, and why.
+
+    Lives here because ``agent-env config debug`` exists to report discovery: a second copy
+    of the walk would put the one command that must not lie about the search path in charge
+    of guessing it.
+    """
+    override = os.getenv(ENV_CONFIG_PATH)
+    if override:
+        return [(Path(override), f"${ENV_CONFIG_PATH}")]
+    return [(path, "walk-up") for path in _walk_up_candidates(start)]
+
+
+_UTF8_BOM = b"\xef\xbb\xbf"
+
+
+def load_config_file(path: Optional[Path]) -> dict:
+    """Parse the config.toml at ``path`` (``{}`` when absent).
+
+    Deliberately lenient about a path that is not there: this is a public helper and the
+    sdk's exporter calls it with a freshly discovered path. Knowing that a path *was* just
+    discovered — so that losing it is a race and not an absent config — belongs to the
+    caller that discovered it, which is ``snapshot``; it uses ``read_config_file``.
+    """
+    if path is None or not path.is_file():
+        return {}
+    return read_config_file(path)
+
+
+def read_config_file(path: Path) -> dict:
+    """Parse the config.toml at ``path``, or raise.
+
+    No existence check: the open *is* the check. Testing first and reading second leaves a
+    window where the file can go, and a caller that has to ask "does it exist" before every
+    read has a race rather than an answer.
+    """
+    with open(path, "rb") as f:
+        raw = f.read()
+    # An editor that writes a UTF-8 BOM produces a file correct to its author and rejected by
+    # tomllib at line 1, column 1. The bytes carry no meaning here, so drop them.
+    raw = raw[len(_UTF8_BOM):] if raw.startswith(_UTF8_BOM) else raw
+    try:
+        return tomllib.loads(raw.decode("utf-8"))
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"Malformed config.toml at {path}: {e}") from e
+    except UnicodeDecodeError as e:
+        raise ConfigError(f"config.toml at {path} is not valid UTF-8: {e}") from e
+
+
+def interpolate(value: Any, *, secret_resolver: Optional[SecretResolver] = None) -> Any:
+    """Resolve ``env:NAME`` / ``secret:KEY`` string references (each with an optional
+    ``?default`` suffix), recursing into dicts/lists; pass any other value through
+    unchanged. ``secret:`` needs a ``secret_resolver``; when none is available (e.g.
+    while building the secret store itself) a ``secret:`` reference fails loud."""
+    if isinstance(value, dict):
+        return {k: interpolate(v, secret_resolver=secret_resolver) for k, v in value.items()}
+    if isinstance(value, list):
+        return [interpolate(v, secret_resolver=secret_resolver) for v in value]
+    if not isinstance(value, str):
+        return value
+    if value.startswith(ENV_REF_PREFIX):
+        return _resolve_ref(ENV_REF_PREFIX, value, os.getenv)
+    if value.startswith(SECRET_REF_PREFIX):
+        if secret_resolver is None:
+            raise ConfigError(f"Cannot resolve {value!r}: no secret store is available for secret: references here")
+        return _resolve_ref(SECRET_REF_PREFIX, value, secret_resolver)
+    return value
+
+
+def _resolve_ref(prefix: str, value: str, resolve: SecretResolver) -> str:
+    ref, sep, default = value[len(prefix):].partition("?")
+    resolved = resolve(ref)
+    if resolved is not None:
+        return resolved
+    if sep:
+        return default
+    raise ConfigError(f"Unresolved {prefix}{ref} reference (no value and no default)")
+
+
+def load_impl(impl: str | type, abc: type) -> type:
+    """Import the ``module.path:ClassName`` pointer ``impl`` and guard the class
+    against its target interface ``abc``. Shared by every ``.agentenv`` seam that
+    resolves a dotted impl pointer (stores, task steps). An already-loaded class, which is
+    what an entry-point plugin registers, is only guarded."""
+    if isinstance(impl, type):
+        if not issubclass(impl, abc):
+            raise ConfigError(f"impl {impl.__qualname__!r} is not a subclass of {abc.__name__}")
+        return impl
+    module_path, sep, attr = impl.partition(":")
+    if not sep or not attr:
+        raise ConfigError(f"impl must be 'module.path:ClassName', got {impl!r}")
+    try:
+        cls = getattr(importlib.import_module(module_path), attr)
+    except ImportError as e:
+        raise ConfigError(f"Cannot import impl {impl!r}: {e}{_install_hint(_missing_module(e))}") from e
+    except AttributeError as e:
+        raise ConfigError(f"Cannot import impl {impl!r}: {e}") from e
+    if not (isinstance(cls, type) and issubclass(cls, abc)):
+        raise ConfigError(f"impl {impl!r} is not a subclass of {abc.__name__}")
+    return cls
+
+
+def _missing_module(error: ImportError) -> str | None:
+    """The module an import failed to find. ``from pkg import mod`` on an absent ``mod`` names
+    ``pkg``, and ``mod`` only as ``name_from`` (3.12+) or in the message (3.11)."""
+    name_from = getattr(error, "name_from", None)
+    if name_from is None and (match := _CANNOT_IMPORT_NAME.match(str(error))):
+        return f"{match[2]}.{match[1]}"
+    return f"{error.name}.{name_from}" if error.name and name_from else error.name
+
+
+def _install_hint(module: str | None) -> str:
+    """Name the smallest extra of this distribution with a requirement named for the missing
+    ``module``: by name, because the missing distribution's files are not installed to read.
+    Separators are dropped before comparing, as ``google-cloud-secret-manager`` installs
+    ``google.cloud.secretmanager``."""
+    if not module:
+        return ""
+    try:
+        package = metadata(DISTRIBUTION)
+    except PackageNotFoundError:
+        return ""
+    wanted = _NAME_SEPARATORS.sub("", module).lower()
+    sizes: dict[str, int] = {}
+    matches: set[str] = set()
+    for line in package.get_all("Requires-Dist") or []:
+        requirement = Requirement(line)
+        if requirement.marker is None:
+            continue
+        for extra in package.get_all("Provides-Extra") or []:
+            if requirement.marker.evaluate({"extra": extra}):
+                sizes[extra] = sizes.get(extra, 0) + 1
+                if _NAME_SEPARATORS.sub("", requirement.name).lower() == wanted:
+                    matches.add(extra)
+    if not matches:
+        return ""
+    extra = min(matches, key=lambda e: (sizes[e], e))
+    return f"; it needs the {extra!r} extra, as in pip install '{DISTRIBUTION}[{extra}]'"
+
+
+def build_store(section: dict, abc: type, *, secret_resolver: Optional[SecretResolver] = None):
+    """Import the ``impl`` class named by ``section``, guard it against ``abc``,
+    and construct it via ``from_config`` with the interpolated ``config`` table."""
+    impl = section.get("impl")
+    if not impl:
+        raise ConfigError(f"Store section is missing an 'impl' dotted path: {section!r}")
+    for key in section:
+        if key not in SEAM_KEYS:
+            logger.warning("Ignoring unknown key %r in store section (expected 'impl'/'config')", key)
+    cls = load_impl(impl, abc)
+    config = interpolate(section.get("config", {}), secret_resolver=secret_resolver)
+    _check_config_keys(cls, abc, config, impl)
+    return cls.from_config(**config)
+
+
+def _check_config_keys(cls: type, abc: type, config: dict, impl: str | type) -> None:
+    """Refuse a config table the store can't take as a ConfigError naming the keys, where Python
+    would raise a TypeError that reads as a bug in the store. A class on its interface's default
+    ``from_config`` hands the table to its constructor, so that is what the table is checked
+    against; any other ``from_config`` is checked against its own parameters."""
+    target = cls if getattr(cls.from_config, "__func__", None) is getattr(abc.from_config, "__func__", ...) else cls.from_config
+    try:
+        parameters = inspect.signature(target).parameters.values()
+    except (TypeError, ValueError):
+        return
+    named = [p for p in parameters if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)]
+    takes_any = any(p.kind is p.VAR_KEYWORD for p in parameters)
+    unknown = [] if takes_any else sorted(set(config) - {p.name for p in named})
+    missing = [p.name for p in named if p.default is p.empty and p.name not in config]
+    if not unknown and not missing:
+        return
+    name = impl if isinstance(impl, str) else impl.__qualname__
+    problems = [f"unknown key {', '.join(map(repr, unknown))}"] if unknown else []
+    problems += [f"no value for {', '.join(map(repr, missing))}"] if missing else []
+    raise ConfigError(
+        f"The config table for {name!r} has {' and '.join(problems)}; "
+        f"it takes {', '.join(p.name for p in named) or 'no keys'}"
+    )

agent_env/config/model.py

@@ -0,0 +1,154 @@
+"""Resolution of the ``[model]`` config.toml block: endpoint, default/per-role models, and
+provider params. A ``ModelConfig`` value object parsed from the ``[model]`` table; a
+``secret_resolver`` is injected per call so secret references resolve lazily."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields
+from enum import StrEnum
+from typing import Optional
+
+from agent_env.config.errors import ConfigError
+from agent_env.config.loader import SecretResolver, interpolate
+
+_ENV_BASE_URL = "LITELLM_BASE_URL"
+_ENV_API_KEY = "LITELLM_API_KEY"
+
+
+class ModelParam(StrEnum):
+    """The ``litellm`` call kwargs agent-env sets itself; ``[model.params]`` may not override these."""
+
+    MODEL = "model"
+    MESSAGES = "messages"
+    API_KEY = "api_key"
+    API_BASE = "api_base"
+    USER = "user"
+    METADATA = "metadata"
+    TIMEOUT = "timeout"
+    RESPONSE_FORMAT = "response_format"
+
+
+MODEL_PARAMS_RESERVED = frozenset(p.value for p in ModelParam)
+
+
+@dataclass(frozen=True)
+class ModelCallConfig:
+    """Resolved api_base / api_key / params for one model call."""
+
+    api_key: Optional[str]
+    api_base: Optional[str]
+    params: dict
+
+    def client_kwargs(self) -> dict:
+        """``api_key`` + ``params``, plus ``api_base`` only when set."""
+        kwargs = {ModelParam.API_KEY: self.api_key, **self.params}
+        if self.api_base:
+            kwargs[ModelParam.API_BASE] = self.api_base
+        return kwargs
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """The parsed ``[model]`` block (every field optional; all-default when unconfigured)."""
+
+    base_url: Optional[str] = None
+    api_key: Optional[str] = None  # may hold an unresolved env:/secret: reference
+    default: Optional[str] = None
+    roles: dict = field(default_factory=dict)
+    params: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_section(cls, section: dict, *, secret_resolver: SecretResolver) -> ModelConfig:
+        """Build from the raw ``[model]`` section: reject unknown keys and reserved
+        ``[model.params]`` keys, then resolve ``env:``/``secret:`` refs — except
+        ``api_key``, which keeps its raw reference and resolves lazily per call
+        (an eager secret fetch would make every ``[model]`` read need credentials)."""
+        allowed = {f.name for f in fields(cls)}
+        unknown = set(section) - allowed
+        if unknown:
+            raise ConfigError(f"[model] has unknown keys {sorted(unknown)}; allowed: {sorted(allowed)}")
+        reserved = set(section.get("params", {})) & MODEL_PARAMS_RESERVED
+        if reserved:
+            raise ConfigError(
+                f"[model.params] may not set reserved keys {sorted(reserved)} "
+                "(agent-env sets these on the model call)"
+            )
+        cfg = interpolate(
+            {k: v for k, v in section.items() if k != "api_key"},
+            secret_resolver=secret_resolver,
+        )
+        return cls(
+            base_url=cfg.get("base_url"),
+            api_key=section.get("api_key"),
+            default=cfg.get("default"),
+            roles=cfg.get("roles", {}),
+            params=cfg.get("params", {}),
+        )
+
+    def model_for_role(self, role: str) -> Optional[str]:
+        """The ``[model.roles].<role>`` model, else ``default`` (open map)."""
+        return self.roles.get(role) or self.default
+
+    def resolve_api_key(self, *, secret_resolver: SecretResolver) -> str:
+        """Key: env ``LITELLM_API_KEY`` > ``api_key`` (resolving a reference lazily);
+        actionable failure when neither is set."""
+        key = os.getenv(_ENV_API_KEY) or self._resolved_api_key(secret_resolver)
+        if not key:
+            raise ConfigError(
+                "No model API key configured: set [model] api_key in .agentenv/config.toml "
+                f"(an env:/secret: reference is fine) or the {_ENV_API_KEY} env var."
+            )
+        return key
+
+    def _resolved_api_key(self, secret_resolver: SecretResolver) -> Optional[str]:
+        if self.api_key is None:
+            return None
+        return interpolate(self.api_key, secret_resolver=secret_resolver)
+
+    def resolve_call(
+        self,
+        model: str,
+        *,
+        default_api_key: Optional[str] = None,
+        base_override: Optional[str] = None,
+        model_overrides: Optional[dict[str, dict[str, str]]] = None,
+        secret_resolver: SecretResolver,
+    ) -> ModelCallConfig:
+        """A provider-prefixed model routes natively when no endpoint is configured; a bare
+        model name needs one (override/env/config) and fails actionably without it."""
+        if model_overrides:
+            override = model_overrides.get(model)
+            if override:
+                key = secret_resolver(override["secret_key"])
+                if key is None:
+                    raise ConfigError(
+                        f"Model override for {model!r} names secret {override['secret_key']!r}, "
+                        "which the configured secret store has no value for"
+                    )
+                return ModelCallConfig(
+                    api_key=key,
+                    api_base=base_override or override["base_url"],
+                    params={},
+                )
+
+        key = default_api_key or os.getenv(_ENV_API_KEY)
+        configured_base = os.getenv(_ENV_BASE_URL) or self.base_url
+        if base_override:
+            api_base = base_override
+        elif configured_base:
+            api_base = configured_base
+        elif "/" in model:
+            api_base = None  # provider-prefixed: litellm routes natively
+        else:
+            raise ConfigError(
+                f"No model endpoint configured for {model!r}: set [model] base_url in "
+                f".agentenv/config.toml or {_ENV_BASE_URL}, or use a provider-prefixed "
+                "model name (e.g. 'openai/gpt-4o') for native routing."
+            )
+        # The configured key is scoped to the configured endpoint (and native routing):
+        # a base_override pointing elsewhere must not inherit it, or a caller-supplied
+        # URL would receive the configured proxy's credential.
+        if key is None and (api_base is None or api_base == configured_base):
+            key = self._resolved_api_key(secret_resolver)
+        return ModelCallConfig(api_key=key, api_base=api_base, params=dict(self.params))

agent_env/config/paths.py

@@ -0,0 +1,25 @@
+"""Where agent-env keeps per-user files outside any project."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_APP_DIR = "agent-env"
+
+
+def state_root() -> Path:
+    """The per-user state root: ``$XDG_STATE_HOME/agent-env`` when that is an absolute path,
+    else ``%LOCALAPPDATA%\\agent-env`` on Windows, else ``~/.local/state/agent-env``.
+
+    A path only; nothing is created. A relative ``$XDG_STATE_HOME`` is ignored, as the XDG
+    Base Directory spec requires.
+    """
+    xdg = os.environ.get("XDG_STATE_HOME", "")
+    if os.path.isabs(xdg):
+        return Path(xdg) / _APP_DIR
+    local_app_data = os.environ.get("LOCALAPPDATA", "")
+    if sys.platform == "win32" and os.path.isabs(local_app_data):
+        return Path(local_app_data) / _APP_DIR
+    return Path.home() / ".local" / "state" / _APP_DIR

agent_env/config/plugin_tables.py

@@ -0,0 +1,101 @@
+"""A plugin's own settings: its ``[plugins.<distribution name>]`` table.
+
+Internal: the public reader is ``agent_env.plugins.settings``. ``config show`` and ``config explain``
+find a table with the same lookup, so the report and the plugin agree about which table it reads.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib.metadata import distributions
+from typing import Any, Optional
+
+from packaging.utils import canonicalize_name
+
+from agent_env.config import loader as config_loader
+from agent_env.config import runtime
+from agent_env.config.errors import ConfigError
+
+TABLE = "plugins"
+_BARE_KEY = re.compile(r"[A-Za-z0-9_-]+")
+
+
+@dataclass(frozen=True)
+class Installed:
+    """An installed distribution: its version, whether it is agent-env itself, and whether it is a
+    plugin, which is any other distribution that declares an ``agent_env.*`` entry point."""
+
+    version: str
+    plugin: bool
+    core: bool = False
+
+
+def spellings(table: Mapping[str, Any]) -> dict[str, list[str]]:
+    """Each canonical distribution name in ``[plugins]``, and the keys that spell it, in file order."""
+    found: dict[str, list[str]] = {}
+    for key in table:
+        found.setdefault(canonicalize_name(key), []).append(key)
+    return found
+
+
+def where(key: str) -> str:
+    """The table as written in TOML, a dotted name quoted so it does not read as nested."""
+    return f"[{TABLE}.{toml_key(key)}]"
+
+
+def toml_key(key: str) -> str:
+    """A key as TOML writes it: bare where it can be, quoted otherwise."""
+    return key if _BARE_KEY.fullmatch(key) else _quoted(key)
+
+
+def _quoted(key: str) -> str:
+    return '"' + key.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def duplicate(name: str, keys: list[str]) -> str:
+    tables = ", ".join(where(k) for k in keys)
+    return f"config.toml sets {name}'s settings more than once, as {tables}; keep one"
+
+
+def installed() -> dict[str, Installed]:
+    """Every installed distribution, by canonical name. One whose metadata cannot be read is left out."""
+    found: dict[str, Installed] = {}
+    with suppress(Exception):
+        for dist in distributions():
+            try:
+                name = dist.name
+                if name:
+                    core = canonicalize_name(name) == config_loader.DISTRIBUTION
+                    plugin = not core and any(ep.group.startswith("agent_env.") for ep in dist.entry_points)
+                    found.setdefault(canonicalize_name(name), Installed(dist.version or "", plugin, core))
+            except Exception:
+                continue
+    return found
+
+
+def settings(name: str, *, config: Optional[runtime.Config] = None) -> dict[str, Any]:
+    """The plugin ``name``'s own settings: its ``[plugins.<name>]`` table, ``{}`` when there is none.
+
+    ``name`` is the plugin's distribution name. Keys are matched by canonical name (PEP 503), so
+    ``[plugins.agentenv_browser]`` is ``agentenv-browser``'s table. ``env:`` and ``secret:``
+    references are resolved, as in every table agent-env reads. Reads ``config``'s document
+    (default: the process Config) on every call, so call it where the value is used, not at import.
+    Raises ``agent_env.config.ConfigError`` when ``[plugins]`` or the table is not a table, when two
+    keys name the same distribution, or when a reference without a default cannot be resolved.
+    """
+    config = config or runtime.get_config()
+    wanted = canonicalize_name(name)
+    keys = spellings(config.section(TABLE)).get(wanted, [])
+    if not keys:
+        return {}
+    if len(keys) > 1:
+        raise ConfigError(duplicate(wanted, keys))
+    try:
+        return config_loader.interpolate(
+            config.section(TABLE, keys[0]), secret_resolver=lambda key: config.get_secret_store().get(key)
+        )
+    except ConfigError as e:
+        raise ConfigError(f"{where(keys[0])}: {e}") from e

agent_env/config/provenance.py

@@ -0,0 +1,134 @@
+"""Where a resolved config value came from, and how to say it in one phrase.
+
+The resolvers in ``runtime`` compute a value and, on the traced path, the ordered list of
+layers that could have supplied it. Reporting reuses that list rather than re-deriving the
+precedence rule, so the two can never drift.
+
+Display lives here too, for the same reason: a winning layer and a shadowed one are the
+same kind of thing said at different lengths, so they share one renderer instead of each
+consumer growing its own.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Optional
+
+LayerKind = Literal["env", "file", "default", "installed"]
+
+KIND_ENV: LayerKind = "env"
+KIND_FILE: LayerKind = "file"
+KIND_DEFAULT: LayerKind = "default"
+# Set on the Config itself by `configure()`, above the file and below the environment.
+KIND_INSTALLED: LayerKind = "installed"
+
+
+def class_name(impl: Any) -> Optional[str]:
+    """The class alone — ``S3ObjectStore``, not the dotted path."""
+    return impl.rpartition(":")[2] if isinstance(impl, str) else None
+
+
+def lines(value: Any, *, seam: bool = True) -> list[str]:
+    """A config node in full: its class and scalars first, then everything nested, indented.
+
+    Nothing is elided. `config show` is a diagnostic, so a summary that hid a nested table
+    behind its key names hid the values an operator ran the command to read.
+
+    ``seam=False`` shows a table exactly as written: a plugin's own table gives ``impl`` and
+    ``config`` no meaning agent-env knows, so neither is read as a class and its settings.
+    """
+    if isinstance(value, list):
+        return [""] + ([line for item in value for line in _entry(item, seam)] or ["(empty)"])
+    if not isinstance(value, dict):
+        return ["(unset)" if value is None else _scalar(value)]
+    impl = class_name(value.get("impl")) if seam else None
+    if not impl:
+        return [_scalars(value)] + _nested(value, seam)
+    # An impl's `config` reads at the same level as the class it configures; anything else
+    # beside them is a key at the wrong level, which is the thing worth seeing. `config`
+    # wins a collision, because that is the one the reader takes.
+    config = value.get("config")
+    hoisted = config if isinstance(config, dict) else {}
+    # a `config` that is not a table is an ordinary key, and hiding it would elide it
+    skip = ("impl", "config") if hoisted else ("impl",)
+    table = {**{k: v for k, v in value.items() if k not in skip}, **hoisted}
+    return ["  ".join(filter(None, [_scalar(impl), _scalars(table)]))] + _nested(table, seam)
+
+
+def headline(value: Any, *, seam: bool = True) -> str:
+    """What a config node says at shadowed length: the class it names, else the keys it sets."""
+    if isinstance(value, dict):
+        impl = class_name(value.get("impl")) if seam else None
+        return (_scalar(impl) if impl else "") or _scalars(value) or ", ".join(value) or "(unset)"
+    return "(unset)" if value is None else _scalar(value)
+
+
+def _scalar(value: Any) -> str:
+    """A value on one physical line: TOML strings may carry newlines, the layout may not."""
+    return str(value).replace("\\", "\\\\").replace("\n", "\\n").replace("\r", "\\r")
+
+
+def _scalars(table: dict) -> str:
+    return "  ".join(f"{k}={_scalar(v)}" for k, v in table.items()
+                     if not isinstance(v, (dict, list)))
+
+
+def _nested(table: dict, seam: bool) -> list[str]:
+    """Each table or list under `table`, beneath its own heading."""
+    out: list[str] = []
+    for key, value in table.items():
+        if isinstance(value, list):
+            out.append(f"{key}:")
+            out += [f"  {line}" for item in value for line in _entry(item, seam)] or ["  (empty)"]
+        elif isinstance(value, dict):
+            out.append(f"{key}:")
+            out += [f"  {row}" for row in _rows(value, seam)] or ["  (empty)"]
+    return out
+
+
+def _rows(table: dict, seam: bool) -> list[str]:
+    """One entry per line: `name=value` for a scalar, else the node's own lines under it."""
+    out: list[str] = []
+    for name, node in table.items():
+        if not isinstance(node, (dict, list)):
+            out.append(f"{name}={_scalar(node)}")
+            continue
+        body = [line for line in lines(node, seam=seam) if line]
+        # a one-key table inlines fine; a one-element list would read as a scalar
+        if len(body) == 1 and not isinstance(node, list):
+            out.append(f"{name}  {body[0]}")
+        else:
+            out.append(f"{name}:")
+            out += [f"  {line}" for line in body]
+    return out
+
+
+def _entry(item: Any, seam: bool) -> list[str]:
+    """One list entry, as its own block: continuation lines indent under the first."""
+    if not isinstance(item, (dict, list)):
+        return [_scalar(item)]
+    body = [line for line in lines(item, seam=seam) if line]
+    return body[:1] + [f"  {line}" for line in body[1:]]
+
+
+@dataclass(frozen=True)
+class Layer:
+    """One candidate source for a value, resolved or not."""
+
+    kind: LayerKind
+    where: str
+    raw: Any = None
+    error: Optional[str] = None
+
+    def summary(self) -> str:
+        """The candidate at shadowed length: what was written, not what it became."""
+        return f"(unreadable: {self.error})" if self.error is not None else headline(self.raw)
+
+
+@dataclass(frozen=True)
+class Traced:
+    """A resolved value plus the layer that won and the ones it beat, highest priority first."""
+
+    value: Any
+    winner: Layer
+    shadowed: tuple[Layer, ...] = ()