Coverage for src/ai_jury/config.py: 99%
536 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
1"""Configuration loading for the jury.
3Config is TOML (see ``jury.toml``). The loader is tolerant: a missing config
4file falls back to a sensible built-in default so the tool runs out of the box.
5"""
7from __future__ import annotations
9import os
10import tomllib
11from dataclasses import dataclass, field
12from dataclasses import fields as dataclass_fields
13from pathlib import Path
14from urllib.parse import urlsplit
16from .ci import fail_on_error
17from .redaction import ENV_VAR_NAME_RULE, redact, safe_env_var_name
19# Hosts that are safe to reach over plaintext http and never an SSRF target.
20_LOOPBACK_HOSTS = ("localhost", "127.0.0.1", "::1", "[::1]")
22# Upper bound on a config/policy TOML file (issue #316/L-5). A real config is a
23# few KB; refuse a multi-MB / pathological file so `tomllib` can't be driven to
24# exhaust memory (the file may be attacker-supplied when jury runs from a PR
25# checkout). Mirrors the cache's _MAX_CACHE_BYTES.
26_MAX_CONFIG_BYTES = 4 * 1024 * 1024
29def _read_toml_bounded(path: Path) -> dict:
30 """Parse a TOML file with a size cap (issue #316/L-5)."""
31 with path.open("rb") as fh:
32 raw = fh.read(_MAX_CONFIG_BYTES + 1)
33 if len(raw) > _MAX_CONFIG_BYTES:
34 raise ConfigError(f"config file '{path}' exceeds the {_MAX_CONFIG_BYTES}-byte limit.")
35 try:
36 text = raw.decode("utf-8")
37 except UnicodeDecodeError:
38 # TOML is UTF-8 by spec; surface a clean error instead of a raw
39 # UnicodeDecodeError (review of #316 — the prior tomllib.load crashed the
40 # same way on bad bytes; now it's a ConfigError).
41 raise ConfigError(f"config file '{path}' is not valid UTF-8.") from None
42 try:
43 return tomllib.loads(text)
44 except tomllib.TOMLDecodeError as exc:
45 raise ConfigError(f"invalid TOML in config file '{path}': {redact(str(exc))[0]}") from None
48def _is_relative_path_command(command: str) -> bool:
49 """True for a relative command that contains a path separator (#293/F-6).
51 A bare name (``codex``) is fine — it is resolved on PATH. An absolute path
52 (``/usr/bin/codex``) is fine — it is explicit. A relative path with a
53 separator (``./tools/codex``, ``bin/agy``) is rejected because it resolves a
54 binary from an attacker-influenceable working-directory-relative location.
55 """
56 cmd_str = str(command or "")
57 has_sep = "/" in cmd_str or "\\" in cmd_str or (os.altsep is not None and os.altsep in cmd_str)
58 return has_sep and not Path(cmd_str).is_absolute()
61# Env opt-in for a non-loopback local endpoint. It lives in the environment, NOT
62# in jury.toml, on purpose (review of #291): the threat model is an
63# attacker-controlled config, so the opt-in must sit OUTSIDE the surface the
64# attacker controls. Without it, a non-loopback host (incl. cloud-metadata
65# 169.254.169.254) is a hard error so an attacker config cannot drive an
66# SSRF POST to an internal address — matching the default-secure F-1 posture.
67_ALLOW_REMOTE_ENDPOINT_ENV = "JURY_ALLOW_REMOTE_ENDPOINT"
69# Opt-in strict mode (issue #296): when set, every agent ``command`` must be an
70# absolute path — rejecting even a bare name, whose PATH resolution an attacker
71# who controls the CI runner's PATH could hijack with a shim. Off by default so
72# the convenient bare-name (``claude``) keeps working for local use.
73_REQUIRE_ABSOLUTE_COMMAND_ENV = "JURY_REQUIRE_ABSOLUTE_COMMAND"
76def _endpoint_issues(endpoint: str, label: str) -> tuple[list[str], list[str]]:
77 """Validate a local-agent ``endpoint`` URL (issue #291, SSRF defense).
79 Returns ``(errors, warnings)``. A non-``http``/``https`` scheme is a hard
80 error (blocks ``file://``/``ftp://`` and other SSRF primitives). A non-loopback
81 host is also a hard error UNLESS the operator opts in via the
82 ``JURY_ALLOW_REMOTE_ENDPOINT`` environment variable (a remote model server is
83 a legitimate but riskier choice the attacker-controlled config must not be
84 able to select on its own); when opted in it degrades to a warning, plus a
85 cleartext warning for plaintext ``http``.
86 """
87 errors: list[str] = []
88 warnings: list[str] = []
89 if not isinstance(endpoint, str): 89 ↛ 90line 89 didn't jump to line 90 because the condition on line 89 was never true
90 errors.append(f"agent '{label}' endpoint must be a string (got {endpoint!r}).")
91 return errors, warnings
92 # `urlsplit` raises ValueError on a malformed URL (e.g. `http://[::1`,
93 # "Invalid IPv6 URL"). Convert that to a hard config error (issue #315) so
94 # `validate_config` reports it cleanly instead of crashing with a stack trace
95 # — the malformed string is, by definition, not a usable endpoint.
96 try:
97 parsed = urlsplit(endpoint)
98 parsed.hostname # noqa: B018 - also raises ValueError on a bad IPv6 host
99 except (ValueError, TypeError, AttributeError):
100 errors.append(f"agent '{label}' endpoint '{endpoint}' is not a valid URL.")
101 return errors, warnings
102 scheme = (parsed.scheme or "").lower()
103 if scheme not in ("http", "https"):
104 errors.append(
105 f"agent '{label}' endpoint scheme '{parsed.scheme or '(none)'}' is "
106 f"not allowed; use http or https."
107 )
108 return errors, warnings
109 host = (parsed.hostname or "").lower()
110 if host in _LOOPBACK_HOSTS:
111 return errors, warnings
112 if not os.environ.get(_ALLOW_REMOTE_ENDPOINT_ENV):
113 errors.append(
114 f"agent '{label}' endpoint host '{host or '(none)'}' is not loopback; "
115 f"a non-loopback model server (incl. internal/metadata addresses) is "
116 f"refused by default. Set {_ALLOW_REMOTE_ENDPOINT_ENV}=1 in the "
117 f"environment to allow a trusted remote endpoint."
118 )
119 return errors, warnings
120 warnings.append(
121 f"agent '{label}' endpoint host '{host or '(none)'}' is not loopback; "
122 f"the (redacted) diff is sent to a remote server — ensure it is trusted "
123 f"and not an internal/metadata address."
124 )
125 if scheme == "http":
126 warnings.append(
127 f"agent '{label}' endpoint uses plaintext http to a non-loopback "
128 f"host; prefer https so the prompt is not sent in cleartext."
129 )
130 return errors, warnings
133#: Distinct vendors a run must have heard from before it may call itself a
134#: cross-vendor consensus (issue #682). The shipped default of 2 FAILS CLOSED:
135#: before it, a three-vendor panel that collapsed to one exited 0 with a verdict
136#: and nothing said so (#635). Lower it, or set 0, to opt out — see
137#: ``[jury.ci] min_vendors`` and ``--no-min-vendors``.
138DEFAULT_MIN_VENDORS = 2
141def _non_negative_int(value, default: int) -> int:
142 """A non-negative int from raw config data, falling back to ``default``.
144 ``validate_config`` refuses a malformed or negative value (docs audit
145 2026-09-29), so a run started from ``jury`` never reaches the fallback. It is
146 for a Python caller that materialises without validating: there, a
147 malformed value falls back to the default rather than raising, because the
148 default is the *safe* direction for a fail-closed gate. A negative value
149 falls back too — clamping it to ``0`` used to turn ``min_vendors = -1``
150 into "guard off", the one direction a fail-closed gate must never drift.
151 """
152 try:
153 number = int(value)
154 except (TypeError, ValueError):
155 return default
156 return number if number >= 0 else default
159DEFAULT_CONFIG: dict = {
160 "jury": {
161 "rounds": 2,
162 "chair": "claude",
163 "timeout": 600,
164 "parallel": True,
165 "verify": True,
166 "ci": {
167 "fail_on": ["critical", "major"],
168 "ignore_unverified": True,
169 "min_vendors": DEFAULT_MIN_VENDORS,
170 },
171 "context": {"mode": "diff-only", "redact_secrets": True},
172 },
173 # Execution controls (issue #30) are optional and conservative by default:
174 # no overall/per-phase budget and zero retries, so out-of-the-box behaviour
175 # is unchanged. They live under [jury] and are documented in
176 # docs/configuration.md.
177 "agent": [
178 {
179 "name": "claude",
180 "vendor": "anthropic",
181 "command": "claude",
182 # The reviewer only needs its prompt, which already carries the diff,
183 # so it gets no tools at all: `--tools ""` leaves no built-in tool
184 # available, the deny list names every write, shell, read, network and
185 # subagent tool as a second layer, `--strict-mcp-config` with no
186 # `--mcp-config` keeps the user's own MCP servers out, `--safe-mode`
187 # drops CLAUDE.md, hooks, skills and plugins (a PR checkout's project
188 # settings included), `--no-session-persistence` writes no transcript
189 # of the untrusted diff to ~/.claude/projects, and `dontAsk` denies
190 # a tool call instead of prompting (so `-p` cannot hang) or approving
191 # it. `privilege.enforce_read_only` injects the same lockdown into a
192 # seat configured without it; `privilege._CLAUDE_DENIED_TOOLS` is the
193 # list below, and a test keeps the two equal.
194 "extra_args": [
195 "--output-format",
196 "text",
197 "--tools",
198 "",
199 "--disallowed-tools",
200 "Edit,Write,NotebookEdit,Bash,Read,Grep,Glob,WebFetch,WebSearch,Task,Agent",
201 "--strict-mcp-config",
202 "--safe-mode",
203 "--no-session-persistence",
204 "--permission-mode",
205 "dontAsk",
206 ],
207 },
208 {
209 "name": "codex",
210 "vendor": "openai",
211 "command": "codex",
212 # `codex exec` reads the prompt from stdin (see CodexAdapter) and only
213 # needs to READ it and print a review — the diff is fetched by the
214 # jury process (`gh`), not the agent. So the secure default is a
215 # read-only sandbox (issue #100); widen it (e.g. `-s workspace-write`
216 # or `danger-full-access`) only if your workflow truly needs it.
217 "extra_args": ["-s", "read-only"],
218 },
219 # No `agy` here: see AGY_AGENT below. A run with no jury.toml never
220 # spawns it; claude + codex are still two vendors, so the shipped
221 # DEFAULT_MIN_VENDORS guard is met by the default panel alone.
222 ],
223}
226#: The Antigravity seat, for a config that asks for it by name. It is NOT in
227#: :data:`DEFAULT_CONFIG`'s panel, because agy cannot be confined for a reviewer
228#: of untrusted diffs: `--dangerously-skip-permissions` auto-approves its tools
229#: (without it, headless agy denies the first command a review tries and returns
230#: no review), and `--sandbox` (issue #100) restricts its terminal but, measured
231#: on agy 1.2.9, did not stop it reading or writing files outside its working
232#: directory or reaching the network. agy offers no flag that removes its tools.
233#: `jury init --agents agy` and `jury run-agent --agent agy` still use this entry;
234#: a panel that seats it draws a least-privilege warning (`--strict` fails).
235AGY_AGENT: dict = {
236 "name": "agy",
237 "vendor": "google",
238 "command": "agy",
239 "extra_args": ["--dangerously-skip-permissions", "--sandbox"],
240}
242#: Why agy is opt-in, in the words every "no reviewer" message and `jury init`
243#: use, so they cannot drift apart.
244AGY_OPT_IN_NOTE = (
245 "agy is not in the default panel because it cannot be confined for untrusted "
246 "diffs (it reads, writes and reaches the network even with --sandbox); add it "
247 "explicitly in jury.toml if you accept that (`jury init --agents agy` writes "
248 "the seat)"
249)
252def agy_opt_in_hint(adapter_keys, which) -> str | None:
253 """:data:`AGY_OPT_IN_NOTE` when agy is installed but no seat uses it, else None.
255 Pure but for *which* (``shutil.which`` in production), so a caller that has
256 just found no usable reviewer can tell an agy-only machine why its one CLI
257 was not used, instead of telling it to install a CLI it already has.
258 *adapter_keys* are the adapter keys of the configured seats; ``google`` is
259 agy's.
260 """
261 if "google" in set(adapter_keys):
262 return None
263 if not which(AGY_AGENT["command"]):
264 return None
265 return AGY_OPT_IN_NOTE
268# Vendors that talk HTTP directly (no CLI subprocess), so they need no
269# `command`: `local` (a user-supplied OpenAI-compatible server, issue #43) and
270# the hosted-API adapters (a real vendor API keyed by an env-var API key,
271# issue #430/#432, joined by `xai-api` in #701).
272_NO_COMMAND_VENDORS = (
273 "local",
274 "anthropic-api",
275 "openai-api",
276 "google-api",
277 "xai-api",
278 "openai-compatible",
279)
281KNOWN_VENDORS = (
282 "anthropic",
283 "openai",
284 "google",
285 "xai",
286 "local",
287 "anthropic-api",
288 "openai-api",
289 "google-api",
290 "xai-api",
291 "openai-compatible",
292 "cli",
293)
295#: The vendor identity every unrecognised vendor collapses into (issue #701).
296#: ``cli`` is a real, documented vendor — "some CLI I brought myself" — and the
297#: generic fallback lands a seat in exactly that bucket, so that is the identity
298#: it carries for the cross-vendor gate.
299GENERIC_VENDOR = "cli"
301#: Vendors serviced by the generic bring-your-own-CLI adapter. The operator
302#: supplies ``command``/``extra_args``; the tool knows no vendor-specific
303#: sandbox flag to add or remove for them (issue #701).
304GENERIC_CLI_VENDORS = ("cli", "xai")
306#: The built-in adapters that spawn ``command`` rather than make an HTTP call:
307#: every known vendor that is not a commandless one (claude, codex, agy and the
308#: bring-your-own CLI). None of them reads ``endpoint`` — ``make_adapter`` picks
309#: them by adapter key before it looks at ``endpoint`` — so an ``endpoint`` on
310#: one of these seats is refused by :func:`validate_config` (#901 review).
311CLI_ADAPTERS: tuple[str, ...] = tuple(v for v in KNOWN_VENDORS if v not in _NO_COMMAND_VENDORS)
313#: Vendors registered at runtime through ``adapters.register_adapter`` — the
314#: documented extension point for a custom adapter. Registering an adapter is
315#: what makes a vendor name *known*: without it the name is a typo as far as
316#: this tool can tell, and :func:`vendor_identity` folds it into
317#: ``GENERIC_VENDOR``. Module-level mutable state, deliberately: it mirrors
318#: ``adapters._VENDOR_ADAPTERS``, which is mutable for the same reason.
319_REGISTERED_VENDORS: set[str] = set()
322def register_vendor(vendor: str) -> None:
323 """Record *vendor* as a recognised name (called by ``register_adapter``)."""
324 name = normalise_vendor(vendor)
325 if name:
326 _REGISTERED_VENDORS.add(name)
329#: Adapter keys registered at runtime, and whether the registered class spawns a
330#: process (#901 review). ``adapters.register_adapter`` records it here, beside
331#: the class it stores, so :func:`spawns_process` can answer for a custom adapter
332#: without importing ``adapters``. A registration replaces the built-in answer
333#: for the same key, exactly as it replaces the built-in class.
334_REGISTERED_ADAPTER_SPAWNS: dict[str, bool] = {}
337def register_adapter_transport(adapter: str, *, spawns: bool) -> None:
338 """Record whether the adapter registered under *adapter* spawns a process."""
339 name = normalise_vendor(adapter)
340 if name:
341 _REGISTERED_ADAPTER_SPAWNS[name] = spawns
344def spawns_process(spec) -> bool:
345 """Whether the adapter ``make_adapter`` builds for *spec* spawns a CLI (pure).
347 The least-privilege audit must ask this of the same selection the spawner
348 makes (#901 review): it used to skip any seat with an ``endpoint``, while
349 ``make_adapter`` picks the adapter by key first and ignores ``endpoint`` on
350 every CLI adapter — so a ``cli`` aider seat with a stray ``endpoint`` ran
351 aider and was audited as an HTTP seat, clean.
353 It lives here, not in ``adapters``, so ``privilege`` can ask it without an
354 import cycle (``adapters`` imports ``privilege`` for ``enforce_read_only``;
355 CodeQL ``py/cyclic-import``). It follows ``adapters.adapter_class`` step for
356 step, and ``tests/test_privilege.py`` holds the two to the same answer for
357 every built-in key, a registered HTTP and a registered CLI adapter, and each
358 fallback shape:
360 1. a registered key: what the registered class declares — its
361 ``SPAWNS_PROCESS`` attribute, ``True`` unless it says otherwise (#903);
362 2. a built-in key: HTTP for the commandless ones (``local``, the hosted APIs,
363 ``openai-compatible``), a process for :data:`CLI_ADAPTERS`;
364 3. no adapter for the key: HTTP when the seat names an ``endpoint``, or an
365 ``api_key_env`` with no ``command`` (the OpenAI-compatible adapter);
366 otherwise a process (the generic CLI adapter, or agy's with no command).
367 """
368 key = spec_adapter(spec)
369 if key in _REGISTERED_ADAPTER_SPAWNS:
370 return _REGISTERED_ADAPTER_SPAWNS[key]
371 if key in _NO_COMMAND_VENDORS:
372 return False
373 if key in CLI_ADAPTERS:
374 return True
375 command = getattr(spec, "command", "") or ""
376 return not (
377 getattr(spec, "endpoint", None) or (getattr(spec, "api_key_env", None) and not command)
378 )
381def recognised_vendors() -> tuple[str, ...]:
382 """Every vendor name this run understands: shipped plus runtime-registered."""
383 return (*KNOWN_VENDORS, *sorted(_REGISTERED_VENDORS - set(KNOWN_VENDORS)))
386def normalise_vendor(vendor) -> str:
387 """The single spelling of a configured vendor every rule reads (pure).
389 ``vendor = "XAI-API"`` and ``vendor = " xai-api "`` name the same vendor as
390 ``vendor = "xai-api"``, so they must normalise to it *before* any rule looks
391 at them. This is the one place that decides what a configured vendor string
392 means: validation, the adapter lookup and :func:`vendor_identity` all go
393 through it, so a seat cannot pass validation under one spelling and reach
394 the cross-vendor gate under another (issue #701, review round 2).
396 Anything that is not a string is not a vendor name, so it normalises to
397 ``""`` rather than raising: ``vendor = 3`` is a config mistake to warn
398 about, not a crash.
399 """
400 return vendor.strip().lower() if isinstance(vendor, str) else ""
403def is_recognised_vendor(vendor) -> bool:
404 """Whether *vendor* names a vendor the tool actually knows (pure-ish)."""
405 key = normalise_vendor(vendor)
406 return bool(key) and key in set(recognised_vendors())
409def is_commandless_vendor(vendor) -> bool:
410 """Whether *vendor* talks HTTP directly and so needs no ``command`` (pure).
412 The one reader of :data:`_NO_COMMAND_VENDORS`. Validation asked this
413 question of the raw string while doctor asked it of a copy of the same
414 tuple, which is how ``vendor = "XAI-API"`` could be a recognised vendor and
415 still be told it was missing a ``command``.
416 """
417 key = normalise_vendor(vendor)
418 return bool(key) and (key in _NO_COMMAND_VENDORS or key.endswith("-api"))
421def vendor_identity(vendor: str) -> str:
422 """The identity a seat carries for the cross-vendor gate (issue #701).
424 A recognised vendor keeps its own name. Everything else — a typo, a vendor
425 this build predates, anything routed to the generic fallback — answers to
426 ``GENERIC_VENDOR``, because that is what it is: two seats the tool could not
427 identify are not two perspectives, and counting them as two is how a bench
428 satisfies ``min_vendors`` without being diverse (#682, reached through
429 configuration). The raw string is still what the ballots and the report
430 carry; only the *gate* collapses, so provenance is never rewritten.
432 Returns ``""`` for an empty vendor, which counts as no vendor at all.
433 """
434 name = normalise_vendor(vendor)
435 if not name:
436 return ""
437 return name if name in set(recognised_vendors()) else GENERIC_VENDOR
440def recognised_adapters() -> tuple[str, ...]:
441 """Every name a seat may give ``[[agent]] adapter`` (issue #705).
443 The adapter vocabulary IS the vendor vocabulary, because ``adapters``' own
444 registry is keyed by vendor name: ``anthropic`` selects the claude protocol,
445 ``cli`` the bring-your-own-CLI passthrough, ``openai-api`` the hosted API
446 call. Derived rather than re-typed so the two cannot drift, and so
447 ``register_adapter`` — which teaches this build a name — makes that name
448 usable as an ``adapter`` in the same breath.
449 """
450 return recognised_vendors()
453def is_recognised_adapter(adapter) -> bool:
454 """Whether *adapter* names an adapter this build actually has (pure-ish)."""
455 key = normalise_vendor(adapter)
456 return bool(key) and key in set(recognised_adapters())
459def unknown_adapter_error(adapter, label: str = "") -> str | None:
460 """The ONE diagnosis for an ``adapter`` name this build does not have (pure).
462 Returns the message, or ``None`` when the seat names no adapter (it inherits
463 its vendor's) or names one that exists.
465 Single because the name is read in two places that must not disagree
466 (issue #708). :func:`validate_config` reads it before a run and turns this
467 into a hard error; ``adapters.make_adapter`` reads it again at the moment the
468 command line is built, and refuses instead of falling through to the generic
469 adapter. Both are needed. With only the first, every caller that loads a
470 config *without* validation — ``--doctor``, ``jury run-agent`` — silently got
471 a ``GenericCLIAdapter``, so ``--doctor`` printed three ``[available]`` seats
472 and ``ready to run: yes`` for a file a real run refused outright. With only
473 the second, the same typo would surface mid-run rather than before the panel
474 starts.
476 The fall-through was the silent guess #705 exists to remove: a name this
477 build does not have is a typo, or a plugin that was not loaded, and invoking
478 the seat through *some other* protocol answers neither.
479 """
480 if adapter is None or is_recognised_adapter(adapter):
481 return None
482 who = f"agent '{label}'" if label else "agent"
483 return (
484 f"{who} has unknown adapter {adapter!r} (expected one "
485 f"of {', '.join(recognised_adapters())}). 'adapter' names the protocol "
486 f"used to build the command line; 'vendor' names the identity the "
487 f"cross-vendor gate counts."
488 )
491def adapter_key(vendor, adapter=None) -> str:
492 """The protocol a seat is invoked through, from its two config keys (pure).
494 ``vendor`` answers "what is this seat?" — the identity the cross-vendor gate
495 counts (:func:`vendor_identity`). ``adapter`` answers "how is its command
496 line built?". Before issue #705 one key answered both, so a GPT model
497 reached through Cursor's ``cursor-agent`` had to choose between running
498 (``vendor = "cli"``, and three such seats are then one vendor) and being
499 counted (``vendor = "openai"``, and ``cursor-agent exec`` is not a command).
501 An unset ``adapter`` falls back to the vendor, which is what makes every
502 configuration written before this key existed byte-identical in argv.
503 """
504 return normalise_vendor(adapter) or normalise_vendor(vendor)
507def spec_adapter(spec) -> str:
508 """:func:`adapter_key` for any spec-like object (duck-typed, pure).
510 Readers outside this module — ``privilege``, ``doctor``, ``adapters`` — are
511 handed specs by tests as well as by the loader, so they ask here instead of
512 reaching for two attributes each and disagreeing about the fallback.
513 """
514 return adapter_key(getattr(spec, "vendor", ""), getattr(spec, "adapter", None))
517KNOWN_TOP_LEVEL_KEYS = ("jury", "agent")
518KNOWN_JURY_KEYS = (
519 "rounds",
520 "chair",
521 "timeout",
522 "parallel",
523 "verify",
524 # Nested tables. The keys inside them are checked too, against
525 # `KNOWN_NESTED_JURY_KEYS` — defined below, beside the dataclasses it
526 # derives them from (issue #719).
527 "ci",
528 "context",
529 "seed",
530 "anonymize_debate",
531 "prefer_non_reviewer_chair",
532 # Demote a local-only finding to non-blocking severity (issue #442).
533 "demote_local_only",
534 # Execution controls (issue #30).
535 "total_timeout",
536 "phase_timeout",
537 "retries",
538 # Adaptive rounds (issue #40).
539 "max_rounds",
540 "early_stop",
541 # Risk-aware auto-depth (issue #120).
542 "auto_depth",
543 # Full-transcript / verbose rendering (rendering-only; not in config_hash).
544 "transcript",
545 # Final-verdict mode: "chair" synthesis or panel "vote" (rendering-only).
546 "decision",
547 # Animated theater view defaults (rendering-only; issue #364).
548 "theater",
549 "theater_style",
550 # Large-diff handling (issue #31); a nested table, like `ci`/`context`.
551 "diff",
552 # The report footer (issue #911); a nested table too. Rendering-only:
553 # not in `config_hash`.
554 "output",
555 # Risk-aware tiered model routing (issue #524) and the static-analysis
556 # pre-pass (issue #523). Both are read by `_from_dict` and documented in
557 # docs/configuration.md, so `--strict-config` must not reject them (#715).
558 "routing",
559 "hints",
560 # Pre-existing findings gating option (issue #976): "report" | "ignore".
561 "pre_existing",
562)
563KNOWN_AGENT_KEYS = (
564 "name",
565 "vendor",
566 # The protocol used to build this seat's command line (issue #705).
567 # Optional: it defaults to the vendor's shipped adapter.
568 "adapter",
569 "command",
570 "model",
571 "timeout",
572 "enabled",
573 "extra_args",
574 # OpenAI-compatible local/open-weight endpoint (issue #43).
575 "endpoint",
576 # Universal agent extensions
577 "api_key_env",
578 "prompt_mode",
579 "headers",
580 # Reasoning effort (issue #662): mapped per vendor in adapters.effort_args.
581 "effort",
582 # Cost tier (issue #714): what tiered routing reads to decide which seats
583 # sit on a routine diff and which one anchors it.
584 "tier",
585 # Sampling temperature for a local seat's chat-completions request. Some
586 # open-weight models (gpt-oss) loop under the greedy default of 0.
587 "temperature",
588)
590#: Inclusive bounds for ``[[agent]] temperature`` — the OpenAI chat-completions
591#: range, which every OpenAI-compatible local server accepts.
592TEMPERATURE_MIN = 0.0
593TEMPERATURE_MAX = 2.0
596def is_valid_temperature(value) -> bool:
597 """Whether *value* is a usable ``[[agent]] temperature`` (pure).
599 A TOML integer or float in ``[TEMPERATURE_MIN, TEMPERATURE_MAX]``. ``bool``
600 is refused although it subclasses ``int`` (``temperature = true`` is a typo,
601 not 1.0), and ``nan`` fails the range test like any other out-of-range value.
602 """
603 if isinstance(value, bool) or not isinstance(value, (int, float)):
604 return False
605 return TEMPERATURE_MIN <= value <= TEMPERATURE_MAX
608#: Accepted values for ``[[agent]] effort`` / ``--effort`` (issue #662).
609#: Duplicated as a literal rather than imported from ``adapters`` so config
610#: validation stays free of any adapter import (``adapters`` imports ``config``).
611#: ``tests/test_adapters.py`` pins the two lists together.
612KNOWN_EFFORTS = ("low", "medium", "high")
614#: Accepted values for ``[[agent]] tier`` (issue #714). ``frontier`` is the
615#: default and the anchor-capable kind; ``economical`` is a seat tiered routing
616#: may put on a routine diff in place of the frontier seats it benches. The
617#: operator says which is which — no model-name heuristics.
618KNOWN_TIERS = ("frontier", "economical")
619DEFAULT_TIER = "frontier"
621#: Accepted values for ``[jury] routing`` (issue #524). ``standard`` is the
622#: default uniform panel; ``tiered`` is the risk-aware panel that reads each
623#: seat's :data:`KNOWN_TIERS` value. The closed vocabulary is the companion of
624#: ``tier``'s (#747): the two keys are one feature, and a misspelling of either
625#: silently produces the panel the operator did not ask for.
626KNOWN_ROUTINGS = ("standard", "tiered")
627DEFAULT_ROUTING = "standard"
629#: Accepted values for ``[jury] pre_existing`` (issue #976). ``report`` (default)
630#: treats pre-existing findings as normal reportable/blocking findings in the CI gate;
631#: ``ignore`` treats them as non-blocking in ``ai_jury.ci.evaluate_ci``.
632KNOWN_PRE_EXISTINGS = ("report", "ignore")
633DEFAULT_PRE_EXISTING = "report"
636class ConfigError(Exception):
637 """Raised when a jury configuration is invalid."""
640# The `[[agent]] headers` messages live here, not inline, because TWO paths
641# reject the same shapes and must say the same thing (issue #716, review r1):
642# `validate_config` collects them into its error list, and `_from_dict` raises
643# one directly for a config that reached materialisation unvalidated —
644# `load_config` defaults to `validate=False`, and a Python caller that loads a
645# config without asking for validation reaches `_from_dict` directly.
646#
647# Every message names the AGENT and, where it helps, the header NAME, and none
648# of them quotes the offending VALUE back: a header is exactly where an
649# `Authorization: Bearer …` credential lives, and these are printed to terminals
650# and pasted into issues. The type says what is wrong without reproducing what
651# is secret — the precedent `api_key_env` set for a rejected value.
652def _headers_not_a_table_message(label: str, value) -> str:
653 """`headers` is not a table at all — it cannot become headers (hard)."""
654 return f"agent '{label}' headers must be a table of string keys (got {type(value).__name__})."
657def _headers_bad_key_message(label: str, key) -> str:
658 """A key that is not a string cannot be a header name (hard).
660 tomllib cannot produce one — every TOML key, bare or quoted, parses to
661 `str` — so this guards a config dict built in Python (a test, an embedder
662 calling `validate_config`/`_from_dict` directly) rather than a written file.
663 """
664 return (
665 f"agent '{label}' headers has a non-string header name "
666 f"({type(key).__name__}); header names must be strings."
667 )
670def _headers_coerced_value_warning(label: str, header: str, value) -> str:
671 """A non-string value still becomes a header — so this is soft.
673 `X-Retries = 3` is a working fallback: it is sent as `X-Retries: 3`. Under
674 this module's split (unusable ⇒ hard error, working fallback ⇒ warning, as
675 for a malformed `api_key_env` name) that is a warning, and `--strict-config`
676 is where an operator asks for it to be fatal.
677 """
678 return (
679 f"agent '{label}' headers value for '{header}' is not a string "
680 f"({type(value).__name__}); it was coerced to a string before being sent."
681 )
684# The nested `[jury.*]` shape message lives here for the same reason the
685# `headers` ones do (issue #729): TWO paths reject the same shape and must say
686# the same thing. `validate_config` collects it into its error list, and the
687# `_*_from_dict` readers raise it directly for a config that reached
688# materialisation unvalidated — `load_config` defaults to `validate=False`, and
689# `jury run-agent` keeps it that way on purpose.
690#
691# `[jury.ci]` and `[jury.diff]` were checked with this wording written out
692# inline; `[jury.context]` was not checked at all, so `context = "diff-only"`
693# (written where `[jury.context] mode = "diff-only"` was meant) passed
694# `--config-validate --strict-config` and then died in `_context_from_dict` with
695# `'str' object has no attribute 'get'`.
696#: Top-level shape messages, shared by ``validate_config`` and ``_from_dict`` so the
697#: validating and the non-validating path (``jury run-agent``, ``load_config``'s
698#: default) say the same thing (issue #732).
699_JURY_NOT_A_TABLE = "[jury] must be a table."
700_AGENTS_NOT_AN_ARRAY = "[[agent]] must be an array of tables."
703def _agent_not_a_table_message(idx: int) -> str:
704 return f"agent[{idx}] must be a table."
707def _nested_table_message(table: str) -> str:
708 """`[jury.<table>]` is not a table, so its reader cannot read it (hard)."""
709 return f"[jury.{table}] must be a table."
712#: The numeric bounds on the `[jury]` scalars, keyed by the setting's dotted
713#: path under `[jury]`. Each entry is `(minimum, phrase, optional)`: *phrase* is
714#: the rule as the message has always stated it — `timeout` says "a positive
715#: integer" and `rounds` "an integer >= 1", which mean the same thing and are
716#: both kept because they are what operators have read for releases — and
717#: *optional* marks a setting whose absence is legal, which the message says as
718#: "when set".
719#:
720#: The table exists because these bounds have TWO surfaces (issue #748). Every
721#: one of them is also a CLI flag, and the flags were assigned onto the config
722#: *after* `validate_config` had already run, so nothing range-checked them:
723#: `--rounds 0` was accepted, ran a full Round 1 and exited 0 while `rounds = 0`
724#: in `jury.toml` was a hard error — one value, one field, two answers, on a
725#: flag `docs/parameters.md` documents as `≥ 1`. `bound_error` is the single
726#: reader, so a bound cannot be stated twice and drift apart.
727_NUMERIC_BOUNDS: dict[str, tuple[int, str, bool]] = {
728 "rounds": (1, "an integer >= 1", False),
729 "timeout": (1, "a positive integer", False),
730 "retries": (0, "an integer >= 0", False),
731 # Execution controls (issue #30).
732 "total_timeout": (1, "a positive integer", True),
733 "phase_timeout": (1, "a positive integer", True),
734 # Adaptive rounds (issue #40).
735 "max_rounds": (1, "an integer >= 1", True),
736 # Large-diff handling (issue #31).
737 "diff.max_bytes": (1, "a positive integer", True),
738 "diff.chunk_max_bytes": (1, "a positive integer", True),
739 # The fail-closed CI guards (docs audit 2026-09-29). Both used to be clamped
740 # rather than checked: `min_vendors = -1` or `--min-vendors -5` became 0,
741 # which is the documented opt-out, so a typo turned the cross-vendor guard
742 # off and nothing said so.
743 "ci.min_vendors": (0, "an integer >= 0", True),
744 "ci.min_reviews": (0, "an integer >= 0", True),
745}
748#: The boolean `[jury]` settings `validate_config` type-checks, as dotted paths
749#: under `[jury]` (docs audit 2026-09-29). `theater` and `output.attribution`
750#: are checked on their own, above this table's reader, with the same message.
751_BOOL_SETTINGS: tuple[str, ...] = (
752 "parallel",
753 "verify",
754 "anonymize_debate",
755 "prefer_non_reviewer_chair",
756 "demote_local_only",
757 "early_stop",
758 "auto_depth",
759 "transcript",
760 "hints",
761 "ci.ignore_unverified",
762 "context.redact_secrets",
763 "diff.chunk",
764 "diff.exclude_generated",
765)
767#: `[jury.context] mode` values; `_context_from_dict` reads anything else as the first.
768KNOWN_CONTEXT_MODES: tuple[str, ...] = ("diff-only", "expanded")
770#: `[[agent]] prompt_mode` values, as `GenericCLIAdapter._prompt_mode` reads them.
771KNOWN_PROMPT_MODES: tuple[str, ...] = ("stdin", "arg")
774def bound_error(setting: str, value, where: str | None = None) -> str | None:
775 """The message for *value* breaking the bound on ``setting``, else ``None``.
777 *setting* is a key of :data:`_NUMERIC_BOUNDS`. *where* names the surface the
778 value was written on and defaults to the ``jury.<setting>`` config path; the
779 CLI passes the flag (``--rounds``), so an operator who has no ``jury.toml``
780 at all is not pointed at a key they never wrote. The rule, the bound and the
781 quoted value are identical either way — that is the point of one reader.
783 ``None`` means "not set" and passes for an optional setting. A bool is not
784 an integer here: ``rounds = true`` is a mistake, not ``rounds = 1``.
785 """
786 minimum, phrase, optional = _NUMERIC_BOUNDS[setting]
787 if value is None and optional:
788 return None
789 if isinstance(value, int) and not isinstance(value, bool) and value >= minimum:
790 return None
791 suffix = " when set" if optional else ""
792 return f"{where or f'jury.{setting}'} must be {phrase}{suffix} (got {value!r})."
795def validate_config(data: dict, strict: bool = False) -> list:
796 """Validate a raw config dict.
798 Raises ``ConfigError`` with an actionable message on hard-invalid input
799 (rounds < 1, timeout <= 0, duplicate agent names, empty/missing command,
800 no agents at all). Returns a list of warning strings for soft issues
801 (unknown vendor, chair not an enabled agent, unknown keys).
803 When ``strict`` is True, soft issues raise ``ConfigError`` instead of
804 being returned as warnings.
805 """
806 warnings: list = []
807 errors: list = []
809 if not isinstance(data, dict):
810 raise ConfigError("config root must be a table/dict.")
812 # Unknown top-level keys (soft).
813 for key in data:
814 if key not in KNOWN_TOP_LEVEL_KEYS:
815 warnings.append(
816 f"unknown top-level key '{key}' (expected one of "
817 f"{', '.join(KNOWN_TOP_LEVEL_KEYS)})."
818 )
820 jury = data.get("jury", {})
821 if not isinstance(jury, dict):
822 raise ConfigError(_JURY_NOT_A_TABLE)
824 for key in jury:
825 if key not in KNOWN_JURY_KEYS:
826 warnings.append(
827 f"unknown key 'jury.{key}' (expected one of {', '.join(KNOWN_JURY_KEYS)})."
828 )
830 # Unknown keys INSIDE the nested `[jury.*]` tables (soft, issue #719).
831 #
832 # The loop above stops at the table names: it sees `jury.ci` and is happy.
833 # `_ci_from_dict`/`_context_from_dict`/`_diff_from_dict` then take the keys
834 # they know and drop the rest, so `[jury.ci] min_vendor = 3` (the
835 # cross-vendor gate, one `s` short) passed `--config-validate
836 # --strict-config` clean and the panel ran on the default of 2. Same soft
837 # severity as the top level — the config still loads, it just does not mean
838 # what it says — with the dotted path in the message so the operator is
839 # told which table to look in.
840 #
841 # A non-table is reported as a shape error and NOT iterated for unknown
842 # keys: iterating a string would produce one warning per character, and the
843 # value cannot carry keys anyway. All three tables are checked in this one
844 # loop (issue #729) — `ci` and `diff` had the check written out inline below
845 # and `context` had none, which is exactly how the missing one went unnoticed.
846 for table, known_nested in KNOWN_NESTED_JURY_KEYS.items():
847 nested = jury.get(table)
848 if nested is None:
849 continue
850 if not isinstance(nested, dict):
851 errors.append(_nested_table_message(table))
852 continue
853 for key in nested:
854 if key not in known_nested:
855 warnings.append(
856 f"unknown key 'jury.{table}.{key}' (expected one of {', '.join(known_nested)})."
857 )
859 # The bounded `[jury]` scalars (hard): rounds >= 1, timeout > 0, the
860 # optional execution budgets (issue #30) > 0 and retries >= 0. Every rule
861 # and every message comes from `_NUMERIC_BOUNDS` through `bound_error`,
862 # which is also what the CLI flags writing these same settings are checked
863 # against, so the two surfaces cannot answer differently (issue #748). A
864 # required key that is absent is validated at its default; an absent
865 # optional one is None and passes.
866 for setting, value in (
867 ("rounds", jury.get("rounds", 1)),
868 ("timeout", jury.get("timeout", 600)),
869 ("total_timeout", jury.get("total_timeout")),
870 ("phase_timeout", jury.get("phase_timeout")),
871 ("retries", jury.get("retries", 0)),
872 ):
873 message = bound_error(setting, value)
874 if message:
875 errors.append(message)
877 # Final-verdict mode (issue #220): "chair" or "vote".
878 decision = jury.get("decision")
879 if decision is not None and str(decision).strip().lower() not in ("chair", "vote"):
880 errors.append(f"jury.decision must be 'chair' or 'vote' (got {decision!r}).")
882 # Animated theater defaults (issue #364): theater is a bool, style is enum.
883 theater = jury.get("theater")
884 if theater is not None and not isinstance(theater, bool):
885 errors.append(f"jury.theater must be true or false (got {theater!r}).")
886 style = jury.get("theater_style")
887 if style is not None and str(style).strip().lower() not in ("flat", "pixel"):
888 errors.append(f"jury.theater_style must be 'flat' or 'pixel' (got {style!r}).")
890 # Panel routing (hard when present and not a known kind, issue #747), for the
891 # reason `[[agent]] tier` is hard: nothing equals "tiered" but "tiered", so
892 # `routing = "teired"` would otherwise be read as the default and the run
893 # would quietly buy the uniform panel the operator asked it not to.
894 routing = jury.get("routing")
895 if routing is not None and (
896 not isinstance(routing, str) or routing.strip().lower() not in KNOWN_ROUTINGS
897 ):
898 errors.append(f"jury.routing must be one of {', '.join(KNOWN_ROUTINGS)} (got {routing!r}).")
900 # Pre-existing findings gating option (hard when present and not known, issue #976).
901 pre_existing = jury.get("pre_existing")
902 if pre_existing is not None and (
903 not isinstance(pre_existing, str) or pre_existing.strip().lower() not in KNOWN_PRE_EXISTINGS
904 ):
905 errors.append(
906 f"jury.pre_existing must be one of {', '.join(KNOWN_PRE_EXISTINGS)} (got {pre_existing!r})."
907 )
909 # The attribution footer (issue #911) is a bool, like `theater`: a string
910 # "false" is truthy, so accepting it would keep the footer the operator turned off.
911 output_cfg = jury.get("output")
912 if isinstance(output_cfg, dict):
913 attribution = output_cfg.get("attribution")
914 if attribution is not None and not isinstance(attribution, bool):
915 errors.append(f"jury.output.attribution must be true or false (got {attribution!r}).")
917 # Every other boolean switch (hard, docs audit 2026-09-29), for the reason
918 # #911 gave `attribution`: they were read with `bool(...)`, and the string
919 # "false" is truthy, so `verify = "false"` ran verification, passing
920 # `--strict-config`. TOML has real booleans; a quoted one is a mistake.
921 for dotted in _BOOL_SETTINGS:
922 table, _, key = dotted.rpartition(".")
923 holder = jury.get(table) if table else jury
924 value = holder.get(key) if isinstance(holder, dict) else None
925 if value is not None and not isinstance(value, bool):
926 errors.append(f"jury.{dotted} must be true or false (got {value!r}).")
927 # `[jury.context] mode` (hard, same audit): anything else was quietly read as
928 # "diff-only", so `mode = "expand"` reviewed without the context asked for.
929 context_mode = (
930 jury.get("context", {}).get("mode") if isinstance(jury.get("context"), dict) else None
931 )
932 if context_mode is not None and not (
933 isinstance(context_mode, str) and context_mode.strip().lower() in KNOWN_CONTEXT_MODES
934 ):
935 errors.append(
936 f"jury.context.mode must be one of {', '.join(KNOWN_CONTEXT_MODES)} "
937 f"(got {context_mode!r})."
938 )
940 # Adaptive rounds (issue #40): max_rounds >= 1 (hard); early_stop is a bool.
941 max_rounds_error = bound_error("max_rounds", jury.get("max_rounds"))
942 if max_rounds_error:
943 errors.append(max_rounds_error)
945 # Large-diff handling (issue #31): [jury.diff] sizes are positive ints.
946 diff_cfg = jury.get("diff", {})
947 if isinstance(diff_cfg, dict):
948 for key in ("max_bytes", "chunk_max_bytes"):
949 message = bound_error(f"diff.{key}", diff_cfg.get(key))
950 if message:
951 errors.append(message)
953 # CI gate severities (issue #718): hard, like `effort`, and for the same
954 # reason. `fail_on = ["majr"]` matches no group, so the one setting that
955 # decides whether CI fails would report a green PASS quoting the typo, on
956 # every run, forever — a silently disabled gate is worse than no gate.
957 ci_cfg = jury.get("ci", {})
958 if isinstance(ci_cfg, dict):
959 fail_on = ci_cfg.get("fail_on")
960 if fail_on is not None:
961 # A scalar is accepted here because `_ci_from_dict` wraps one in a
962 # list; validating the raw value would refuse a config that loads.
963 message = fail_on_error(
964 fail_on if isinstance(fail_on, list) else [fail_on], "jury.ci.fail_on"
965 )
966 if message:
967 errors.append(message)
968 # The fail-closed guards (hard, docs audit 2026-09-29): a negative or
969 # non-integer value used to be clamped or defaulted at load, so
970 # `min_vendors = -1` silently disabled the cross-vendor guard and
971 # `min_reviews = "lots"` silently read as "off", both passing
972 # `--strict-config`. Same table and message as the `--min-vendors` /
973 # `--min-reviews` flags.
974 for key in ("min_vendors", "min_reviews"):
975 message = bound_error(f"ci.{key}", ci_cfg.get(key))
976 if message:
977 errors.append(message)
979 agents_data = data.get("agent", [])
980 if not isinstance(agents_data, list):
981 raise ConfigError(_AGENTS_NOT_AN_ARRAY)
983 # At least one agent (hard).
984 if not agents_data:
985 errors.append("no agents configured; define at least one [[agent]] entry.")
987 seen_names: set = set()
988 enabled_names: set = set()
989 for idx, agent in enumerate(agents_data):
990 if not isinstance(agent, dict):
991 errors.append(_agent_not_a_table_message(idx))
992 continue
994 for key in agent:
995 if key not in KNOWN_AGENT_KEYS:
996 warnings.append(
997 f"unknown key 'agent[{idx}].{key}' (expected one of "
998 f"{', '.join(KNOWN_AGENT_KEYS)})."
999 )
1001 name = agent.get("name", "")
1002 label = name or f"agent[{idx}]"
1004 # Normalise the vendor ONCE, here, and let every later rule read the
1005 # normalised value (issue #701, review round 2). A vendor that is
1006 # recognised must be recognised by every rule: deciding "commandless
1007 # API vendor" on the raw string made `vendor = "XAI-API"` a known
1008 # vendor that was nonetheless failed for having no `command`.
1009 # `vendor_value` is kept for the messages, which quote what the
1010 # operator actually wrote.
1011 vendor_value = agent.get("vendor", "")
1012 vendor = normalise_vendor(vendor_value)
1014 # The adapter is the PROTOCOL, the vendor is the IDENTITY (issue #705).
1015 # Every question below of the form "how is this seat invoked?" — does it
1016 # need a `command`, which sandbox flag does it accept — is asked of the
1017 # adapter, which is the vendor itself unless the operator said otherwise.
1018 adapter_value = agent.get("adapter")
1019 adapter = adapter_key(vendor, adapter_value)
1021 # Unknown adapter (HARD, unlike an unknown vendor). An unknown vendor
1022 # still names a seat that can run; it just answers to `cli` at the gate.
1023 # An unknown adapter names a protocol this build does not have, and the
1024 # only fallbacks are to guess — which is precisely the failure #705 is
1025 # about: `openai` guessed `codex exec` onto `cursor-agent` and the seat
1026 # died in half a second, mid-run, having already been paid for. A typo
1027 # here is named before the panel starts, like `effort`. The message
1028 # itself lives in `unknown_adapter_error`, because `make_adapter` asks
1029 # the same question at the other end and must give the same answer
1030 # (issue #708).
1031 adapter_error = unknown_adapter_error(adapter_value, label)
1032 if adapter_error is not None:
1033 errors.append(adapter_error)
1035 # Unique, non-empty name (hard for duplicates).
1036 if not name:
1037 errors.append(f"agent[{idx}] is missing a non-empty 'name'.")
1038 elif name in seen_names:
1039 errors.append(f"duplicate agent name '{name}'.")
1040 else:
1041 seen_names.add(name)
1043 # A local OpenAI-compatible agent (issue #43) talks to an HTTP
1044 # ``endpoint`` (default ``http://localhost:11434/v1``) instead of a CLI,
1045 # so it does not require a ``command``; it does need a ``model``. A
1046 # hosted-API agent (issue #430) likewise talks HTTP instead of a CLI —
1047 # to the vendor's fixed, non-configurable endpoint — so it also needs
1048 # no ``command``, but does need a ``model``; it has no ``endpoint`` to
1049 # validate since the URL isn't a config value. Every other vendor
1050 # requires a non-empty ``command``.
1051 command = agent.get("command", "")
1052 has_endpoint = bool(agent.get("endpoint"))
1053 # A CLI adapter does not read `endpoint` (#901 review): `make_adapter`
1054 # selects it by key and spawns `command` whatever `endpoint` says. The key
1055 # was worse than unused — it made this check treat the seat as HTTP, skip
1056 # every `command` rule below, and made the least-privilege audit skip the
1057 # seat — so a seat that runs a CLI and names an endpoint is refused, and
1058 # its `command` is still checked.
1059 if has_endpoint and adapter in CLI_ADAPTERS:
1060 errors.append(
1061 f"agent '{label}' names an 'endpoint', but its adapter '{adapter}' "
1062 f"runs 'command' and never reads one; remove 'endpoint', or use "
1063 f"vendor/adapter 'local' or 'openai-compatible' for an HTTP seat."
1064 )
1065 has_endpoint = False
1066 # Asked of the ADAPTER, not the vendor (#705): whether a seat needs a
1067 # `command` is a fact about how it is invoked. `vendor = "openai",
1068 # adapter = "cli"` runs a CLI and needs one; `vendor = "openai",
1069 # adapter = "openai-api"` makes an HTTP call and does not.
1070 is_local_or_http = is_commandless_vendor(adapter) or has_endpoint
1071 if is_local_or_http:
1072 if not agent.get("model"):
1073 who = (
1074 f"vendor '{vendor_value}'"
1075 if adapter == vendor
1076 else f"adapter '{adapter_value}'"
1077 )
1078 warnings.append(
1079 f"agent '{label}' ({who}) has no 'model'; the "
1080 f"server or API call will likely reject the request."
1081 )
1082 endpoint = agent.get("endpoint")
1083 if endpoint:
1084 e_errors, e_warnings = _endpoint_issues(endpoint, label)
1085 errors.extend(e_errors)
1086 warnings.extend(e_warnings)
1087 elif not command:
1088 # A custom adapter registered with `SPAWNS_PROCESS = False` is its own
1089 # invocation — its `run()` calls the backend — so it has no `command`
1090 # to be missing (docs audit 2026-09-29). docs/configuration.md has
1091 # always shown such a seat without one, and this refused it. A
1092 # registered adapter that spawns still needs one, like a built-in CLI.
1093 if _REGISTERED_ADAPTER_SPAWNS.get(adapter) is not False:
1094 errors.append(f"agent '{label}' is missing a non-empty 'command'.")
1095 elif _is_relative_path_command(command):
1096 # A relative path with separators (e.g. ./tools/codex, bin/agy) could
1097 # resolve a binary from an attacker-influenced location (#293/F-6).
1098 # Require a bare name (resolved on PATH) or an absolute path.
1099 errors.append(
1100 f"agent '{label}' command '{command}' is a relative path; use a "
1101 f"bare name (resolved on PATH) or an absolute path."
1102 )
1103 elif os.environ.get(_REQUIRE_ABSOLUTE_COMMAND_ENV) and not Path(command).is_absolute():
1104 # Strict opt-in (issue #296): in a hardened/CI context, refuse even a
1105 # bare name so a poisoned PATH can't resolve a shim — require an
1106 # absolute path for every agent command.
1107 errors.append(
1108 f"agent '{label}' command '{command}' is not an absolute path; "
1109 f"{_REQUIRE_ABSOLUTE_COMMAND_ENV} requires every agent command to "
1110 f"be an absolute path."
1111 )
1113 # `enabled` and `prompt_mode` (hard, docs audit 2026-09-29): `enabled =
1114 # "false"` is truthy and seated the agent it meant to bench, and any
1115 # `prompt_mode` but "arg" was read as "stdin", so `prompt_mode = "args"`
1116 # piped the prompt to a CLI that expected it on argv.
1117 enabled_value = agent.get("enabled")
1118 if enabled_value is not None and not isinstance(enabled_value, bool):
1119 errors.append(f"agent '{label}' enabled must be true or false (got {enabled_value!r}).")
1120 prompt_mode = agent.get("prompt_mode")
1121 if prompt_mode is not None and not (
1122 isinstance(prompt_mode, str) and prompt_mode.lower() in KNOWN_PROMPT_MODES
1123 ):
1124 errors.append(
1125 f"agent '{label}' prompt_mode must be one of "
1126 f"{', '.join(KNOWN_PROMPT_MODES)} (got {prompt_mode!r})."
1127 )
1129 # Per-agent timeout (hard if present and invalid).
1130 a_timeout = agent.get("timeout", 600)
1131 if not isinstance(a_timeout, int) or isinstance(a_timeout, bool) or a_timeout <= 0:
1132 errors.append(
1133 f"agent '{label}' timeout must be a positive integer (got {a_timeout!r})."
1134 )
1136 # `api_key_env` names an environment variable and is echoed into
1137 # diagnostics, so it is bounded to a real env var name (see
1138 # redaction.safe_env_var_name). Warn rather than fail: the vendor
1139 # default still works, but the operator should not discover the
1140 # silent fallback by wondering why their variable is ignored.
1141 #
1142 # The rejected value is deliberately NOT quoted back. Reaching this
1143 # branch means it contains characters outside the safe set — which is
1144 # exactly the class (control characters, ANSI escapes, quotes) that must
1145 # not be written to a terminal or spliced into a report. Naming the
1146 # agent and stating the rule locates the problem without reproducing it.
1147 env_var = agent.get("api_key_env")
1148 if env_var is not None and safe_env_var_name(env_var, "") != env_var:
1149 warnings.append(
1150 f"agent '{label}' api_key_env is not a valid environment variable "
1151 f"name (expected {ENV_VAR_NAME_RULE}); the vendor default will be used."
1152 )
1154 # `headers` carries the extra HTTP headers a hosted adapter sends
1155 # (issue #716). It was never checked at all: `_from_dict` turned every
1156 # non-table into `{}`, so `headers = "Authorization = Bearer y"` passed
1157 # `--config-validate` AND `--strict-config` and the seat ran with no
1158 # extra headers — failing at the remote API, or, for a routing header
1159 # the provider honours a default for, reviewing quietly against a
1160 # backend nobody chose.
1161 #
1162 # The severity follows this module's split, not the fact that the key is
1163 # newly checked: a shape that CANNOT become headers is hard (like an
1164 # unknown `effort`), a shape that becomes working headers by a documented
1165 # coercion is a warning (like a malformed `api_key_env` name that falls
1166 # back to the vendor default). Hard: not a table, and a non-string key —
1167 # neither can be a header name or map. Soft: a non-string VALUE, which
1168 # `_from_dict` sends as `str(value)`.
1169 raw_headers = agent.get("headers")
1170 if raw_headers is not None and not isinstance(raw_headers, dict):
1171 errors.append(_headers_not_a_table_message(label, raw_headers))
1172 elif isinstance(raw_headers, dict):
1173 for header_name, header_value in raw_headers.items():
1174 if not isinstance(header_name, str):
1175 errors.append(_headers_bad_key_message(label, header_name))
1176 elif not isinstance(header_value, str):
1177 warnings.append(
1178 _headers_coerced_value_warning(label, header_name, header_value)
1179 )
1181 # Reasoning effort (hard when present and not a known level, issue
1182 # #662): a typo like `effort = "max"` would otherwise be silently
1183 # dropped, and the operator would pay for a run they think is deeper
1184 # than it is.
1185 effort = agent.get("effort")
1186 if effort is not None and (
1187 not isinstance(effort, str) or effort.strip().lower() not in KNOWN_EFFORTS
1188 ):
1189 errors.append(
1190 f"agent '{label}' effort must be one of "
1191 f"{', '.join(KNOWN_EFFORTS)} (got {effort!r})."
1192 )
1194 # Cost tier (hard when present and not a known kind, issue #714), for
1195 # the reason `effort` is hard: `tier = "cheap"` would otherwise be read
1196 # as the default and the seat silently treated as frontier — the exact
1197 # opposite of what the operator wrote.
1198 tier = agent.get("tier")
1199 if tier is not None and (
1200 not isinstance(tier, str) or tier.strip().lower() not in KNOWN_TIERS
1201 ):
1202 errors.append(
1203 f"agent '{label}' tier must be one of {', '.join(KNOWN_TIERS)} (got {tier!r})."
1204 )
1206 # Sampling temperature. Hard when present and not a number in range,
1207 # for the reason `effort` is: `temperature = "1"` or `= 5` would
1208 # otherwise fall back to the greedy default, and a model that loops at 0
1209 # (gpt-oss) returns an empty review the operator believes they fixed.
1210 # Only the local adapter sends it; on any other seat it is a warning,
1211 # because the seat still runs — without the setting the operator wrote.
1212 temperature = agent.get("temperature")
1213 if temperature is not None:
1214 if not is_valid_temperature(temperature):
1215 errors.append(
1216 f"agent '{label}' temperature must be a number from "
1217 f"{TEMPERATURE_MIN:g} to {TEMPERATURE_MAX:g} (got {temperature!r})."
1218 )
1219 elif adapter != "local":
1220 warnings.append(
1221 f"agent '{label}' temperature applies only to local seats "
1222 f"(adapter '{adapter}' does not send it); ignored."
1223 )
1225 # Known vendor (soft). The warning names the CONSEQUENCE, not just the
1226 # fact: the fallback seat still runs, but it answers to `cli` at the
1227 # cross-vendor gate, so two of them are one vendor (issue #701).
1228 if not is_recognised_vendor(vendor):
1229 warnings.append(
1230 f"agent '{label}' has unknown vendor '{vendor_value}' (expected one "
1231 f"of {', '.join(recognised_vendors())}); using the generic "
1232 f"'{GENERIC_VENDOR}' fallback, which counts as vendor "
1233 f"'{GENERIC_VENDOR}' for min_vendors — two such seats are one "
1234 f"vendor, not two."
1235 )
1237 if name and agent.get("enabled", True):
1238 enabled_names.add(name)
1240 # Chair must reference an enabled agent (soft). The literal "rotate" is a
1241 # valid special value (deterministic per-run rotation) and never warns.
1242 # Only a chair the operator WROTE is checked (docs audit 2026-09-29): an
1243 # absent one is `default_chair`, the first enabled agent, which is enabled
1244 # by construction. This used to assume `claude`, so a config with no
1245 # `claude` seat and no `chair` failed `--strict-config` over a value the run
1246 # never used.
1247 chair = jury.get("chair")
1248 if chair is not None and enabled_names and chair != "rotate" and chair not in enabled_names:
1249 warnings.append(
1250 f"jury.chair '{chair}' is not an enabled agent (enabled: "
1251 f"{', '.join(sorted(enabled_names)) or 'none'}); the first "
1252 "enabled agent will be used as fallback."
1253 )
1255 if errors:
1256 raise ConfigError("invalid configuration:\n - " + "\n - ".join(errors))
1258 if strict and warnings:
1259 raise ConfigError(
1260 "configuration warnings treated as errors (strict mode):\n - "
1261 + "\n - ".join(warnings)
1262 )
1264 return warnings
1267@dataclass
1268class AgentSpec:
1269 """One configured seat on the panel.
1271 ``vendor`` is normalised on construction (issue #701, review round 3) and is
1272 therefore the ONLY spelling any reader ever sees. Round 2 normalised at each
1273 rule instead, which left every new reader free to forget: ``_detect_warnings``
1274 compared the raw string while ``_unavailable_reason`` compared the normalised
1275 one, so a single ``vendor = "XAI-API"`` seat got two different diagnoses out
1276 of one ``--doctor`` run. Doing it here — in the one place a spec comes into
1277 existence, whatever built it — is what makes "every rule reads one value"
1278 true by construction rather than by review.
1280 Normalising is only ``strip().lower()``, so provenance survives it: the
1281 operator's vendor *name* is preserved, only its whitespace and case are not.
1282 Messages that must quote the file verbatim (``validate_config``) read the raw
1283 TOML dict, not this field. A non-string vendor normalises to ``""`` — a
1284 config mistake to warn about, not a crash in a later ``.lower()``.
1285 """
1287 name: str
1288 vendor: str
1289 command: str = ""
1290 model: str | None = None
1291 timeout: int = 600
1292 enabled: bool = True
1293 extra_args: list[str] = field(default_factory=list)
1294 # OpenAI-compatible base URL for a local/open-weight or hosted API agent (issue #43).
1295 endpoint: str | None = None
1296 # Universal agent extensions
1297 api_key_env: str | None = None
1298 prompt_mode: str | None = None
1299 headers: dict[str, str] = field(default_factory=dict)
1300 # Reasoning effort: "low" | "medium" | "high" (issue #662). None leaves the
1301 # vendor default alone. Mapped per vendor by ``adapters.effort_args``.
1302 effort: str | None = None
1303 # The protocol this seat is invoked through (issue #705): which adapter
1304 # builds its command line. ``None`` means "the vendor's shipped adapter",
1305 # which is what every configuration written before this key existed means —
1306 # so their argv is unchanged, byte for byte. Declared last, after every
1307 # other field, so no positional construction site is silently re-bound.
1308 # Read it through :attr:`adapter_key`, never directly: the fallback to the
1309 # vendor belongs in one place.
1310 adapter: str | None = None
1311 # Cost tier (issue #714): "frontier" (default; may anchor a routed panel) or
1312 # "economical" (seated on routine diffs in place of benched frontier seats).
1313 # Normalised on construction like `vendor`; an unknown value is refused by
1314 # `validate_config` and falls back to the default here so the reader never
1315 # carries a spelling no rule knows.
1316 tier: str = DEFAULT_TIER
1317 # Sampling temperature a local seat sends. ``None`` keeps the local
1318 # adapter's greedy default of 0, byte for byte. Declared last for the reason
1319 # `adapter` was: no positional construction site is re-bound.
1320 temperature: float | None = None
1322 def __post_init__(self) -> None:
1323 # The single normalisation point. Every construction site — `_from_dict`,
1324 # `runagent`'s built-in templates, `cli`'s ad-hoc local seat, a test —
1325 # goes through it, so no reader downstream can be handed the raw form.
1326 self.vendor = normalise_vendor(self.vendor)
1327 tier = str(self.tier).strip().lower() if isinstance(self.tier, str) else ""
1328 self.tier = tier if tier in KNOWN_TIERS else DEFAULT_TIER
1329 # Same treatment for the adapter, and for the same reason (#701 r3):
1330 # `adapter = "CLI"` and `adapter = "cli"` name one protocol, so they must
1331 # be one string before any lookup sees them. A key that is *present* but
1332 # normalises to nothing — `7`, `" "` — is refused here rather than read
1333 # as "unset": `validate_config` already calls it an unknown adapter, and a
1334 # caller of `load_config` (default `validate=False`) or of `make_adapter`
1335 # builds seats without validating, so treating it as a fallback to the
1336 # vendor let that path run what validation refused.
1337 if self.adapter is not None:
1338 key = normalise_vendor(self.adapter)
1339 if not key:
1340 raise ConfigError(
1341 unknown_adapter_error(self.adapter, self.name)
1342 or f"agent {self.name!r}: adapter {self.adapter!r} names no protocol"
1343 )
1344 self.adapter = key
1346 @property
1347 def adapter_key(self) -> str:
1348 """The adapter name this seat resolves to — its ``adapter`` or its vendor."""
1349 return adapter_key(self.vendor, self.adapter)
1352@dataclass
1353class CiConfig:
1354 fail_on: list[str] = field(default_factory=lambda: ["critical", "major"])
1355 ignore_unverified: bool = True
1356 # Distinct vendors that must have CONTRIBUTED a review before the run is
1357 # allowed to stand as cross-vendor consensus (issue #682). Fails closed at
1358 # 2: the product claim is a cross-vendor jury, and a panel that collapsed to
1359 # one vendor is a different thing wearing the same output. Only applies when
1360 # the run claimed consensus in the first place — a panel with fewer distinct
1361 # vendors enabled than this is never failed by the default (see
1362 # ``metadata.collapse_reason``). ``0`` disables the guard entirely.
1363 min_vendors: int = DEFAULT_MIN_VENDORS
1364 # REVIEWS the run must be able to hand a downstream consumer before it is
1365 # worth running at all (issue #699) — one per ballot that *reviewed*, i.e.
1366 # ``panel.is_review``: a substantive scope and a voting verdict, so an
1367 # abstention is not one (#700). That is the
1368 # number a gate like `keel review --from-jury` counts: it splits the
1369 # ``reviewers`` array on ``role`` and reads the ``chair`` entry as the
1370 # panel's consensus, not as a review. ``0`` (the default)
1371 # disables it: most consumers have no minimum, and a gate that fails closed
1372 # here would break every single-agent install. Set it to what your consumer
1373 # requires and the shortfall is named before the panel runs, instead of after
1374 # the review has already been paid for.
1375 #
1376 # Deliberately NOT in ``config_hash`` (unlike ``min_vendors``): it changes
1377 # neither the orchestration nor what the panel finds, only whether the
1378 # resulting bundle is accepted, and it is re-evaluated on every run including
1379 # a cache hit — so a cached outcome cannot smuggle a shortfall past it, and
1380 # adding it would invalidate every existing cache entry for nothing.
1381 min_reviews: int = 0
1384@dataclass
1385class ContextConfig:
1386 mode: str = "diff-only" # "diff-only" or "expanded"
1387 redact_secrets: bool = True
1390@dataclass
1391class DiffConfig:
1392 """Large-diff handling policy (issue #31).
1394 ``max_bytes`` is the size (UTF-8 bytes, measured after filtering) above which
1395 a diff is either chunked or rejected. ``chunk`` enables per-file chunking;
1396 ``chunk_max_bytes`` bounds each chunk (defaults to ``max_bytes``).
1397 ``exclude_generated`` drops binary and common generated/vendored files;
1398 ``exclude``/``include`` are extra path-glob deny/allow lists.
1399 """
1401 max_bytes: int = 200_000
1402 chunk: bool = False
1403 chunk_max_bytes: int | None = None
1404 exclude_generated: bool = True
1405 exclude: list[str] = field(default_factory=list)
1406 include: list[str] = field(default_factory=list)
1409@dataclass
1410class OutputConfig:
1411 """The markdown report's footer (issue #911).
1413 ``attribution`` keeps the ai-jury footer that ends the markdown report and
1414 every comment ``jury`` posts, now naming the seats that returned a review.
1415 ``False`` removes it. Rendering-only, so it is not in ``config_hash``.
1416 """
1418 attribution: bool = True
1421#: Known keys inside each nested ``[jury.*]`` table (issue #719).
1422#:
1423#: Every one is DERIVED from the dataclass the matching ``*_from_dict`` reader
1424#: builds, rather than written out a second time, so a new field cannot be added
1425#: to ``CiConfig``/``ContextConfig``/``DiffConfig`` and leave this list behind —
1426#: which is how the top-level ``KNOWN_JURY_KEYS`` list has drifted before (#715).
1427#: The readers happen to accept exactly their dataclass's field names and no
1428#: aliases; ``tests/test_config_validation.py`` pins each tuple to the keys its
1429#: reader actually reads, so an alias added later must be added here too.
1430#:
1431#: These live here, below the dataclasses, rather than beside ``KNOWN_JURY_KEYS``
1432#: because deriving them needs the classes to exist. ``validate_config`` reads
1433#: them at call time, so the ordering in the module is not a problem.
1434KNOWN_CI_KEYS = tuple(f.name for f in dataclass_fields(CiConfig))
1435KNOWN_CONTEXT_KEYS = tuple(f.name for f in dataclass_fields(ContextConfig))
1436KNOWN_DIFF_KEYS = tuple(f.name for f in dataclass_fields(DiffConfig))
1437KNOWN_OUTPUT_KEYS = tuple(f.name for f in dataclass_fields(OutputConfig))
1439#: The nested ``[jury.*]`` tables ``_from_dict`` reads, and the keys each one
1440#: knows. ``ci``/``context``/``diff``/``output`` are the complete set: every other member of
1441#: ``KNOWN_JURY_KEYS`` is a scalar (``theater`` is a bool, ``routing`` a string),
1442#: so there is no other sub-table for a typo to disappear into.
1443KNOWN_NESTED_JURY_KEYS: dict[str, tuple[str, ...]] = {
1444 "ci": KNOWN_CI_KEYS,
1445 "context": KNOWN_CONTEXT_KEYS,
1446 "diff": KNOWN_DIFF_KEYS,
1447 "output": KNOWN_OUTPUT_KEYS,
1448}
1451@dataclass
1452class JuryConfig:
1453 rounds: int = 2
1454 chair: str = "claude"
1455 timeout: int = 600
1456 parallel: bool = True
1457 verify: bool = True
1458 agents: list[AgentSpec] = field(default_factory=list)
1459 ci: CiConfig = field(default_factory=CiConfig)
1460 context: ContextConfig = field(default_factory=ContextConfig)
1461 diff: DiffConfig = field(default_factory=DiffConfig)
1462 # The markdown report's footer (issue #911).
1463 output: OutputConfig = field(default_factory=OutputConfig)
1464 # Optional run seed. Controls the shared run RNG used by randomized
1465 # orchestration features (see orchestrator.run_jury). LLM output itself
1466 # is never made deterministic by this; only the orchestration around it.
1467 seed: int | None = None
1468 # Anonymize peer reviews shown in the round-2 debate (Chatham House rule,
1469 # issue #37): strip vendor/agent identity, relabel as "Reviewer A/B/...",
1470 # and randomize per-debater presentation order via the shared run RNG so
1471 # neither identity nor position is a stable signal. The rendered report
1472 # still attributes findings by real name. Set False for the old
1473 # identity-labeled debate path.
1474 anonymize_debate: bool = True
1475 # Prefer a chair that was NOT a round-1 reviewer when a usable non-reviewer
1476 # is available (issue #38), mitigating chair self-preference bias. Has no
1477 # effect when chair == "rotate" (rotation already picks among usable agents)
1478 # or when an explicit usable chair name is configured.
1479 prefer_non_reviewer_chair: bool = False
1480 # Demote a finding to non-blocking severity when every reviewer who raised it
1481 # is vendor "local" and no cloud reviewer corroborates it (issue #442).
1482 # Rejected alternative: a numeric per-reviewer trust weight — this categorical
1483 # rule is auditable in one line where a coefficient invites silent drift.
1484 # Off by default so the out-of-the-box CI gate is unchanged.
1485 demote_local_only: bool = False
1486 # Execution controls (issue #30). All optional and off by default so the
1487 # out-of-the-box run is unchanged. ``total_timeout``/``phase_timeout`` cap the
1488 # whole run / a single phase (None = uncapped); the effective per-agent-call
1489 # timeout is the minimum of the agent timeout, the phase budget, and the
1490 # remaining total budget. ``retries`` is the number of EXTRA attempts for
1491 # transient (retryable) failures — 0 means try once.
1492 total_timeout: int | None = None
1493 phase_timeout: int | None = None
1494 retries: int = 0
1495 # Adaptive rounds (issue #40). When ``early_stop`` is True the orchestrator
1496 # decides whether to run the debate round(s) from the round-1 convergence
1497 # signal instead of always honouring a fixed ``rounds``: a unanimous panel
1498 # stops after round 1, and disagreement runs debate up to ``max_rounds``.
1499 # A CLI ``--rounds`` (or any explicit fixed-N intent) disables early stop so
1500 # benchmarking stays reproducible. ``max_rounds`` defaults to ``rounds``.
1501 max_rounds: int | None = None
1502 early_stop: bool = False
1503 # Risk-aware auto-depth (issue #120): when True, the CLI sets rounds/verify/
1504 # early_stop from a cheap pre-review diff profile (size/paths/security), so a
1505 # trivial diff runs shallow and a risky one runs full. Off by default; the
1506 # panel is never trimmed; explicit --rounds/--verify/--early-stop override it.
1507 auto_depth: bool = False
1508 # Full-transcript output (issue: full transcript). When True, the markdown
1509 # report defaults to the chronological play-by-play (each agent's raw review,
1510 # the debate, and the chair's reasoning) instead of the consensus-first
1511 # summary. Rendering-only: it does NOT affect orchestration, so it is
1512 # deliberately excluded from ``config_hash`` and the cache key. The CLI
1513 # ``--transcript``/``--no-transcript`` override it; ``--verbose`` is summary +
1514 # transcript in one document.
1515 transcript: bool = False
1516 # Final-verdict mode (issue #220): "chair" = the chair's synthesis is the
1517 # verdict (default, historical); "vote" = the panel verdict is a tally of the
1518 # reviewers (each votes from the worst finding they raised). Rendering-only —
1519 # it does not change orchestration, so it is excluded from ``config_hash`` and
1520 # the cache key. The chair still runs (its reasoning is shown as supporting
1521 # narrative), and the severity-based CI gate is unaffected. CLI: ``--decision``.
1522 decision: str = "chair"
1523 # Animated theater view defaults (issue #364). Rendering-only side channel —
1524 # excluded from ``config_hash`` and the cache key (it never touches the
1525 # outcome). ``theater`` defaults the scene on; ``theater_style`` is "flat"
1526 # (ANSI line scene) or "pixel" (pixel-art room). The CLI ``--theater`` /
1527 # ``--theater-style`` flags override these per run. Theater is TTY-only, so
1528 # even when defaulted on it falls back to ``--live`` off an interactive
1529 # terminal (and ``pixel`` falls back to ``flat`` without truecolor/unicode).
1530 theater: bool = False
1531 theater_style: str = "flat"
1532 # Risk-aware tiered model routing (issue #524): "standard" (uniform panel) |
1533 # "tiered" (cost-optimized with frontier anchor). Normalised on construction
1534 # like `AgentSpec.tier`, its companion key; an unknown value is refused by
1535 # `validate_config` and falls back to the default here so no reader carries a
1536 # spelling the vocabulary lacks (#747).
1537 routing: str = DEFAULT_ROUTING
1538 # Pre-pass static analysis hints (issue #523): inject linter hints into prompt context
1539 hints: bool = False
1540 # Pre-existing findings gating option (issue #976): "report" | "ignore".
1541 pre_existing: str = DEFAULT_PRE_EXISTING
1543 def __post_init__(self) -> None:
1544 # The single normalisation point for `routing`, for the reason
1545 # `AgentSpec.__post_init__` is one for `tier`: `_from_dict` is not the
1546 # only way a config is built — `--doctor` and `jury run-agent` load
1547 # without validating, and tests and programmatic callers construct
1548 # `JuryConfig` directly — and every one of those readers compares against
1549 # the literal "tiered". A value that survives to a reader unnormalised
1550 # takes the `standard` path while claiming to be something else.
1551 routing = str(self.routing).strip().lower() if isinstance(self.routing, str) else ""
1552 self.routing = routing if routing in KNOWN_ROUTINGS else DEFAULT_ROUTING
1553 pre_existing = (
1554 str(self.pre_existing).strip().lower() if isinstance(self.pre_existing, str) else ""
1555 )
1556 self.pre_existing = (
1557 pre_existing if pre_existing in KNOWN_PRE_EXISTINGS else DEFAULT_PRE_EXISTING
1558 )
1560 @property
1561 def effective_max_rounds(self) -> int:
1562 """Round ceiling for adaptive mode: ``max_rounds`` or ``rounds``."""
1563 return self.max_rounds if self.max_rounds is not None else self.rounds
1565 @property
1566 def enabled_agents(self) -> list[AgentSpec]:
1567 return [a for a in self.agents if a.enabled]
1570def default_chair(agents) -> str:
1571 """The chair a config that names none gets: its first ENABLED agent (pure).
1573 The one reader of the default (docs audit 2026-09-29), so validation and the
1574 run cannot disagree about it. A disabled first seat is skipped because it
1575 cannot chair; with no enabled seat the first seat stands (the run then falls
1576 back to the first usable agent), and with no seat at all ``claude``.
1577 """
1578 for agent in agents:
1579 if agent.enabled:
1580 return agent.name
1581 return agents[0].name if agents else "claude"
1584def _ci_from_dict(data: dict) -> CiConfig:
1585 # `ConfigError`, not the `AttributeError` a `.get` on a string would raise:
1586 # materialisation is reached WITHOUT validation whenever a caller uses
1587 # `load_config`'s default `validate=False` (a Python caller; `jury run-agent`
1588 # validates since #903), and such a caller can handle `ConfigError` where a
1589 # traceback would just be a crash (issue #729, following #716).
1590 if not isinstance(data, dict):
1591 raise ConfigError(_nested_table_message("ci"))
1592 fail_on = data.get("fail_on", ["critical", "major"])
1593 if not isinstance(fail_on, list):
1594 fail_on = [fail_on]
1595 fail_on = [str(s).strip().lower() for s in fail_on if str(s).strip()]
1596 return CiConfig(
1597 fail_on=fail_on,
1598 ignore_unverified=bool(data.get("ignore_unverified", True)),
1599 min_vendors=_non_negative_int(data.get("min_vendors"), DEFAULT_MIN_VENDORS),
1600 min_reviews=_non_negative_int(data.get("min_reviews"), 0),
1601 )
1604def _context_from_dict(data: dict) -> ContextConfig:
1605 if not isinstance(data, dict):
1606 raise ConfigError(_nested_table_message("context"))
1607 mode = str(data.get("mode", "diff-only")).strip().lower()
1608 if mode not in KNOWN_CONTEXT_MODES:
1609 mode = KNOWN_CONTEXT_MODES[0]
1610 return ContextConfig(mode=mode, redact_secrets=bool(data.get("redact_secrets", True)))
1613def _output_from_dict(data: dict) -> OutputConfig:
1614 if not isinstance(data, dict):
1615 raise ConfigError(_nested_table_message("output"))
1616 return OutputConfig(attribution=bool(data.get("attribution", True)))
1619def _str_list(value) -> list[str]:
1620 """Coerce a config value into a clean list of non-empty strings."""
1621 if isinstance(value, str):
1622 value = [value]
1623 if not isinstance(value, list):
1624 return []
1625 return [str(v).strip() for v in value if str(v).strip()]
1628def _diff_from_dict(data: dict) -> DiffConfig:
1629 if not isinstance(data, dict):
1630 raise ConfigError(_nested_table_message("diff"))
1631 default = DiffConfig()
1632 return DiffConfig(
1633 max_bytes=_opt_positive_int(data.get("max_bytes")) or default.max_bytes,
1634 chunk=bool(data.get("chunk", default.chunk)),
1635 chunk_max_bytes=_opt_positive_int(data.get("chunk_max_bytes")),
1636 exclude_generated=bool(data.get("exclude_generated", default.exclude_generated)),
1637 exclude=_str_list(data.get("exclude", [])),
1638 include=_str_list(data.get("include", [])),
1639 )
1642def _seed_from_dict(jury: dict) -> int | None:
1643 """Parse ``[jury] seed`` into an int, or None when absent/invalid.
1645 A non-integer or boolean seed is treated as "no seed" rather than an error:
1646 the seed only governs orchestration randomness, so a malformed value should
1647 degrade gracefully to the unseeded (still deterministic-orchestration) path.
1648 """
1649 raw = jury.get("seed")
1650 if raw is None or isinstance(raw, bool):
1651 return None
1652 try:
1653 return int(raw)
1654 except (TypeError, ValueError):
1655 return None
1658def _opt_positive_int(raw) -> int | None:
1659 """Coerce an optional positive-int config value, else None.
1661 Used for the optional execution budgets (issue #30) and ``max_rounds``
1662 (issue #40). A missing, boolean, non-numeric, or non-positive value degrades
1663 to None (uncapped) rather than raising, so ``_from_dict`` stays tolerant when
1664 called without validation; :func:`validate_config` is what reports the hard
1665 error for an explicit bad value.
1666 """
1667 if raw is None or isinstance(raw, bool):
1668 return None
1669 try:
1670 value = int(raw)
1671 except (TypeError, ValueError):
1672 return None
1673 return value if value > 0 else None
1676def _from_dict(data: dict) -> JuryConfig:
1677 jury = data.get("jury", {})
1678 # The top-level tables get the same treatment the nested ones got in #731: this
1679 # function is reached without validation on real paths (`jury run-agent`,
1680 # `load_config`'s default), and a scalar where a table was meant used to fall
1681 # through to `AttributeError` here instead of the `ConfigError` those callers
1682 # already handle (issue #732).
1683 if not isinstance(jury, dict):
1684 raise ConfigError(_JURY_NOT_A_TABLE)
1685 agents_raw = data.get("agent", [])
1686 if not isinstance(agents_raw, list):
1687 raise ConfigError(_AGENTS_NOT_AN_ARRAY)
1688 default_timeout = int(jury.get("timeout", 600))
1689 agents: list[AgentSpec] = []
1690 for idx, raw in enumerate(agents_raw):
1691 if not isinstance(raw, dict):
1692 raise ConfigError(_agent_not_a_table_message(idx))
1693 # `headers` no longer coerces a non-table to `{}` (issue #716). That
1694 # coercion is what made the mistake invisible: the seat materialised
1695 # cleanly carrying no headers, and only the remote API — or nobody —
1696 # ever noticed.
1697 #
1698 # It raises `ConfigError` rather than falling through to an
1699 # `AttributeError` from `.items()`, because materialisation is reached
1700 # WITHOUT validation whenever a caller uses `load_config`'s default
1701 # `validate=False` (review r1) — a Python caller; `jury run-agent`
1702 # validates since #903. Such a caller can handle `ConfigError`, and an
1703 # uncaught traceback would be a regression for it, not a fix.
1704 # The messages are the shared builders, so the two paths say the same
1705 # thing and neither echoes the value.
1706 #
1707 # A non-string VALUE is coerced, as before, and warned about in
1708 # `validate_config`: `X-Retries = 3` is a header that works.
1709 headers_label = raw.get("name") or f"agent[{len(agents)}]"
1710 raw_headers = raw.get("headers", {})
1711 if not isinstance(raw_headers, dict):
1712 raise ConfigError(_headers_not_a_table_message(headers_label, raw_headers))
1713 for key in raw_headers:
1714 if not isinstance(key, str):
1715 raise ConfigError(_headers_bad_key_message(headers_label, key))
1716 headers_dict = {k: str(v) for k, v in raw_headers.items()}
1717 api_key_env_val = str(raw["api_key_env"]) if raw.get("api_key_env") else None
1718 prompt_mode_val = str(raw["prompt_mode"]) if raw.get("prompt_mode") else None
1719 raw_effort = raw.get("effort")
1720 effort_val = str(raw_effort).strip().lower() if isinstance(raw_effort, str) else None
1721 raw_tier = raw.get("tier")
1722 tier_val = str(raw_tier).strip().lower() if isinstance(raw_tier, str) else ""
1723 # An invalid value is refused by `validate_config`; here it reads as
1724 # unset, like an unknown `effort`, so this reader never carries it.
1725 raw_temperature = raw.get("temperature")
1726 temperature_val = float(raw_temperature) if is_valid_temperature(raw_temperature) else None
1727 agents.append(
1728 AgentSpec(
1729 name=raw["name"],
1730 # Passed through raw on purpose: `AgentSpec.__post_init__` is the
1731 # one place that normalises a vendor, so normalising here as well
1732 # would create a second place to keep in step (issue #701, r3).
1733 vendor=raw.get("vendor", "unknown"),
1734 # ``command`` is optional for local/HTTP agents (issue #43).
1735 command=raw.get("command", ""),
1736 model=raw.get("model"),
1737 timeout=int(raw.get("timeout", default_timeout)),
1738 enabled=bool(raw.get("enabled", True)),
1739 extra_args=list(raw.get("extra_args", [])),
1740 endpoint=raw.get("endpoint"),
1741 api_key_env=api_key_env_val,
1742 prompt_mode=prompt_mode_val,
1743 headers=headers_dict,
1744 effort=effort_val or None,
1745 tier=tier_val or DEFAULT_TIER,
1746 # Raw, like `vendor`: `AgentSpec.__post_init__` normalises both,
1747 # and a second normalisation here would be a second place to keep
1748 # in step (issue #701 r3, extended by #705).
1749 adapter=raw.get("adapter"),
1750 temperature=temperature_val,
1751 )
1752 )
1753 return JuryConfig(
1754 rounds=int(jury.get("rounds", 2)),
1755 chair=jury.get("chair", default_chair(agents)),
1756 timeout=default_timeout,
1757 parallel=bool(jury.get("parallel", True)),
1758 verify=bool(jury.get("verify", True)),
1759 agents=agents,
1760 ci=_ci_from_dict(jury.get("ci", {})),
1761 context=_context_from_dict(jury.get("context", {})),
1762 diff=_diff_from_dict(jury.get("diff", {})),
1763 output=_output_from_dict(jury.get("output", {})),
1764 seed=_seed_from_dict(jury),
1765 anonymize_debate=bool(jury.get("anonymize_debate", True)),
1766 prefer_non_reviewer_chair=bool(jury.get("prefer_non_reviewer_chair", False)),
1767 demote_local_only=bool(jury.get("demote_local_only", False)),
1768 total_timeout=_opt_positive_int(jury.get("total_timeout")),
1769 phase_timeout=_opt_positive_int(jury.get("phase_timeout")),
1770 retries=max(0, int(jury.get("retries", 0) or 0)),
1771 max_rounds=_opt_positive_int(jury.get("max_rounds")),
1772 early_stop=bool(jury.get("early_stop", False)),
1773 auto_depth=bool(jury.get("auto_depth", False)),
1774 transcript=bool(jury.get("transcript", False)),
1775 decision=(str(jury.get("decision", "chair")).strip().lower() or "chair"),
1776 theater=bool(jury.get("theater", False)),
1777 theater_style=(str(jury.get("theater_style", "flat")).strip().lower() or "flat"),
1778 # Passed through raw on purpose, like `AgentSpec`'s `vendor`:
1779 # `JuryConfig.__post_init__` is the one place that normalises a routing
1780 # kind, so normalising here as well would create a second place to keep
1781 # in step (#747).
1782 routing=jury.get("routing", DEFAULT_ROUTING),
1783 hints=bool(jury.get("hints", False)),
1784 pre_existing=(
1785 str(jury.get("pre_existing", DEFAULT_PRE_EXISTING)).strip().lower()
1786 or DEFAULT_PRE_EXISTING
1787 ),
1788 )
1791def config_hash(config: JuryConfig) -> str:
1792 """Return a stable SHA-256 hash of the EFFECTIVE jury configuration.
1794 The hash is a function of the resolved configuration only (no timestamps,
1795 no diff text), so the same config always produces the same digest and a
1796 changed config produces a different one. This anchors reproducibility
1797 metadata: two runs with an identical config hash were orchestrated under
1798 identical settings.
1800 The seed is intentionally excluded so the hash describes the *configuration*
1801 independent of which run seed was chosen; the seed is recorded separately in
1802 run metadata.
1803 """
1804 import hashlib
1805 import json
1807 canonical = {
1808 "rounds": config.rounds,
1809 "chair": config.chair,
1810 "timeout": config.timeout,
1811 "parallel": config.parallel,
1812 "verify": config.verify,
1813 "total_timeout": config.total_timeout,
1814 "phase_timeout": config.phase_timeout,
1815 "retries": config.retries,
1816 "max_rounds": config.max_rounds,
1817 "early_stop": config.early_stop,
1818 "auto_depth": config.auto_depth,
1819 # Orchestration-affecting toggles (issue #122): both change how a run is
1820 # conducted, so the "same hash ⇒ same orchestration" promise must include
1821 # them.
1822 "anonymize_debate": config.anonymize_debate,
1823 "prefer_non_reviewer_chair": config.prefer_non_reviewer_chair,
1824 "demote_local_only": config.demote_local_only,
1825 # The static-analysis pre-pass changes what Round 1 is shown, and the
1826 # routing mode changes which models the panel is built from, so two runs
1827 # that disagree about either are not the same run and must not share a
1828 # cache entry (#715). Like `min_vendors` before them, adding these keys
1829 # invalidates every existing review cache entry ONCE on upgrade — noted
1830 # in the CHANGELOG, since a user's first run after the bump is a full one.
1831 "hints": config.hints,
1832 "routing": config.routing,
1833 # `pre_existing` is deliberately omitted from `config_hash` (like
1834 # `ci.min_reviews` and `decision`): it changes neither orchestration nor
1835 # what the panel finds, only the post-review `evaluate_ci` gate, which
1836 # runs on cached outcomes too (#976).
1837 "ci": {
1838 "fail_on": list(config.ci.fail_on),
1839 "ignore_unverified": config.ci.ignore_unverified,
1840 # `min_vendors` belongs here for the same reason the other two do: it
1841 # decides the outcome of a run, so two runs that disagree about it are
1842 # not the same run. Adding it invalidates every existing review cache
1843 # entry ONCE on upgrade — noted in the CHANGELOG, since a user's first
1844 # run after the bump is a full one.
1845 "min_vendors": config.ci.min_vendors,
1846 },
1847 "context": {
1848 "mode": config.context.mode,
1849 "redact_secrets": config.context.redact_secrets,
1850 },
1851 "diff": {
1852 "max_bytes": config.diff.max_bytes,
1853 "chunk": config.diff.chunk,
1854 "chunk_max_bytes": config.diff.chunk_max_bytes,
1855 "exclude_generated": config.diff.exclude_generated,
1856 "exclude": list(config.diff.exclude),
1857 "include": list(config.diff.include),
1858 },
1859 "agents": [
1860 {
1861 "name": a.name,
1862 "vendor": a.vendor,
1863 "command": a.command,
1864 "endpoint": a.endpoint,
1865 "model": a.model,
1866 "timeout": a.timeout,
1867 "enabled": a.enabled,
1868 "extra_args": list(a.extra_args),
1869 # Effort changes the model id / request body an agent sends, so
1870 # it is orchestration-affecting and must split the cache key.
1871 "effort": a.effort,
1872 # The adapter decides which command line is built, so two seats
1873 # that differ only in it are not the same run and must not share
1874 # a cache entry (issue #705). Present ONLY when it differs from
1875 # the vendor: a seat with no `adapter`, or one naming its own
1876 # vendor, means exactly what it meant before this key existed, so
1877 # its canonical payload — and therefore every existing cache
1878 # entry — stays byte-identical. The conditional is the point,
1879 # not an optimisation: this change invalidates no one's cache.
1880 **({"adapter": a.adapter_key} if a.adapter_key != a.vendor else {}),
1881 # The tier decides which seats a routed panel keeps, so two
1882 # benches that differ in it are not the same run (issue #714).
1883 # Conditional for the reason `adapter` is: a seat with no `tier`
1884 # means exactly what it meant before the key existed, so every
1885 # existing cache entry stays byte-identical.
1886 **({"tier": a.tier} if a.tier != DEFAULT_TIER else {}),
1887 # How the prompt reaches the seat: piped to stdin, or appended to
1888 # argv as the last argument (issue #746). That is the invocation
1889 # protocol, so a cached outcome produced under one must not be
1890 # served for a run configured with the other — the rule that put
1891 # `adapter` here, one field along. Conditional for the reason
1892 # `adapter` is: `None` and `""` both mean the `stdin` fallback in
1893 # `GenericCLIAdapter._prompt_mode`, which is what a config that never
1894 # named the key has always meant, so its canonical payload — and
1895 # therefore every existing cache entry — stays byte-identical.
1896 #
1897 # The test is "was it written", not "does it resolve to something
1898 # other than the default", which is where this parts company with
1899 # `adapter` and `tier`: an explicit `prompt_mode = "stdin"`, or an
1900 # `"ARG"` beside an `"arg"`, splits the key even though the seat is
1901 # invoked identically. Deliberate. Unlike those two, this field is
1902 # neither validated nor normalised on construction, so folding
1903 # spellings together here would put a second, more precise reader
1904 # of the vocabulary next to the adapter's own — the duplication
1905 # #701 r3 removed. The cost is one extra run for a config that
1906 # writes the default out longhand; the alternative is a stale hit.
1907 **({"prompt_mode": a.prompt_mode} if a.prompt_mode else {}),
1908 # Where the request goes and under whose key (issue #716). A
1909 # provider-routing header — `X-Route: premium`, an OpenRouter
1910 # `HTTP-Referer`, an Azure deployment selector — can put a
1911 # byte-identical seat in front of a different model, and
1912 # `api_key_env` can put it in front of a different account. Both
1913 # are therefore orchestration-affecting under the same rule as
1914 # `min_vendors` above, and two configs that disagree about
1915 # either are not the same run.
1916 #
1917 # Unconditional, unlike `adapter`: there is no spelling of these
1918 # keys that means "what it meant before", so this DOES invalidate
1919 # every existing review cache entry once on upgrade. That is the
1920 # honest price of a key that was wrong, and it is noted in the
1921 # CHANGELOG — the user's first run after the bump is a full one.
1922 # Sorted so the digest depends on the mapping, not on the order
1923 # the table happened to be written in.
1924 "api_key_env": a.api_key_env,
1925 "headers": sorted(a.headers.items()),
1926 # The sampling temperature changes what a local seat answers —
1927 # at 0 gpt-oss returns nothing, at 1 a review — so a cached
1928 # outcome from one must not serve the other. Conditional for the
1929 # reason `tier` is: an unset key means what it meant before it
1930 # existed, so every existing cache entry stays byte-identical.
1931 **({"temperature": a.temperature} if a.temperature is not None else {}),
1932 }
1933 for a in config.agents
1934 ],
1935 }
1936 payload = json.dumps(canonical, sort_keys=True, separators=(",", ":"))
1937 return hashlib.sha256(payload.encode("utf-8")).hexdigest()
1940def load_raw_config(path: str | Path | None = None) -> dict:
1941 """Return the raw config dict for *path*, or the built-in default.
1943 If *path* is None, look for ``jury.toml`` in the current directory and
1944 fall back to :data:`DEFAULT_CONFIG` when it is absent. An explicit *path*
1945 that does not exist raises ``FileNotFoundError``.
1946 """
1947 if path is None:
1948 candidate = Path("jury.toml")
1949 if not candidate.exists():
1950 return DEFAULT_CONFIG
1951 path = candidate
1952 path = Path(path)
1953 if not path.exists():
1954 raise FileNotFoundError(f"Config not found: {path}")
1955 return _read_toml_bounded(path)
1958def load_config(
1959 path: str | Path | None = None,
1960 validate: bool = False,
1961 strict: bool = False,
1962) -> JuryConfig:
1963 """Load jury config from *path*, or fall back to the built-in default.
1965 If *path* is None, look for ``jury.toml`` in the current directory.
1967 When *validate* is True, the resolved config dict is checked with
1968 :func:`validate_config` before being materialized; a ``ConfigError`` is
1969 raised on hard-invalid input (and on warnings when *strict* is True).
1970 Validation is opt-in so existing callers stay unaffected.
1971 """
1972 data = load_raw_config(path)
1973 if validate:
1974 validate_config(data, strict=strict)
1975 return _from_dict(data)