Coverage for src/governed_harness/agents/environment.py: 96%
43 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""The environment an agent provider receives (``passEnv`` and ``env``, since 2.0).
3The process runner gives every command only ``PATH``, ``HOME``, ``SYSTEMROOT``, ``TMPDIR``,
4``TEMP``, ``LANG`` and ``LC_ALL``: an agent CLI did not receive its API key, a proxy or a
5certificate bundle, and the adapter template of the external-agents guide failed with
6``KeyError: 'AGENT_COMMAND'``. A provider now declares what it needs:
8* ``passEnv``: names of variables of the harness's environment passed as they are (a variable
9 that is not set is not passed);
10* ``env``: variables set for the provider, as a literal value or ``{fromEnv: NAME}`` (the value
11 of ``NAME`` in the harness's environment; a missing ``NAME`` stops IMPLEMENTATION before the
12 provider starts, instead of running the agent without its credentials).
14Only the names are recorded as evidence. Every value that comes from the environment is a
15secret literal of the artifact store: it is redacted from every stored artifact and from the
16agent's summary.
17"""
19from __future__ import annotations
21import os
22from collections.abc import Iterable, Mapping
23from dataclasses import dataclass, field
25from governed_harness.configuration.models import (
26 AgentProviderConfiguration,
27 ProjectConfiguration,
28 ProviderEnvReference,
29)
32@dataclass(frozen=True)
33class ProviderEnvironment:
34 allowed: tuple[str, ...] = ()
35 """Names the process may receive (``passEnv`` and the keys of ``env``)."""
36 values: dict[str, str] = field(default_factory=dict)
37 """Values set from ``env`` (literals and resolved ``fromEnv`` references)."""
38 missing: tuple[str, ...] = ()
39 """``fromEnv`` variables that are not set in the harness's environment."""
40 passed: tuple[str, ...] = ()
41 """``passEnv`` names that were set and are passed."""
43 def evidence(self) -> dict[str, list[str]]:
44 """Names only, never values."""
45 return {
46 "passEnv": list(self.passed),
47 "env": sorted(self.values),
48 "missing": list(self.missing),
49 }
52def provider_environment(
53 config: AgentProviderConfiguration, source: Mapping[str, str] | None = None
54) -> ProviderEnvironment:
55 environ = os.environ if source is None else source
56 pass_env = tuple(config.pass_env or ())
57 values: dict[str, str] = {}
58 missing: list[str] = []
59 for name, value in sorted((config.env or {}).items()):
60 if isinstance(value, ProviderEnvReference): 60 ↛ 66line 60 didn't jump to line 66 because the condition on line 60 was always true
61 if value.from_env not in environ:
62 missing.append(value.from_env)
63 continue
64 values[name] = environ[value.from_env]
65 else:
66 values[name] = value
67 return ProviderEnvironment(
68 allowed=tuple(dict.fromkeys((*pass_env, *sorted(values)))),
69 values=values,
70 missing=tuple(missing),
71 passed=tuple(name for name in pass_env if name in environ),
72 )
75def secret_values(
76 project: ProjectConfiguration, source: Mapping[str, str] | None = None
77) -> tuple[bytes, ...]:
78 """The values of every configured provider and project validator that come from the
79 environment (``passEnv`` and ``fromEnv``), and of the API tokens (``api.tokenEnv`` and
80 ``api.users[].tokenEnv``), to be redacted from the artifacts."""
81 environ = os.environ if source is None else source
82 names: list[str] = []
83 for config in project.agent_providers.values():
84 names.extend(config.pass_env or ())
85 names.extend(
86 value.from_env
87 for value in (config.env or {}).values()
88 if isinstance(value, ProviderEnvReference)
89 )
90 for validator in project.toolchain_settings.validators or ():
91 names.extend(validator.pass_env or ())
92 if project.api is not None:
93 # The API tokens (#18): redacted should an agent or a validator ever echo one.
94 names.extend(project.api.token_env_names)
95 return _encoded(environ[name] for name in dict.fromkeys(names) if name in environ)
98def _encoded(values: Iterable[str]) -> tuple[bytes, ...]:
99 return tuple(value.encode("utf-8") for value in values if value)