techtree 0.1.0__py3-none-any.whl

techtree/verifiers/config.py

@@ -0,0 +1,365 @@
+"""The only Verifiers configuration Techtree may emit. Spec section 6.7.
+
+This module is an allow-list, and the allow-list is the control. Verifiers has
+a large and growing set of knobs; a Campaign that could reach any of them could
+introduce a second difference between baseline and candidate without anyone
+being able to name it afterwards. Every model here forbids extra keys, so a
+knob Techtree has not deliberately modelled is unrepresentable rather than
+merely discouraged.
+
+Several fields are typed as literals rather than validated at runtime, because
+"the value is wrong" and "the value cannot be spelled" are different guarantees:
+
+``push: Literal[False]``
+    ``EvalConfig.push`` defaults to **true** upstream and uploads the complete
+    Episode — prompts and subject replies included — to the Prime platform
+    (``docs/verifiers-eval.md``, finding E1). A config that merely forgets to
+    set it exfiltrates the participant's trajectories.
+``rich: Literal[None]``
+    The dashboard is the whole output when it is on; a captured child needs log
+    lines. Upstream's ``rich`` is a table, not a flag, and **null is the only
+    spelling that turns the dashboard off**. Measured against the pinned build:
+    an omitted key resolves to ``{"show_logs": false}``, which is the dashboard
+    on *and* the log lines suppressed — the exact failure this lock-down
+    exists to prevent. So the danger here is a key that is missing, not a key
+    set to true, and :func:`emitted_document` writes this one null explicitly
+    while every other unset optional stays absent.
+``shuffle: Literal[False]`` and ``num_rollouts: Literal[1]``
+    Decisions document 0001. There is no seed anywhere in the protocol, so a
+    shuffled run could not be reproduced by anyone.
+``use_bundled_skill: Literal[False]``
+    A bundled skill catalogue is an uncontrolled second difference.
+
+``disabled_tools`` is absent by construction. The native Hermes harness accepts
+it at config time and then refuses it in the middle of a run, after Docker has
+been provisioned (``docs/verifiers-eval.md``, finding E3), so the only safe
+place to reject it is here.
+
+The Docker table carries ``allow`` and ``block``, which spec section 6.7 does
+not model. Upstream's default egress policy is unrestricted, so without them a
+Campaign declaring ``network_policy: "restricted"`` would compile to a
+container with open network access.
+
+The emitted document is **JSON**, and that is a safety property rather than a
+taste. TOML has no null literal, so a TOML document cannot say "no dashboard"
+at all — it can only leave ``rich`` out, which is the dangerous value. The
+engine reads either format and picks its parser from the file extension, so
+the configuration Techtree writes is named ``.json`` and every locked-down
+setting stays expressible only as its safe value, in the file, where the run's
+own inputs record it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Final, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from techtree.errors import ValidationError
+from techtree.models.campaign import CREDENTIAL_ENV_PATTERN
+
+__all__ = [
+    "ALLOWED_CLIENT_HEADERS",
+    "EVAL_CONFIG_INVALID",
+    "IMAGE_DIGEST_PATTERN",
+    "OPEN_BLOCK",
+    "OPEN_NETWORK",
+    "RESTRICTED_BLOCK",
+    "RESTRICTED_NETWORK",
+    "DockerRuntimeToml",
+    "EnvToml",
+    "EvalClientToml",
+    "EvalToml",
+    "HermesHarnessToml",
+    "SamplingToml",
+    "SubjectAgentToml",
+    "TasksetToml",
+    "TimeoutToml",
+    "config_to_json_bytes",
+    "egress_for",
+    "emitted_document",
+]
+
+#: Stable error code. Spec section 6.7.
+EVAL_CONFIG_INVALID: Final = "eval_config_invalid"
+
+#: Headers Techtree is allowed to declare on the evaluation client. Empty: the
+#: only supported profile routes through the pinned client's own resolution,
+#: and a header Techtree invents is a routing decision nobody reviewed. The
+#: engine may still *add* headers of its own when it resolves the config
+#: (``docs/verifiers-eval.md``); that is upstream's business, not Techtree's.
+ALLOWED_CLIENT_HEADERS: Final[frozenset[str]] = frozenset()
+
+#: Framework-only egress: the interception endpoint and nothing else, which is
+#: what a restricted subject runtime means. Upstream normalizes an empty
+#: allow-list to exactly this pair, so Techtree declares the normalized form
+#: rather than the shorthand — otherwise the configuration Techtree compiled
+#: and the configuration the engine resolved would disagree at ``block`` on
+#: every restricted run.
+RESTRICTED_NETWORK: Final[tuple[str, ...]] = ()
+RESTRICTED_BLOCK: Final[tuple[str, ...]] = ("*",)
+#: Unrestricted egress, upstream's own default spelling.
+OPEN_NETWORK: Final[tuple[str, ...]] = ("*",)
+OPEN_BLOCK: Final[tuple[str, ...]] = ()
+
+#: An OCI reference that names content rather than a moving tag.
+IMAGE_DIGEST_PATTERN: Final = r"@sha256:[0-9a-f]{64}$"
+
+_CREDENTIAL_ENV_RE: Final = re.compile(CREDENTIAL_ENV_PATTERN)
+_IMAGE_DIGEST_RE: Final = re.compile(IMAGE_DIGEST_PATTERN)
+
+#: The settings whose null the emitted document must state out loud, because
+#: leaving the key out would select something else. Only ``rich`` qualifies:
+#: every other optional in this module defaults to the same ``None`` upstream.
+_NULL_IS_THE_DECISION: Final[frozenset[str]] = frozenset({"rich"})
+
+
+class TomlModel(BaseModel):
+    """A frozen, extra-forbidden fragment of the emitted configuration."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", validate_default=True)
+
+
+class EvalClientToml(TomlModel):
+    """The OpenAI-compatible endpoint the evaluation runs against.
+
+    ``base_url`` is deliberately omitted for the supported profile. The pinned
+    client resolves a ``PRIME_API_KEY``-keyed endpoint from the environment and
+    the active Prime CLI configuration, and writing a URL here would freeze a
+    deployment detail into a run's inputs.
+    """
+
+    type: Literal["eval"] = "eval"
+    api_key_var: str
+    base_url: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _check_the_client_names_a_variable_and_no_headers(self) -> Self:
+        """Reject a credential value, and any header Techtree may not declare."""
+        if _CREDENTIAL_ENV_RE.fullmatch(self.api_key_var) is None:
+            raise ValueError(
+                "api_key_var must be an uppercase environment-variable name, "
+                "never a credential value"
+            )
+        unknown = sorted(set(self.headers) - ALLOWED_CLIENT_HEADERS)
+        if unknown:
+            raise ValueError(f"Techtree does not declare client headers; got {unknown}")
+        return self
+
+
+class SamplingToml(TomlModel):
+    """How the subject model is sampled."""
+
+    temperature: float = Field(ge=0.0, le=2.0)
+    max_tokens: int = Field(ge=1)
+
+
+class HermesHarnessToml(TomlModel):
+    """The pinned Hermes Agent harness and the skills inserted into it."""
+
+    id: Literal["hermes-agent"] = "hermes-agent"
+    version: str = Field(min_length=1)
+    use_bundled_skill: Literal[False] = False
+    skills: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_skill_paths_are_absolute_and_distinct(self) -> Self:
+        """Reject a relative or repeated skill path."""
+        for path in self.skills:
+            if not path.startswith("/"):
+                raise ValueError(
+                    f"skill paths are absolute run-owned paths; got {path!r}"
+                )
+        if len(set(self.skills)) != len(self.skills):
+            raise ValueError("a harness mounts each skill exactly once")
+        return self
+
+
+class DockerRuntimeToml(TomlModel):
+    """Where the subject agent executes."""
+
+    type: Literal["docker"] = "docker"
+    image: str = Field(min_length=1)
+    allow: list[str] = Field(default_factory=list)
+    block: list[str] = Field(default_factory=list)
+    cpu: float | None = Field(default=None, gt=0.0)
+    memory: float | None = Field(default=None, gt=0.0)
+
+    @property
+    def image_is_digest_pinned(self) -> bool:
+        """Whether the image reference names content rather than a tag."""
+        return _IMAGE_DIGEST_RE.search(self.image) is not None
+
+    @property
+    def network_is_restricted(self) -> bool:
+        """Whether egress is anything narrower than unrestricted."""
+        return list(self.allow) != list(OPEN_NETWORK) or bool(self.block)
+
+    @model_validator(mode="after")
+    def _check_the_egress_lists_are_not_both_concrete(self) -> Self:
+        """Reject the one egress combination upstream refuses outright."""
+        if self.allow and list(self.allow) != list(OPEN_NETWORK) and self.block:
+            raise ValueError(
+                "a concrete allow list and a block list are mutually exclusive"
+            )
+        return self
+
+
+class TimeoutToml(TomlModel):
+    """Per-rollout Verifiers lifecycle limits.
+
+    Every one of these defaults to ``None`` upstream, and ``None`` means "no
+    limit": the pinned build wraps each phase in ``asyncio.timeout(value)``, and
+    ``asyncio.timeout(None)`` is a no-op. A Campaign that declares
+    ``timeout_seconds`` and cannot reach this table has declared nothing, which
+    is the whole reason the table exists here (decisions document 0029, layer
+    A).
+    """
+
+    setup: float | None = Field(default=None, gt=0.0)
+    rollout: float | None = Field(default=None, gt=0.0)
+    finalize: float | None = Field(default=None, gt=0.0)
+    scoring: float | None = Field(default=None, gt=0.0)
+
+
+class SubjectAgentToml(TomlModel):
+    """The one seat v0.1 evaluates, named for the role it plays."""
+
+    harness: HermesHarnessToml
+    runtime: DockerRuntimeToml
+    max_turns: int | None = Field(default=None, ge=1)
+    max_input_tokens: int | None = Field(default=None, ge=1)
+    max_output_tokens: int | None = Field(default=None, ge=1)
+    max_total_tokens: int | None = Field(default=None, ge=1)
+    timeout: TimeoutToml = Field(default_factory=TimeoutToml)
+
+
+class TasksetToml(TomlModel):
+    """Which taskset the environment seeds from.
+
+    Only the identifier. Every other taskset field on the pinned reference
+    Taskset is a default Techtree does not vary, and a field Techtree does not
+    vary should not appear in a document a reader has to check.
+    """
+
+    id: str = Field(min_length=1)
+
+
+class EnvToml(TomlModel):
+    """The environment block: the taskset, the subject seat, and the bound.
+
+    The seat is spelled ``subject`` because the reference package's ``Env``
+    declares a field of that name; Verifiers stamps the field name onto every
+    trace as ``agent.name`` (spec section 6.5). Against an environment without
+    that seat the whole configuration is rejected at parse time
+    (``docs/verifiers-eval.md``, finding E0).
+    """
+
+    taskset: TasksetToml
+    subject: SubjectAgentToml
+    max_concurrent_agents: int = Field(default=1, ge=1)
+
+
+class EvalToml(TomlModel):
+    """One resolved Techtree experiment as a Verifiers evaluation."""
+
+    model: str = Field(min_length=1)
+    client: EvalClientToml
+    sampling: SamplingToml
+    env: EnvToml
+    num_tasks: int = Field(ge=1)
+    num_rollouts: Literal[1] = 1
+    shuffle: Literal[False] = False
+    max_concurrent: int = Field(ge=1)
+    rich: Literal[None] = None
+    push: Literal[False] = False
+    output_dir: str = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _check_the_run_is_bounded_and_run_owned(self) -> Self:
+        """Reject a relative output directory or an unbounded episode fan-out."""
+        if not self.output_dir.startswith("/"):
+            raise ValueError(
+                "output_dir is an absolute run-owned path; a relative path "
+                "lands wherever the child happened to be started"
+            )
+        if self.env.max_concurrent_agents > self.max_concurrent:
+            raise ValueError(
+                "max_concurrent_agents cannot exceed max_concurrent; the "
+                "product is the number of live subject runs"
+            )
+        return self
+
+
+def egress_for(network_policy: str) -> tuple[list[str], list[str]]:
+    """Return the ``(allow, block)`` pair one Campaign network policy compiles to.
+
+    The Campaign speaks in intent — restricted or open — and upstream speaks in
+    two lists whose meaning depends on each other. This is the single place the
+    two vocabularies meet, and it emits the already-normalized form so nothing
+    downstream has to know that upstream would have rewritten the shorthand.
+    """
+    if network_policy == "restricted":
+        return list(RESTRICTED_NETWORK), list(RESTRICTED_BLOCK)
+    if network_policy == "open":
+        return list(OPEN_NETWORK), list(OPEN_BLOCK)
+    raise ValidationError(
+        f"{network_policy!r} is not a network policy Techtree can compile",
+        code=EVAL_CONFIG_INVALID,
+        details={"network_policy": network_policy},
+    )
+
+
+def emitted_document(config: EvalToml) -> dict[str, Any]:
+    """Return exactly the mapping Techtree writes for one configuration.
+
+    ``exclude_none`` is kept for every field but one, because for every other
+    optional here a null and an absence mean the same thing to the engine and
+    an absence says it more honestly. ``client.base_url`` is left out so the
+    pinned client resolves the endpoint itself; an unset token ceiling or
+    timeout phase is a limit the Campaign did not declare, and upstream's own
+    default for each is the same ``None`` it would have been written as. In
+    every one of those cases the document should say only what Techtree
+    actually decided.
+
+    ``rich`` is the exception, and it is why the omission is not simply
+    switched off wholesale: its null is the decision, and dropping the key
+    selects the opposite (see the module docstring). So it is kept, which is
+    safe precisely because :class:`EvalToml` can spell no other value for it.
+    """
+    document: dict[str, Any] = config.model_dump(mode="json")
+    return {
+        key: _without_nulls(value)
+        for key, value in document.items()
+        if value is not None or key in _NULL_IS_THE_DECISION
+    }
+
+
+def _without_nulls(value: Any) -> Any:
+    """Drop every unset optional from one nested value."""
+    if isinstance(value, dict):
+        return {
+            key: _without_nulls(inner)
+            for key, inner in value.items()
+            if inner is not None
+        }
+    return value
+
+
+def config_to_json_bytes(config: EvalToml) -> bytes:
+    """Serialize one configuration to deterministic JSON bytes.
+
+    Key order is declaration order, so the same configuration always produces
+    the same bytes. The engine chooses its parser from the file's extension,
+    so these bytes belong in a file named ``.json``.
+    """
+    try:
+        return json.dumps(emitted_document(config), indent=2).encode("utf-8") + b"\n"
+    except (TypeError, ValueError) as error:
+        raise ValidationError(
+            f"the compiled evaluation config is not serializable: {error}",
+            code=EVAL_CONFIG_INVALID,
+        ) from error

