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

1"""The environment an agent provider receives (``passEnv`` and ``env``, since 2.0). 

2 

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: 

7 

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). 

13 

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""" 

18 

19from __future__ import annotations 

20 

21import os 

22from collections.abc import Iterable, Mapping 

23from dataclasses import dataclass, field 

24 

25from governed_harness.configuration.models import ( 

26 AgentProviderConfiguration, 

27 ProjectConfiguration, 

28 ProviderEnvReference, 

29) 

30 

31 

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.""" 

42 

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 } 

50 

51 

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 ) 

73 

74 

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) 

96 

97 

98def _encoded(values: Iterable[str]) -> tuple[bytes, ...]: 

99 return tuple(value.encode("utf-8") for value in values if value)