techtree/verifiers/credentials.py

@@ -0,0 +1,321 @@
+"""Whether the evaluation endpoint can authenticate. Spec section 6.9.
+
+Two rules shape everything in this module.
+
+*A secret is checked, never carried.* No function here returns a credential
+value, writes one, or puts one in an error message, a detail dictionary, or a
+log line. The only object that ever holds the value is the child process
+environment :func:`scrubbed_child_environment` builds, and that dictionary is
+handed straight to the child. :func:`redacted_environment` exists so that the
+same dictionary can be described in a diagnostic without being disclosed.
+
+*Evaluation auth is not host auth.* The credential this module diagnoses buys
+model tokens for the evaluated subject. It is unrelated to whatever the
+operator's own Hermes is authenticated with, and confusing the two produces the
+worst possible failure: a run that looks configured, provisions Docker, and
+then discovers thirty seconds later that nothing can answer. Spec sections 6.9
+and 6.18 keep them separate, and so does the wording of every message here.
+
+The pinned client resolves a ``PRIME_API_KEY``-named credential from the
+environment first and from the active Prime CLI configuration second, returning
+the literal string ``"EMPTY"`` when it finds neither
+(``docs/verifiers-eval.md``). A missing credential therefore does not fail at
+startup; it fails at the first model call, after the container is up. That is
+the whole reason this check runs before a child is launched.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Final, Literal
+
+from techtree.errors import AuthenticationError
+from techtree.models.base import NonEmptyString, ProtocolModel
+from techtree.models.campaign import ModelSpec
+from techtree.models.cli import NextAction
+from techtree.models.engine import EngineInstallation
+
+__all__ = [
+    "MODEL_CREDENTIALS_MISSING",
+    "PRIME_CONFIG_RELATIVE_PATH",
+    "PRIME_CREDENTIAL_ENV",
+    "PRIME_ENVIRONMENT",
+    "CredentialStatus",
+    "credential_status",
+    "redacted_environment",
+    "require_credentials",
+    "scrubbed_child_environment",
+]
+
+#: Stable error code. Spec section 6.9.
+MODEL_CREDENTIALS_MISSING: Final = "model_credentials_missing"
+
+#: The credential name the pinned client gives its own resolution to. Any other
+#: name is read from the environment and nowhere else.
+PRIME_CREDENTIAL_ENV: Final = "PRIME_API_KEY"
+
+#: Where the Prime CLI keeps its configuration, relative to ``HOME``.
+PRIME_CONFIG_RELATIVE_PATH: Final = (".prime", "config.json")
+
+#: Prime variables the pinned client reads when it resolves an endpoint. The
+#: key itself is not here: it is forwarded by name from the Campaign.
+PRIME_ENVIRONMENT: Final[tuple[str, ...]] = (
+    "PRIME_INFERENCE_URL",
+    "PRIME_TEAM_ID",
+)
+
+#: The only host variables a child inherits. ``PATH`` so ordinary system tools
+#: and the container runtime resolve, ``HOME`` because the Prime CLI
+#: configuration and package caches hang off it, ``TMPDIR`` so scratch files
+#: land where the host expects them.
+_BASE_ENVIRONMENT: Final[tuple[str, ...]] = ("PATH", "HOME", "TMPDIR")
+
+_PRIME_CONFIG_KEY: Final = "api_key"
+
+#: What the Prime CLI configuration under one ``HOME`` supplies.
+type _PrimeConfigState = Literal["usable", "signed_out", "malformed", "absent"]
+
+
+class CredentialStatus(ProtocolModel):
+    """Whether one model endpoint can authenticate, and from where.
+
+    ``detail`` is operator-facing prose. It names the variable and the place it
+    was looked for, never a value or a fragment of one.
+
+    ``malformed_prime_config`` is its own answer rather than another way of
+    saying "missing": a configuration file that cannot be read is a broken
+    store, and telling somebody who has signed in that they have not is the
+    kind of advice that sends them round the loop again.
+    """
+
+    provider: NonEmptyString
+    credential_env: NonEmptyString
+    available: bool
+    source: Literal["environment", "prime_config", "missing", "malformed_prime_config"]
+    detail: NonEmptyString
+
+
+def credential_status(
+    model: ModelSpec, *, environ: Mapping[str, str] | None = None
+) -> CredentialStatus:
+    """Report whether the declared credential can be resolved.
+
+    Presence only. The value is never read into a return, a log, or an error.
+
+    ``environ`` is the environment the question is asked *about*, which is not
+    always the one this process happens to have. A readiness check runs in an
+    operator's terminal but has to answer for the environment a detached run
+    would get, and a check that answered for its own terminal instead would be
+    able to say "ready" about a run that cannot authenticate.
+    """
+    source = os.environ if environ is None else environ
+    name = model.credential_env
+    if source.get(name):
+        return CredentialStatus(
+            provider=model.provider,
+            credential_env=name,
+            available=True,
+            source="environment",
+            detail=f"{name} is set in this environment.",
+        )
+
+    state = (
+        _prime_config_state(source.get("HOME"))
+        if name == PRIME_CREDENTIAL_ENV
+        else "absent"
+    )
+
+    if state == "usable":
+        return CredentialStatus(
+            provider=model.provider,
+            credential_env=name,
+            available=True,
+            source="prime_config",
+            detail=(
+                "the active Prime CLI configuration holds a key the pinned "
+                "evaluation client can use."
+            ),
+        )
+
+    if state == "malformed":
+        return CredentialStatus(
+            provider=model.provider,
+            credential_env=name,
+            available=False,
+            source="malformed_prime_config",
+            detail=(
+                "the Prime CLI configuration on this machine could not be read "
+                "as a configuration, so no key can be resolved from it. Signing "
+                "in again writes a fresh one."
+            ),
+        )
+
+    if state == "signed_out":
+        return CredentialStatus(
+            provider=model.provider,
+            credential_env=name,
+            available=False,
+            source="missing",
+            detail=(
+                "the Prime CLI configuration on this machine holds no key: this "
+                "machine is signed out, or the sign-in has been cleared. This "
+                "credential pays for the evaluated subject's model calls; it is "
+                "separate from whatever your own agent is signed in with."
+            ),
+        )
+
+    return CredentialStatus(
+        provider=model.provider,
+        credential_env=name,
+        available=False,
+        source="missing",
+        detail=(
+            f"no active Prime CLI configuration supplies {name}. This credential "
+            "pays for the evaluated subject's model calls; it is separate from "
+            "whatever your own agent is signed in with."
+        ),
+    )
+
+
+def require_credentials(model: ModelSpec) -> CredentialStatus:
+    """Return the status, or refuse to go further without a credential."""
+    status = credential_status(model)
+    if status.available:
+        return status
+    raise AuthenticationError(
+        f"the evaluation model endpoint has no credential: {status.detail}",
+        code=MODEL_CREDENTIALS_MISSING,
+        details={
+            "provider": model.provider,
+            "model_id": model.model_id,
+            "credential_env": model.credential_env,
+        },
+        next_actions=[
+            NextAction(
+                id="sign_in_to_prime",
+                label="Sign in to Prime, then start the run again",
+                reason=(
+                    "A PRIME_API_KEY-named credential resolves from the active "
+                    "Prime CLI configuration, which a run can read for itself."
+                ),
+                cli=["prime", "login"],
+                hermes_tool=None,
+                hermes_args=None,
+                requires_user_confirmation=True,
+            ),
+            NextAction(
+                id="export_evaluation_credential",
+                label=(f"Check how {model.credential_env} reaches a run"),
+                reason=(
+                    "Setting this credential in your own terminal is not "
+                    "enough: a run works in a separate background process that "
+                    "is not given your terminal's variables. It pays for the "
+                    "evaluated subject's model calls and is never stored."
+                ),
+                cli=["techtree", "doctor", "--for-evaluation"],
+                hermes_tool=None,
+                hermes_args=None,
+                requires_user_confirmation=False,
+            ),
+        ],
+    )
+
+
+def _prime_config_state(home: str | None) -> _PrimeConfigState:
+    """Report what the Prime CLI configuration under ``home`` supplies.
+
+    The file is opened, one key is tested for emptiness, and the value is
+    discarded. Nothing read here reaches a caller.
+
+    Three not-usable answers are distinguished because they need three
+    different sentences. No file is somebody who has not signed in; a file with
+    no key is somebody whose sign-in has gone away; a file that will not parse
+    is a broken store, and no amount of signing in explains itself if it is
+    described as either of the other two.
+    """
+    if not home:
+        return "absent"
+    path = Path(home).joinpath(*PRIME_CONFIG_RELATIVE_PATH)
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return "absent"
+    try:
+        document = json.loads(raw)
+    except ValueError:
+        return "malformed"
+    if not isinstance(document, dict):
+        return "malformed"
+    value = document.get(_PRIME_CONFIG_KEY)
+    if value is None or (isinstance(value, str) and not value.strip()):
+        return "signed_out"
+    return "usable" if isinstance(value, str) else "malformed"
+
+
+def scrubbed_child_environment(
+    *,
+    model: ModelSpec,
+    engine: EngineInstallation,
+    extra: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Build a Verifiers child's environment from a narrow allow-list.
+
+    The host environment is not copied. A developer machine carries cloud
+    credentials, provider keys for other services, and shell configuration that
+    would change how the subject behaves, and none of it belongs inside an
+    experiment that claims only one thing differed.
+
+    The engine's own ``bin`` directory is prepended to ``PATH`` so the child
+    resolves the tools the pinned engine ships before anything the operator
+    happens to have installed, for the same reason the engine invokes its own
+    console scripts by absolute path.
+    """
+    environment = {
+        name: os.environ[name] for name in _BASE_ENVIRONMENT if name in os.environ
+    }
+    environment["PATH"] = _engine_first_path(engine, environment.get("PATH"))
+
+    credential = os.environ.get(model.credential_env)
+    if credential:
+        environment[model.credential_env] = credential
+
+    for name in PRIME_ENVIRONMENT:
+        value = os.environ.get(name)
+        if value:
+            environment[name] = value
+
+    for name, value in (extra or {}).items():
+        environment[name] = value
+
+    return environment
+
+
+def _engine_first_path(engine: EngineInstallation, inherited: str | None) -> str:
+    """Return a ``PATH`` that starts with the engine's own executables."""
+    engine_bin = str(Path(engine.python_executable).parent)
+    if not inherited:
+        return engine_bin
+    entries = [engine_bin, *(part for part in inherited.split(os.pathsep) if part)]
+    return os.pathsep.join(dict.fromkeys(entries))
+
+
+def redacted_environment(
+    environment: Mapping[str, str], *, secret_names: Iterable[str]
+) -> dict[str, str]:
+    """Describe a child environment safely enough to put in a diagnostic.
+
+    Named secrets are replaced by their length. That distinguishes an unset
+    variable from an empty one from a truncated paste, which is the whole of
+    what an operator needs, and discloses nothing usable. Everything else — the
+    ``PATH`` the child searched, the ``HOME`` it read configuration from — is
+    shown, because hiding it would make the diagnostic useless without making
+    anything safer.
+    """
+    secrets = set(secret_names)
+    return {
+        name: (f"<set, {len(value)} characters>" if name in secrets else value)
+        for name, value in environment.items()
+    }