Coverage for src/ai_jury/adapters.py: 98%
862 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"""Agent adapters — each wraps one native coding-agent CLI in headless mode.
3Every adapter turns a prompt into a subprocess invocation and captures stdout as
4the agent's response. Adapters are intentionally thin: the orchestrator owns the
5prompt content and the round structure; an adapter only knows how to *invoke its
6CLI*.
8Headless invocations (verified against installed CLIs, early 2026). The prompt
9embeds the redacted diff, so it is delivered on STDIN (never argv) for every
10real adapter so it is not exposed in the process list (issue #287):
11 - Claude Code : ``claude -p --output-format text`` (prompt piped via stdin)
12 - Codex CLI : ``codex exec <args>`` (prompt piped via stdin)
13 - Antigravity : ``agy --print`` (prompt piped via stdin)
14"""
16from __future__ import annotations
18import contextlib
19import errno
20import json
21import os
22import re
23import shutil
24import signal
25import subprocess
26import tempfile
27import time
28from dataclasses import dataclass, field
30from . import config as config_module
31from . import privilege, redaction
32from .config import AgentSpec
33from .findings import emitted_findings_block
35# Cap on a single local-model HTTP response body (issue #293/F-9). A chat
36# completion is small; an unbounded read from a malicious/buggy endpoint would
37# let it OOM the process.
38_MAX_RESPONSE_BYTES = 16 * 1024 * 1024
41def _kill_process_group(proc: subprocess.Popen) -> None:
42 """Best-effort kill of the child's whole process group (issue #293/F-7)."""
43 if hasattr(os, "killpg"): 43 ↛ 47line 43 didn't jump to line 47 because the condition on line 43 was always true
44 with contextlib.suppress(ProcessLookupError, PermissionError, OSError):
45 os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
46 return
47 with contextlib.suppress(OSError):
48 proc.kill()
51def _spawn(
52 argv: list[str], stdin: str | None, timeout: int, cwd: str | None = None
53) -> subprocess.CompletedProcess:
54 """Run a CLI with stdout/stderr captured, killing the whole group on timeout.
56 ``subprocess.run(timeout=…)`` SIGKILLs only the direct child, so an agent CLI
57 that wraps node/python can leak orphaned grandchildren (issue #293/F-7). The
58 child is started in its own session (process-group leader); on timeout the
59 entire group is killed before re-raising ``TimeoutExpired`` so the caller's
60 handling is unchanged. ``cwd`` starts the child somewhere other than this
61 process's working directory (see :func:`_review_workdir`). Returns a
62 ``CompletedProcess``.
63 """
64 popen_kwargs: dict = {
65 "stdin": subprocess.PIPE if stdin is not None else None,
66 "stdout": subprocess.PIPE,
67 "stderr": subprocess.PIPE,
68 "text": True,
69 }
70 if cwd is not None:
71 popen_kwargs["cwd"] = cwd
72 if hasattr(os, "setsid"): 72 ↛ 74line 72 didn't jump to line 74 because the condition on line 72 was always true
73 popen_kwargs["start_new_session"] = True
74 proc = subprocess.Popen(argv, **popen_kwargs)
75 try:
76 out, err = proc.communicate(input=stdin, timeout=timeout)
77 except subprocess.TimeoutExpired:
78 _kill_process_group(proc)
79 with contextlib.suppress(Exception):
80 proc.communicate() # reap the killed child
81 raise
82 return subprocess.CompletedProcess(argv, proc.returncode, out, err)
85@contextlib.contextmanager
86def _review_workdir(isolate: bool):
87 """A fresh, empty directory for one reviewer process, removed afterwards.
89 Yields ``None`` — "inherit this process's directory" — when ``isolate`` is
90 false. Otherwise the reviewer starts outside the repository under review, so
91 whatever that repository carries for the agent CLI to pick up on its own is
92 out of reach: instruction files (``CLAUDE.md``, ``AGENTS.md``), project
93 settings with hooks or MCP servers (``.claude/settings.json``, ``.mcp.json``),
94 and the relative path to a ``.env``. On a PR checkout every one of those is
95 the author's, and a reviewer needs none of them — its prompt carries the diff.
97 Cleanup ignores errors, so a file the CLI left behind can never turn a
98 finished review into a failure; the directory is created per call, so two
99 seats running in parallel never share one.
100 """
101 if not isolate:
102 yield None
103 return
104 with tempfile.TemporaryDirectory(prefix="ai-jury-review-", ignore_cleanup_errors=True) as path:
105 yield path
108def _read_only_extra_args(spec: AgentSpec) -> list[str]:
109 """The agent's ``extra_args`` with the read-only sandbox added when none is named.
111 Enforced at the adapter layer (issue #288) so an **empty** ``extra_args`` cannot
112 produce a write-capable reviewer of an attacker-controlled diff. It injects; it
113 does not override. A config that names its own sandbox keeps it — ``-s
114 workspace-write`` is passed through as written — codex's bypass flags are passed
115 through too, and the ``cli``/``xai`` adapters have no enforcement at all. Those
116 are the cases :func:`ai_jury.privilege.audit_agent` reports and ``--strict``
117 fails on (#750); this function is not the guarantee on its own.
118 """
119 # Keyed on the ADAPTER, not the vendor (issue #705): the sandbox flag is a
120 # property of the CLI being spawned, not of whose model answers. A seat with
121 # `vendor = "openai", adapter = "cli", command = "cursor-agent"` must not have
122 # codex's `-s read-only` spliced into an unrelated binary.
123 return privilege.enforce_read_only(config_module.spec_adapter(spec), spec.extra_args)
126def _write_extra_args(spec: AgentSpec) -> list[str]:
127 """The agent's ``extra_args`` with its vendor write/tool mode enabled (#661).
129 Reached ONLY from ``jury run-agent --role implement|fix --allow-write``, via
130 :meth:`Adapter.build_write_argv`. Nothing on the panel path calls it.
131 """
132 return privilege.enable_write(config_module.spec_adapter(spec), spec.extra_args)
135# Short timeout for capability/version probes. Detection is best-effort and must
136# never slow down or block a normal run, so probes are deliberately snappy.
137_VERSION_PROBE_TIMEOUT = 10
139# Matches a version-looking token, e.g. "1.2", "1.2.3", "v0.45.1".
140_VERSION_RE = re.compile(r"\d+\.\d+(?:\.\d+)?")
142# Capability/version probe statuses.
143CAP_OK = "ok"
144CAP_UNKNOWN_VERSION = "unknown_version"
145CAP_UNAVAILABLE = "unavailable"
147# Stable, typed error taxonomy for failed agent executions. These codes let
148# reports and CI/policy distinguish retryable from non-retryable failures
149# instead of pattern-matching free-text error strings.
150ERR_MISSING_CLI = "missing_cli"
151ERR_AUTH_REQUIRED = "auth_required"
152ERR_PERMISSION_PROMPT = "permission_prompt"
153ERR_TIMEOUT = "timeout"
154ERR_NONZERO_EXIT = "nonzero_exit"
155ERR_EMPTY_OUTPUT = "empty_output"
156ERR_SPAWN_FAILED = "spawn_failed"
157ERR_RATE_LIMITED = "rate_limited"
158# The account's usage / quota allowance is spent (issue #975): codex "You've hit
159# your usage limit ... try again at 3:40 PM", agy/Gemini "RESOURCE_EXHAUSTED ...
160# Resets in 34h". Unlike ERR_RATE_LIMITED (a burst limit that clears in seconds)
161# this clears in hours or days, so it is deliberately NOT in
162# RETRYABLE_ERROR_CODES: a retry only burns the backoff before failing again.
163ERR_QUOTA_EXHAUSTED = "quota_exhausted"
164# Local/HTTP adapter could not reach its server (issue #43): connection refused,
165# DNS failure, or the local model server is not running.
166ERR_CONNECTION = "connection_error"
167# Hosted-API adapter (issue #430): the vendor's API key env var is unset. Distinct
168# from ERR_AUTH_REQUIRED (a key was sent but the server rejected it) so a report
169# can tell "never configured" apart from "misconfigured/expired/revoked".
170ERR_MISSING_API_KEY = "missing_api_key"
171# Hosted-API adapter (issue #430): the configured key contains a control
172# character and was rejected BEFORE being sent as a header, rather than
173# letting http.client raise (and risk echoing a transformed/escaped copy of
174# the secret in its exception text — see _HostedApiAdapter._invalid_key_reason).
175ERR_INVALID_API_KEY = "invalid_api_key"
176# The agent exited 0 and printed something, but that something is not a review
177# (issue #682): a refusal, or the CLI's own usage/argument-error/version banner
178# echoed back because the invocation never reached the model. Distinct from
179# ERR_EMPTY_OUTPUT (nothing at all on stdout) so a report can tell "the CLI is
180# broken/misinvoked" apart from "the model declined", and distinct from ok=True
181# so neither can be counted as a vendor that contributed to consensus. #635 is
182# the shape: `agy` passed every availability probe, printed an argument error,
183# and the panel silently became single-vendor.
184ERR_NO_REVIEW = "no_review"
185ERR_UNKNOWN = "unknown"
187ERROR_CODES = frozenset(
188 {
189 ERR_MISSING_CLI,
190 ERR_AUTH_REQUIRED,
191 ERR_PERMISSION_PROMPT,
192 ERR_TIMEOUT,
193 ERR_NONZERO_EXIT,
194 ERR_EMPTY_OUTPUT,
195 ERR_SPAWN_FAILED,
196 ERR_RATE_LIMITED,
197 ERR_QUOTA_EXHAUSTED,
198 ERR_CONNECTION,
199 ERR_MISSING_API_KEY,
200 ERR_INVALID_API_KEY,
201 ERR_NO_REVIEW,
202 ERR_UNKNOWN,
203 }
204)
206# Failures that are worth retrying because they are typically transient (issue
207# #30): a timeout, a rate-limit, a process that failed to spawn, or a local
208# server that was briefly unreachable (#43). Auth, missing-CLI,
209# permission-prompt, empty-output, and generic nonzero-exit are treated as
210# deterministic — retrying them just burns time and tokens. So is a
211# no-review output: a misinvoked CLI prints the same usage banner every time.
212RETRYABLE_ERROR_CODES = frozenset(
213 {
214 ERR_TIMEOUT,
215 ERR_RATE_LIMITED,
216 ERR_SPAWN_FAILED,
217 ERR_CONNECTION,
218 }
219)
222# Ordered keyword groups for classify_stderr. Each keyword is matched on word
223# boundaries (\b...\b) so incidental substrings do NOT trigger a false
224# classification: bare "auth" matches "auth error" but not "author identity",
225# and "login" matches "login required" but not "login_attempts" ("_" is a word
226# char, so there is no boundary inside "login_attempts"). Multi-word phrases
227# tolerate a space OR "_" between tokens (e.g. "rate limit"/"rate_limit").
228def _keyword_pattern(*keywords: str) -> re.Pattern[str]:
229 parts = [r"[ _]+".join(re.escape(tok) for tok in kw.split()) for kw in keywords]
230 return re.compile(r"\b(?:" + "|".join(parts) + r")\b")
233# Order matters: auth and rate-limit signals are checked before the generic
234# permission and nonzero-exit fallbacks.
235_AUTH_RE = _keyword_pattern(
236 "not authenticated",
237 "unauthenticated",
238 "authentication",
239 "unauthorized",
240 "api key",
241 "auth",
242 "log in",
243 "login",
244 "credential",
245 "credentials",
246)
247# Checked BEFORE the rate-limit group (#975): these would otherwise be swallowed
248# by the bare "quota" keyword and retried for a reset that is hours away. A bare
249# "quota exceeded" stays rate_limited (often a per-minute quota).
250_QUOTA_EXHAUSTED_RE = _keyword_pattern(
251 "usage limit",
252 "resource exhausted",
253 "exceeded your current quota",
254 "out of credits",
255 "insufficient quota",
256 "insufficient credits",
257)
258_RATE_LIMIT_RE = _keyword_pattern("rate limit", "429", "quota", "too many requests")
259_PERMISSION_RE = _keyword_pattern(
260 "permission",
261 "permissions",
262 "approve",
263 "approval",
264 "confirm",
265 "confirmation",
266)
269def classify_stderr(returncode: int, stderr: str) -> str:
270 """Classify a nonzero-exit failure into a typed error code from its stderr.
272 Token-aware matching against the lowercased stderr: each keyword group is a
273 word-boundary regex, so incidental substrings (e.g. "author" containing
274 "auth") never cause a misclassification. Ordering matters (auth and
275 rate-limit signals are checked before the generic permission and
276 nonzero-exit fallbacks). Returns one of the ``ERR_*`` codes.
277 """
278 text = (stderr or "").lower()
279 if _AUTH_RE.search(text):
280 return ERR_AUTH_REQUIRED
281 if _QUOTA_EXHAUSTED_RE.search(text):
282 return ERR_QUOTA_EXHAUSTED
283 if _RATE_LIMIT_RE.search(text):
284 return ERR_RATE_LIMITED
285 if _PERMISSION_RE.search(text):
286 return ERR_PERMISSION_PROMPT
287 del returncode
288 return ERR_NONZERO_EXIT
291# --- "Exit 0, but nothing reviewable came back" (issue #682) ------------------
292#
293# A CLI that exits 0 and prints its own usage text is indistinguishable, to
294# everything downstream, from a reviewer that read the diff — the run stays
295# fail-soft and the panel quietly loses a vendor (#635). These patterns turn
296# that into a typed failure at the adapter boundary, on SHAPE alone: never on
297# whether a review is any good, only on whether it is a review at all.
299#: An output longer than this is treated as a review even if it opens with a
300#: refusal-shaped sentence. A real review that mentions "I cannot verify X"
301#: mid-argument must never be discarded; an actual refusal is a short paragraph.
302_NO_REVIEW_MAX_CHARS = 600
304#: How much of the output is examined for a usage/argument-error banner. A CLI
305#: that is going to print one prints it first.
306_NO_REVIEW_HEAD_CHARS = 400
308# The #635 class: the launcher rejected the argv, so the model was never
309# reached. Every one of these is text a CLI writes about ITSELF — and the whole
310# difficulty is that a review may *talk about* the same words. "Usage of int()
311# is unsafe" and "Invalid argument passed to calculate_total()" are findings,
312# not banners, and discarding either costs a panelist and (with the guard
313# failing closed) can collapse the panel. So each pattern below is matched
314# against a whole line, and every branch is bounded the way the refusal branch
315# already is: a banner is short, or it is corroborated by banner structure.
317#: A launcher's own usage line, as a whole line. Prose that merely opens with
318#: the word "usage" does not match: the line must go on to look like a synopsis
319#: (a colon, or a bracketed/flag-shaped operand).
320_USAGE_LINE_RE = re.compile(
321 r"usage:\s*\S" # "Usage: agy [options] [prompt]"
322 r"|usage\s+of\s+\S+:$" # Go's flag package: "Usage of ./agy:"
323 r"|usage\s+\S+\s+[\[<-]", # "usage agy [options]"
324 re.IGNORECASE,
325)
327#: Text only a launcher writes about itself — it complains about the argv it
328#: was handed, in the first person of a program. Needs no corroboration beyond
329#: opening a short output.
330_CLI_SELF_ERROR_RE = re.compile(
331 r"(?:error|fatal)\s*:\s*(?:unknown|unrecognized|invalid|unexpected)\s+"
332 r"(?:flag|option|argument|command|subcommand)\b"
333 r"|flag needs an argument\b"
334 r"|.{0,40}\bcommand not found$",
335 re.IGNORECASE,
336)
338#: The same complaint without the ``error:`` prefix. This one IS ambiguous with
339#: review prose, so it must both name a flag-shaped token ("unknown flag:
340#: --print") and be corroborated by surrounding banner structure.
341_BARE_ARG_ERROR_RE = re.compile(
342 r"(?:unknown|unrecognized|invalid|unexpected)\s+"
343 r"(?:flag|option|argument|command|subcommand)\b"
344 r"[\s:=]*[\"'`]?-{1,2}[A-Za-z0-9]",
345 re.IGNORECASE,
346)
348#: Corroborating structure, never a trigger on its own: the options/flags block
349#: under a synopsis, or the help hint a launcher prints beneath it. The old
350#: unanchored "for more information, try/see" pattern lives on only here — it
351#: is a sentence a review can perfectly well contain.
352_BANNER_STRUCTURE_RE = re.compile(
353 r"^[ \t]*(?:options|flags|commands|arguments|subcommands)\b[ \t]*:?[ \t]*$"
354 r"|^[ \t]*-{1,2}[A-Za-z0-9][\w-]*(?:[ \t=,]|$)"
355 r"|^[ \t]*for more information,? (?:try|see)\b",
356 re.IGNORECASE | re.MULTILINE,
357)
359#: Nothing but a version/probe banner, e.g. "1.1.22" or "agy version 1.1.22".
360_VERSION_ONLY_RE = re.compile(r"^[\w.@/+-]{0,40}(?:\s+version)?\s*v?\d+\.\d+[\w.+-]*$")
362#: A refusal, matched on the lowercased text and only inside the length bound
363#: above. Deliberately narrow: these are first-person declines, not any
364#: sentence containing the word "cannot".
365#:
366#: Matching this is NOT on its own enough to discard an output — see
367#: :func:`_is_whole_output_refusal`. A reviewer routinely opens with a limit it
368#: hit ("I do not have access to the migration file, so I reviewed the Python
369#: only: …") and then reviews; discarding that costs a panelist and, with the
370#: gate failing closed, turns a passing two-vendor run into exit 3.
371_REFUSAL_RE = re.compile(
372 r"i(?:'|\u2019)?m (?:sorry|unable|not able)"
373 r"|i am (?:sorry|unable|not able)"
374 r"|i (?:can(?:'|\u2019)?t|cannot|won(?:'|\u2019)?t|will not)"
375 r" (?:help|assist|do|review|comply|provide|analyz|analys)"
376 r"|sorry,? (?:but )?i "
377 r"|as an ai\b"
378 r"|i (?:do not|don(?:'|\u2019)?t) have (?:access|the ability)"
379)
382#: How far into the output a decline may begin and still BE the output. A
383#: refusal says so first; a review that ran into a limit mid-argument says so
384#: after paragraphs of review. One short lead-in sentence is allowed for, no more.
385_REFUSAL_OPENING_CHARS = 80
387#: Marks of an output that reviewed something, however briefly. Any one of them
388#: outranks the refusal phrase in front of it: an agent that says it could not
389#: read one file and then names a defect HAS reviewed, and its finding is the
390#: thing the panel exists to collect.
391_REVIEW_SUBSTANCE_RE = re.compile(
392 r"\blines?\s+\d+" # "line 12", "lines 40-52"
393 r"|\b[\w./-]+\.[a-z]{1,5}:\d+" # "src/app.py:12"
394 r"|^@@[ \t]" # a hunk header quoted back
395 r"|\bi (?:reviewed|read|checked|examined|inspected|looked at|went through)\b"
396 r"|\b(?:having|after) (?:reviewed|read|checked|examined)\b",
397 re.IGNORECASE | re.MULTILINE,
398)
400#: The adversative pivot that turns a limit into a review: "I'm not able to
401#: reproduce the race locally, BUT the lock ordering here is wrong." It counts
402#: only when what follows is prose of its own and is not itself another decline
403#: — "I'm sorry, but I can't help with this" pivots into the same refusal.
404_PIVOT_RE = re.compile(r"\b(?:but|however|though|although|that said)\b", re.IGNORECASE)
406#: How much text must follow a pivot before it can carry a review claim.
407_PIVOT_MIN_CHARS = 20
410def _carries_review_substance(body: str) -> bool:
411 """True when ``body`` says something about the code, not only about itself."""
412 if _REVIEW_SUBSTANCE_RE.search(body):
413 return True
414 pivot = _PIVOT_RE.search(body)
415 if pivot is None:
416 return False
417 rest = body[pivot.end() :].strip()
418 return len(rest) >= _PIVOT_MIN_CHARS and _REFUSAL_RE.search(rest.lower()) is None
421def _is_whole_output_refusal(body: str) -> bool:
422 """True when the output *is* a decline, not a review that mentions a limit.
424 Three conditions, all necessary. The output is short (a real decline is a
425 sentence or two), the decline OPENS it, and nothing in it carries review
426 substance. Merely containing a refusal phrase somewhere inside the length
427 bound was the old rule, and it destroyed genuine short reviews — including
428 ones that named a defect and a line number (#682, round 3).
429 """
430 if len(body) > _NO_REVIEW_MAX_CHARS:
431 return False
432 match = _REFUSAL_RE.search(body.lower())
433 if match is None or match.start() > _REFUSAL_OPENING_CHARS:
434 return False
435 return not _carries_review_substance(body)
438def _is_cli_banner(body: str) -> bool:
439 """True when ``body`` *is* a launcher's banner, not prose that mentions one.
441 Two shapes qualify. A full help dump — a synopsis line plus an options
442 block — is unmistakable at any length. Anything shorter must both open with
443 a banner-shaped line and fit inside the same length bound the refusal branch
444 uses: a real review is not three lines.
445 """
446 head = body[:_NO_REVIEW_HEAD_CHARS]
447 lines = [line.strip() for line in head.splitlines() if line.strip()]
448 if not lines: # pragma: no cover - `body` is stripped and non-empty here
449 return False
450 synopsis = any(_USAGE_LINE_RE.match(line) for line in lines)
451 structure = _BANNER_STRUCTURE_RE.search(head) is not None
452 if synopsis and structure:
453 return True
454 if len(body) > _NO_REVIEW_MAX_CHARS:
455 return False
456 first = lines[0]
457 if _USAGE_LINE_RE.match(first) or _CLI_SELF_ERROR_RE.match(first):
458 return True
459 return _BARE_ARG_ERROR_RE.match(first) is not None and (synopsis or structure)
462def no_review_reason(text: str) -> str | None:
463 """Why ``text`` cannot be a review, or ``None`` when it could be one.
465 PURE, and a judgement of SHAPE only — it never scores a review's quality.
466 An adapter calls it on an exit-0 stdout so that a refusal, a usage banner
467 or a bare version string is recorded as a typed failure (``ERR_NO_REVIEW``)
468 rather than as a contributing vendor. Fail-soft still applies: the run
469 continues, but with a dead seat that says so.
471 Returns a short human-readable reason, safe to embed in an error string
472 (it names the category, never the agent's text).
473 """
474 body = (text or "").strip()
475 if not body:
476 return "the agent produced no output"
477 # A structured findings block is the one machine-checkable proof that the
478 # agent answered in the reviewer's contract, and it settles the question
479 # before any prose heuristic gets a vote: a launcher banner does not emit
480 # one, and an agent that declines and then reports a finding has reviewed.
481 if emitted_findings_block(body):
482 return None
483 if _is_cli_banner(body):
484 return "the CLI printed usage or argument-error text instead of a review"
485 if _VERSION_ONLY_RE.match(body):
486 return "the CLI printed only a version banner instead of a review"
487 if _is_whole_output_refusal(body):
488 return "the agent declined to review"
489 return None
492# --- Reasoning effort (issue #662) -------------------------------------------
493#
494# Every vendor expresses "think harder" differently, so the mapping lives HERE,
495# in one pure function, instead of being spread across the adapters: agy encodes
496# effort as a model-id suffix, the Anthropic Messages API takes an extended-
497# thinking token budget, OpenAI-shaped APIs take `reasoning_effort`, Gemini takes
498# a `thinkingConfig` budget, and the `claude`/`codex` CLIs have no headless knob
499# at all. `effort_args` is the single place any of that is decided.
501#: The effort levels accepted by ``[[agent]] effort`` and ``--effort``.
502EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high")
504# Anthropic extended-thinking budgets (tokens) per level, before clamping.
505_ANTHROPIC_THINKING_BUDGET = {"low": 2048, "medium": 8192, "high": 32768}
506# Ceiling on the `max_tokens` this project will ever request from Anthropic.
507# Thinking tokens are drawn from the same allowance, so `max_tokens` has to
508# exceed the budget — but per-model caps vary and an unbounded sum would build a
509# request some models reject outright. 32000 sits inside every current model's
510# limit, so the `high` budget is clamped to `ceiling - _HOSTED_API_MAX_TOKENS`
511# (27904) rather than sending its nominal 32768. Documented in
512# docs/configuration.md.
513_ANTHROPIC_MAX_TOKENS_CEILING = 32000
514# Gemini `thinkingConfig.thinkingBudget` (tokens) per level.
515_GEMINI_THINKING_BUDGET = {"low": 1024, "medium": 8192, "high": 32768}
516# agy model-id suffixes that already carry an effort level.
517_AGY_MODEL_SUFFIXES = tuple(f"-{level}" for level in EFFORT_LEVELS)
519# Vendors that can actually act on an effort level. Everything else (the
520# `claude`/`codex` CLIs, `local`, `cli`, any unregistered vendor) warns once and
521# ignores it: a local OpenAI-compatible server is NOT included, because many of
522# them reject an unknown request field outright, which would turn a hint into a
523# failed review.
524_EFFORT_VENDORS = frozenset(
525 {"google", "anthropic-api", "openai-api", "xai-api", "openai-compatible", "google-api"}
526)
529@dataclass(frozen=True)
530class EffortPlan:
531 """How one vendor expresses a reasoning-effort level.
533 ``model`` is a replacement model id (agy, which encodes effort in the id);
534 ``payload`` is a request-body fragment to merge into the vendor's JSON body;
535 ``warning`` is the once-per-run operator message when the level is ignored.
536 """
538 supported: bool = True
539 model: str | None = None
540 payload: dict = field(default_factory=dict)
541 warning: str | None = None
544def effort_supported(vendor: str) -> bool:
545 """Whether *vendor* can act on an effort level at all (pure)."""
546 return config_module.normalise_vendor(vendor) in _EFFORT_VENDORS
549def _anthropic_budget(level: str) -> int:
550 """Thinking budget for *level*, clamped to the documented ceiling (pure)."""
551 return min(
552 _ANTHROPIC_THINKING_BUDGET[level],
553 _ANTHROPIC_MAX_TOKENS_CEILING - _HOSTED_API_MAX_TOKENS,
554 )
557def _effort_uses_model_listing(vendor: str) -> bool:
558 """Whether *vendor* expresses effort through the model id (pure).
560 Those are the vendors whose mapped id can be checked against what the CLI
561 actually offers, so callers know when discovering a listing is worth a probe.
562 """
563 return config_module.normalise_vendor(vendor) == "google"
566def effort_args(
567 vendor: str,
568 effort: str | None,
569 model: str | None = None,
570 known_models: list[str] | None = None,
571) -> EffortPlan:
572 """Map ``(vendor, effort, model)`` to the vendor's own effort knob (pure).
574 An empty/None *effort* is a no-op plan. An unrecognized level raises
575 ``ValueError`` — ``config.validate_config`` and the ``--effort`` choices
576 already gate user input, so reaching here with garbage is a programming
577 error, not something to silently swallow.
579 ``known_models``, when the caller has discovered one, is the model listing
580 the vendor actually offers. It is only consulted where effort is expressed
581 *as* a model id (agy): sending a suffixed id the CLI does not have would
582 fail the whole review, so an unlisted mapping falls back to the configured
583 id and warns instead. ``None`` means "no listing available" — the check is
584 skipped, never guessed.
585 """
586 level = (effort or "").strip().lower()
587 if not level:
588 return EffortPlan()
589 if level not in EFFORT_LEVELS:
590 raise ValueError(f"unknown effort {effort!r}; expected one of {', '.join(EFFORT_LEVELS)}")
592 name = config_module.normalise_vendor(vendor)
594 if name == "google":
595 # The `agy` CLI selects effort through the model id itself.
596 current = (model or "").strip()
597 if not current:
598 return EffortPlan(
599 warning=(
600 f"effort '{level}' needs a configured model for vendor '{vendor}' "
601 f"(effort is encoded in the model id), ignored"
602 )
603 )
604 if current.endswith(_AGY_MODEL_SUFFIXES):
605 # Already pinned by the operator; an explicit model id wins.
606 return EffortPlan(model=current)
607 suffixed = f"{current}-{level}"
608 if known_models is not None and suffixed not in known_models:
609 # Better a review at the configured depth than no review at all.
610 return EffortPlan(
611 model=current,
612 warning=(
613 f"effort '{level}' maps model '{current}' to '{suffixed}', which "
614 f"vendor '{vendor}' does not offer; using '{current}' unchanged"
615 ),
616 )
617 return EffortPlan(model=suffixed)
619 if name == "anthropic-api":
620 return EffortPlan(
621 payload={
622 "thinking": {
623 "type": "enabled",
624 "budget_tokens": _anthropic_budget(level),
625 }
626 }
627 )
629 if name in ("openai-api", "xai-api", "openai-compatible"):
630 return EffortPlan(payload={"reasoning_effort": level})
632 if name == "google-api":
633 return EffortPlan(
634 payload={
635 "generationConfig": {
636 "thinkingConfig": {"thinkingBudget": _GEMINI_THINKING_BUDGET[level]}
637 }
638 }
639 )
641 return EffortPlan(supported=False, warning=f"effort unsupported for {vendor}, ignored")
644def effort_warnings(agents, adapter_factory=None) -> list[str]:
645 """Deduped, ordered effort warnings for a panel — one message per run.
647 Callers (the CLI) print these once before the run rather than once per agent
648 invocation, so a three-round panel does not repeat the same line nine times.
650 Pure unless *adapter_factory* is given. With it, an agent whose effort is
651 expressed as a model id has its mapped id checked against the vendor's real
652 listing, so "that model does not exist" is reported up front instead of
653 surfacing as an abstention mid-run. The probe is skipped entirely for agents
654 with no effort configured and for every other vendor, and any failure
655 degrades to "no listing" rather than blocking the run.
656 """
657 seen: set[str] = set()
658 out: list[str] = []
659 for spec in agents:
660 # The adapter, not the vendor (#705): how effort is expressed — a model
661 # suffix, a request-body field, nothing at all — is a property of the
662 # protocol the seat is invoked through.
663 vendor = config_module.spec_adapter(spec)
664 effort = getattr(spec, "effort", None)
665 known_models = None
666 if adapter_factory is not None and effort and _effort_uses_model_listing(vendor):
667 try:
668 known_models = adapter_factory(spec).list_models()
669 except Exception: # noqa: BLE001 - discovery is best-effort
670 known_models = None
671 try:
672 plan = effort_args(
673 vendor,
674 effort,
675 getattr(spec, "model", None),
676 known_models=known_models,
677 )
678 except ValueError as exc:
679 # Redact before it reaches a warning/log, like every other str(exc) in this
680 # module — an effort-args failure can echo attacker/config-influenced text (#828).
681 message = redaction.redact(str(exc))[0]
682 else:
683 message = plan.warning
684 if message and message not in seen:
685 seen.add(message)
686 out.append(message)
687 return out
690# Model ids look like `gemini-3.8-flash`, `qwen2.5-coder:7b`, `anthropic/claude-x`.
691_MODEL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]*$")
692# Cap a discovered model listing so a chatty/hostile CLI cannot flood diagnostics.
693_MAX_LISTED_MODELS = 50
696def parse_model_list(raw: str) -> list[str]:
697 """Model ids out of a CLI's model listing (pure, best-effort, order-preserving).
699 Accepts either JSON (a list, or an object with ``models``/``data``) or plain
700 lines, because a CLI's listing format is not a contract. Anything that does
701 not look like a model id is dropped rather than guessed at.
702 """
703 text = (raw or "").strip()
704 if not text:
705 return []
707 ids: list[str] = []
708 try:
709 data = json.loads(text)
710 except ValueError:
711 data = None
712 if isinstance(data, dict):
713 data = data.get("models") or data.get("data")
714 if isinstance(data, list):
715 for item in data:
716 if isinstance(item, str):
717 ids.append(item)
718 elif isinstance(item, dict):
719 value = item.get("id") or item.get("name") or item.get("model")
720 if isinstance(value, str):
721 ids.append(value)
722 else:
723 for line in text.splitlines():
724 token = line.strip().lstrip("-*\u2022").strip()
725 token = token.split()[0] if token else ""
726 if _MODEL_ID_RE.match(token):
727 ids.append(token)
729 seen: set[str] = set()
730 out: list[str] = []
731 for value in ids:
732 value = value.strip()
733 if value and value not in seen:
734 seen.add(value)
735 out.append(value)
736 return out[:_MAX_LISTED_MODELS]
739@dataclass
740class AgentResult:
741 agent: str
742 vendor: str
743 ok: bool
744 output: str
745 duration_s: float
746 error: str | None = None
747 findings: list = field(default_factory=list)
748 warnings: list = field(default_factory=list)
749 error_code: str | None = None
750 # Number of attempts made for this result (issue #30): 1 means no retry.
751 # >1 records that a transient failure was retried before this outcome.
752 attempts: int = 1
753 # Did this agent emit a structured findings block at all (issue #501)? A
754 # reviewer that examined the diff and found nothing still emits `[]`; one that
755 # produced no review emits prose and no block. Without this, both arrive as zero
756 # findings and the panel reports the same size either way.
757 structured: bool = False
758 # The agent process's own exit status (issue #661), or None when there was
759 # no process to exit: a network adapter, a CLI that was never spawned
760 # (missing on PATH, spawn failure), or one killed on timeout. `jury
761 # run-agent` reports it so an orchestrator can act on the real status
762 # instead of parsing it back out of the error string.
763 exit_code: int | None = None
764 # The model id this invocation actually sent (issue #709), stamped by the
765 # path that ran the adapter from :meth:`Adapter.resolved_model` — the same
766 # call that put the id in the argv/payload. Empty when nothing was pinned
767 # (the CLI chose) or when the record was not produced by an invocation.
768 # A ballot READS this rather than re-deriving it: `vendor` and `adapter` can
769 # differ since #705, and a second derivation is a second answer.
770 model: str = ""
773class Adapter:
774 """Base adapter. Subclasses build the argv for their CLI."""
776 # Declarative capability metadata. Real coding-agent CLIs support a headless
777 # (non-interactive) invocation and model selection; subclasses override where
778 # this differs. ``MockAdapter`` reports synthetic capabilities.
779 SUPPORTS_HEADLESS = True
780 SUPPORTS_MODEL_SELECTION = True
782 #: Start every READ-ONLY invocation — the panel's review, debate, verify and
783 #: synthesis calls, and ``jury run-agent``'s review/gate/chair roles — in a
784 #: fresh empty directory rather than the one ``jury`` runs in (see
785 #: :func:`_review_workdir`). A read-only role reads its prompt and nothing
786 #: else, so it never needs the repository, and a PR checkout's project
787 #: settings (a ``.claude/settings.json`` hook ran from one, measured) must not
788 #: reach it. Only a write role (``implement``/``fix`` with ``--allow-write``)
789 #: stays in ``--cwd``: it has to edit that worktree. On for the three native
790 #: CLIs, whose behaviour there is known — codex needs
791 #: ``--skip-git-repo-check`` outside a git repository, and its read-only argv
792 #: carries it. Off by default, so a bring-your-own ``cli`` seat and a
793 #: registered custom adapter keep running where they always did: this tool
794 #: cannot know what an operator's own binary expects of its directory.
795 ISOLATE_REVIEW_CWD = False
797 #: Whether this adapter runs its agent as a subprocess — the question the
798 #: least-privilege audit asks before it looks for a sandbox. ``True`` unless a
799 #: class says otherwise: the HTTP adapters (``LocalAdapter`` and the
800 #: hosted-API ones) set ``False``, and so can a custom adapter that calls its
801 #: backend over the network from ``run()`` (#903). ``register_adapter`` reads
802 #: it, and only an explicit ``False`` opts out; a registered class that spawns
803 #: a CLI and sets ``False`` would escape the audit, so the default is the safe one.
804 SPAWNS_PROCESS = True
806 # Args passed to the CLI to print its version. Subclasses override if the CLI
807 # uses a different verb/flag (e.g. ``codex --version``).
808 _VERSION_ARGS = ("--version",)
810 def __init__(self, spec: AgentSpec):
811 self.spec = spec
813 @property
814 def name(self) -> str:
815 return self.spec.name
817 def available(self) -> bool:
818 return shutil.which(self.spec.command) is not None
820 def build_argv(self, prompt: str) -> list[str]: # pragma: no cover - overridden
821 raise NotImplementedError
823 def build_write_argv(self, prompt: str) -> list[str]:
824 """Argv for a WRITE-capable invocation of this CLI (issue #661).
826 The default is the read-only argv: a vendor with no tool-enabled mode
827 (and every network adapter, which has no tools at all) simply cannot
828 widen, and failing closed is the right default. The three native CLI
829 adapters override it.
830 """
831 return self.build_argv(prompt)
833 def build_argv_for_role(self, prompt: str, policy=None) -> list[str]:
834 """Argv for one ``jury run-agent`` role (issue #661).
836 The single seam between the role policy and an adapter's argv, so the
837 policy is never re-decided inside :meth:`run`. ``policy=None`` — every
838 panel invocation — resolves to the unchanged read-only :meth:`build_argv`,
839 which is why adding this could not alter an existing run.
841 Both branches end in :meth:`build_argv`, which the base class leaves
842 ``NotImplementedError``. That is not reachable through a real run: every
843 adapter that spawns a subprocess implements it, and the ones that do not
844 (``LocalAdapter`` and the hosted-API adapters) build no argv at all —
845 they override :meth:`run` and never call this. A new subprocess adapter
846 that forgets ``build_argv`` therefore fails loudly on its first
847 invocation rather than running with an empty command line.
848 """
849 if policy is None or not getattr(policy, "write", False):
850 return self.build_argv(prompt)
851 return self.build_write_argv(prompt)
853 def _stdin_for(self, prompt: str) -> str | None:
854 """Prompt to feed on stdin, or None to pass it in argv (the default)."""
855 del prompt
856 return None
858 def _text_from_stdout(self, raw: str) -> str:
859 """The reviewer's prose, given the CLI's raw stdout.
861 Plain text for every adapter but one. `agy` speaks NDJSON events, so it
862 overrides this rather than teaching `run` about event streams.
863 """
864 return raw
866 def _version_argv(self) -> list[str]:
867 """Argv used to probe the CLI's version."""
868 return [self.spec.command, *self._VERSION_ARGS]
870 def effort_plan(self) -> EffortPlan:
871 """This agent's resolved effort mapping (see :func:`effort_args`).
873 An invalid level degrades to a no-op plan here: a run must not crash on
874 a bad config value that ``validate_config`` is responsible for rejecting.
875 """
876 try:
877 return effort_args(
878 config_module.spec_adapter(self.spec),
879 getattr(self.spec, "effort", None),
880 self.spec.model,
881 )
882 except ValueError:
883 return EffortPlan()
885 def resolved_model(self) -> str:
886 """The model id this adapter sends, byte-for-byte (issue #709).
888 **The** answer to "which model was asked for", and the only one: every
889 place a model id leaves this module — the ``--model``/``-m`` argv of the
890 three CLI adapters, the ``model`` field of every network payload, the
891 Gemini URL — reads it from here, and :attr:`AgentResult.model` records
892 what it returned so a ballot can quote the id instead of deriving a
893 second one.
895 That second derivation was the defect. :func:`effort_args` is keyed on
896 the **adapter**, because how effort is expressed is a property of the
897 protocol a seat is invoked through; ``ai_jury.ballots.requested_model``
898 keyed it on the ``vendor``, and since #705 those can differ, so a seat
899 with ``vendor = google, adapter = cli`` was invoked with ``gemini-3-pro``
900 while its ballot reported ``gemini-3-pro-high`` under
901 ``model_source: requested`` — a field whose whole claim is that it is the
902 id actually sent. The subclass that consults a live model listing
903 (:class:`AgyAdapter`) overrides :meth:`effort_plan`, not this, so the
904 fallback it resolves is recorded here too.
905 """
906 return (self.effort_plan().model or self.spec.model or "").strip()
908 def list_models(self) -> list[str] | None:
909 """Model ids this agent could be pointed at, or None when unknown.
911 Diagnostics only (``jury --doctor --json``). The default is None — most
912 CLIs have no listing command — and every override is time-boxed and
913 fail-soft, because doctor must never hang or crash on a probe.
914 """
915 return None
917 def detect_capabilities(self) -> dict:
918 """Best-effort probe of this agent's version and capabilities.
920 Returns a dict shaped like::
922 {
923 "version": "<str|None>",
924 "supports_headless": bool,
925 "supports_model_selection": bool,
926 "raw_version_output": "<short str>",
927 "status": "ok|unknown_version|unavailable",
928 "warnings": [...],
929 }
931 This is intentionally fast and forgiving: it runs ``<command> --version``
932 with a SHORT timeout and swallows ALL errors (missing CLI, timeout,
933 nonzero exit, garbage output). It NEVER raises, so it is safe to call
934 from diagnostics without blocking or crashing a run.
935 """
936 caps = {
937 "version": None,
938 "supports_headless": self.SUPPORTS_HEADLESS,
939 "supports_model_selection": self.SUPPORTS_MODEL_SELECTION,
940 "raw_version_output": "",
941 "status": CAP_UNAVAILABLE,
942 "warnings": [],
943 }
945 # Not on PATH: report unavailable without spawning a subprocess.
946 if not self.available():
947 return caps
949 try:
950 # Via _spawn so the probe also runs in its own process group and the
951 # whole group is killed on timeout (issue #303/L-1) — matching the
952 # main run path; a bare subprocess.run would orphan grandchildren.
953 proc = _spawn(self._version_argv(), None, _VERSION_PROBE_TIMEOUT)
954 except subprocess.TimeoutExpired:
955 caps["status"] = CAP_UNKNOWN_VERSION
956 caps["warnings"].append(
957 f"version probe for '{self.spec.command}' timed out after {_VERSION_PROBE_TIMEOUT}s"
958 )
959 return caps
960 except Exception as exc: # noqa: BLE001 - swallow any spawn failure
961 caps["status"] = CAP_UNKNOWN_VERSION
962 caps["warnings"].append(
963 f"version probe for '{self.spec.command}' failed: {redaction.redact(str(exc))[0]}"
964 )
965 return caps
967 raw = ((proc.stdout or "") + (proc.stderr or "")).strip()
968 caps["raw_version_output"] = redaction.redact(raw[:200])[0]
969 match = _VERSION_RE.search(raw)
970 if proc.returncode == 0 and match:
971 caps["version"] = match.group(0)
972 caps["status"] = CAP_OK
973 else:
974 caps["status"] = CAP_UNKNOWN_VERSION
975 caps["warnings"].append(
976 f"could not determine version of '{self.spec.command}' "
977 f"(exit {proc.returncode}); capabilities assumed from vendor defaults"
978 )
979 return caps
981 def run(
982 self,
983 prompt: str,
984 phase: str = "review",
985 timeout: int | None = None,
986 role_policy=None,
987 ) -> AgentResult:
988 del phase
989 if not self.available():
990 return AgentResult(
991 self.name,
992 self.spec.vendor,
993 False,
994 "",
995 0.0,
996 f"command not found on PATH: {self.spec.command}",
997 error_code=ERR_MISSING_CLI,
998 )
999 # The effective timeout is the caller's override (the run budget, issue
1000 # #30) when smaller than the agent's own bound, else the agent timeout.
1001 effective_timeout = self.spec.timeout
1002 if timeout is not None:
1003 effective_timeout = max(1, min(self.spec.timeout, int(timeout)))
1004 argv = self.build_argv_for_role(prompt, role_policy)
1005 stdin = self._stdin_for(prompt)
1006 start = time.monotonic()
1007 try:
1008 # A command is a bare name or an absolute path (config validation
1009 # refuses a relative one, #293/F-6), so moving the directory cannot
1010 # change which binary runs.
1011 read_only = not getattr(role_policy, "write", False)
1012 with _review_workdir(self.ISOLATE_REVIEW_CWD and read_only) as cwd:
1013 if cwd is None:
1014 proc = _spawn(argv, stdin, effective_timeout)
1015 else:
1016 proc = _spawn(argv, stdin, effective_timeout, cwd=cwd)
1017 except subprocess.TimeoutExpired:
1018 return AgentResult(
1019 self.name,
1020 self.spec.vendor,
1021 False,
1022 "",
1023 time.monotonic() - start,
1024 f"timed out after {effective_timeout}s",
1025 error_code=ERR_TIMEOUT,
1026 )
1027 except Exception as exc: # noqa: BLE001 - surface any spawn failure
1028 return AgentResult(
1029 self.name,
1030 self.spec.vendor,
1031 False,
1032 "",
1033 time.monotonic() - start,
1034 f"spawn failed: {redaction.redact(str(exc))[0]}",
1035 error_code=ERR_SPAWN_FAILED,
1036 )
1037 dur = time.monotonic() - start
1038 out = self._text_from_stdout((proc.stdout or "").strip()).strip()
1039 # A nonzero exit is ALWAYS a failure, even with stdout (issue #101): a
1040 # crashing CLI can still print partial or error output, and counting that
1041 # as a clean review would silently feed it into consensus, synthesis, and
1042 # the CI gate. We classify from stderr (falling back to any stdout) and
1043 # keep a short snippet in the error for debugging — but ok=False, so the
1044 # orchestrator excludes it.
1045 if proc.returncode != 0:
1046 stderr = (proc.stderr or "").strip()
1047 detail = stderr or out
1048 # Redact before embedding in the error: a crashing CLI can dump an
1049 # env var / token into its stderr, and this string is rendered into
1050 # the report and posted to the PR. Mirrors the LocalAdapter path
1051 # (#293/F-8); the asymmetry was a secret-leak vector (audit
1052 # 2026-06-13/N-1). Classify on the raw text (no secrets in codes).
1053 safe_detail = redaction.redact(detail)[0]
1054 return AgentResult(
1055 self.name,
1056 self.spec.vendor,
1057 False,
1058 "",
1059 dur,
1060 f"exit {proc.returncode}: {safe_detail[:500]}",
1061 error_code=classify_stderr(proc.returncode, stderr or out),
1062 exit_code=proc.returncode,
1063 )
1064 if not out:
1065 # Exit 0 but nothing on stdout: the agent produced no usable review.
1066 return AgentResult(
1067 self.name,
1068 self.spec.vendor,
1069 False,
1070 "",
1071 dur,
1072 f"exit {proc.returncode}: empty output",
1073 error_code=ERR_EMPTY_OUTPUT,
1074 exit_code=proc.returncode,
1075 )
1076 # Exit 0 with output that is not a review (issue #682): a refusal, or the
1077 # CLI's own usage/version banner because the argv never reached the model
1078 # (#635). Counting it as a review is what makes a panel collapse silent.
1079 no_review = no_review_reason(out)
1080 if no_review is not None:
1081 return AgentResult(
1082 self.name,
1083 self.spec.vendor,
1084 False,
1085 "",
1086 dur,
1087 f"no review returned: {no_review}: {redaction.redact(out)[0][:200]}",
1088 error_code=ERR_NO_REVIEW,
1089 exit_code=proc.returncode,
1090 )
1091 return AgentResult(self.name, self.spec.vendor, True, out, dur, exit_code=proc.returncode)
1094class ClaudeAdapter(Adapter):
1095 # The prompt embeds the (redacted) diff and PR/issue context; deliver it on
1096 # STDIN rather than as a process argument so it is not exposed in `ps` /
1097 # /proc/<pid>/cmdline to other local users (issue #287). `claude -p` reads
1098 # the prompt from stdin when no positional prompt is given.
1099 ISOLATE_REVIEW_CWD = True
1101 def _head_argv(self) -> list[str]:
1102 argv = [self.spec.command, "-p"]
1103 model = self.resolved_model()
1104 if model:
1105 argv += ["--model", model]
1106 return argv
1108 def build_argv(self, prompt: str) -> list[str]:
1109 del prompt
1110 return self._head_argv() + _read_only_extra_args(self.spec)
1112 def build_write_argv(self, prompt: str) -> list[str]:
1113 """Implementer invocation: the CLI's own tool set, no deny list (#661)."""
1114 del prompt
1115 return self._head_argv() + _write_extra_args(self.spec)
1117 def _stdin_for(self, prompt: str) -> str | None:
1118 return prompt
1121class CodexAdapter(Adapter):
1122 # Pipe the prompt on stdin (not positionally) so ``codex exec`` never blocks
1123 # waiting for input in non-interactive runs. Sandbox flags live in extra_args;
1124 # the shipped default is ``-s read-only`` (secure by default, #100) — the
1125 # reviewer only reads its prompt, since the jury fetches the diff via ``gh``.
1126 ISOLATE_REVIEW_CWD = True
1128 #: `codex exec` refuses to start outside a git repository ("Not inside a
1129 #: trusted directory and --skip-git-repo-check was not specified", verified
1130 #: against codex-cli 0.155.0), and a panel invocation starts in an empty
1131 #: temporary directory. The check keeps an agent out of a directory nobody
1132 #: vouched for; a reviewer is kept in check by its read-only sandbox instead,
1133 #: which ``privilege.audit_agent`` reports on, and the directory is empty.
1134 _SKIP_GIT_CHECK = "--skip-git-repo-check"
1136 def _head_argv(self) -> list[str]:
1137 argv = [self.spec.command, "exec"]
1138 model = self.resolved_model()
1139 if model:
1140 argv += ["-m", model]
1141 return argv
1143 #: ``codex exec --ephemeral`` ("Run without persisting session files to
1144 #: disk", codex-cli 0.155.0): a reviewer's session holds the untrusted diff
1145 #: and is never resumed.
1146 _EPHEMERAL = "--ephemeral"
1148 def build_argv(self, prompt: str) -> list[str]:
1149 del prompt
1150 extra = _read_only_extra_args(self.spec)
1151 # Only an option counts as present: after `--` it is prompt text (#908 review).
1152 options = privilege._codex_options(extra)
1153 added = [f for f in (self._SKIP_GIT_CHECK, self._EPHEMERAL) if f not in options]
1154 return self._head_argv() + added + extra
1156 def build_write_argv(self, prompt: str) -> list[str]:
1157 """Implementer invocation: ``-s workspace-write`` instead of read-only (#661)."""
1158 del prompt
1159 return self._head_argv() + _write_extra_args(self.spec)
1161 def _stdin_for(self, prompt: str) -> str | None:
1162 return prompt
1165class AgyAdapter(Adapter):
1166 # Prompt on STDIN, not argv (issue #287): the redacted diff must not appear in
1167 # the process list, where any local user can read it.
1168 #
1169 # `agy --print` used to read the prompt from stdin (verified against 1.0.6).
1170 # On 1.1.x `--print` takes a value, so that invocation dies before the model
1171 # is reached — `flag needs an argument: -print` with an empty `extra_args`,
1172 # and "took --dangerously-skip-permissions as its prompt" with a non-empty
1173 # one (#635). The agent passed every availability check and contributed
1174 # nothing to the panel.
1175 #
1176 # The obvious repair — put the prompt in argv — silently undoes #287. So the
1177 # prompt moves to agy's own stdin channel instead: `--input-format
1178 # stream-json` reads one NDJSON message per line and requires
1179 # `--output-format stream-json`. `--print` is not passed at all; the input
1180 # format implies print mode, and passing it would reintroduce the arity
1181 # problem. Verified end to end against agy 1.1.22.
1182 _STREAM_ARGS = ("--input-format", "stream-json", "--output-format", "stream-json")
1184 # A panel review starts in an empty temporary directory; agy 1.2.9 answers
1185 # from one (checked by hand against the installed CLI).
1186 ISOLATE_REVIEW_CWD = True
1188 # `agy models` lists the model ids the CLI can be pointed at.
1189 _MODELS_ARGS = ("models",)
1191 def effort_plan(self) -> EffortPlan:
1192 """agy's effort IS the model id, so check the mapping against its listing.
1194 The listing is probed at most once per adapter instance, and only when an
1195 effort level is actually configured — a run without one pays nothing,
1196 which matters because this is on the per-invocation path.
1197 """
1198 if not getattr(self.spec, "effort", None):
1199 return EffortPlan()
1200 try:
1201 return effort_args(
1202 config_module.spec_adapter(self.spec),
1203 self.spec.effort,
1204 self.spec.model,
1205 known_models=self._cached_model_listing(),
1206 )
1207 except ValueError:
1208 return EffortPlan()
1210 def _cached_model_listing(self) -> list[str] | None:
1211 """``agy models``, memoized per adapter instance."""
1212 if not hasattr(self, "_model_listing"):
1213 self._model_listing = self.list_models()
1214 return self._model_listing
1216 def _head_argv(self) -> list[str]:
1217 argv = [self.spec.command, *self._STREAM_ARGS]
1218 # agy encodes reasoning effort in the model id (`…-flash` -> `…-flash-high`),
1219 # so effort changes WHICH model is selected rather than adding a flag.
1220 model = self.resolved_model()
1221 if model:
1222 argv += ["--model", model]
1223 return argv
1225 def build_argv(self, prompt: str) -> list[str]:
1226 del prompt
1227 return self._head_argv() + _read_only_extra_args(self.spec)
1229 def build_write_argv(self, prompt: str) -> list[str]:
1230 """Implementer invocation: drop the boolean ``--sandbox`` (#661)."""
1231 del prompt
1232 return self._head_argv() + _write_extra_args(self.spec)
1234 def list_models(self) -> list[str] | None:
1235 """Model ids from ``agy models`` (time-boxed, fail-soft; issue #662)."""
1236 if not self.available():
1237 return None
1238 try:
1239 proc = _spawn([self.spec.command, *self._MODELS_ARGS], None, _VERSION_PROBE_TIMEOUT)
1240 except Exception: # noqa: BLE001 - discovery is best-effort
1241 return None
1242 if proc.returncode != 0:
1243 return None
1244 return parse_model_list(proc.stdout or "") or None
1246 def _stdin_for(self, prompt: str) -> str | None:
1247 """One NDJSON frame carrying the prompt. Shape verified against 1.1.22."""
1248 return json.dumps({"event": "user", "message": {"role": "user", "content": prompt}}) + "\n"
1250 def _text_from_stdout(self, raw: str) -> str:
1251 """The `result` event's response, out of the NDJSON stream.
1253 Falls back to the raw stream when no `result` frame is present rather
1254 than returning empty: a truncated stream should surface as an
1255 unparseable review the operator can read, not as a silent abstention —
1256 an empty review is counted as one, and #625 exists because an
1257 abstention read as an approval is the expensive failure.
1258 """
1259 response, saw_result = None, False
1260 for line in raw.splitlines():
1261 line = line.strip()
1262 if not line:
1263 continue
1264 try:
1265 event = json.loads(line)
1266 except ValueError:
1267 continue
1268 if isinstance(event, dict) and event.get("event") == "result":
1269 saw_result = True
1270 result = event.get("result")
1271 if isinstance(result, dict): 1271 ↛ 1260line 1271 didn't jump to line 1260 because the condition on line 1271 was always true
1272 response = result.get("response")
1273 if saw_result and isinstance(response, str):
1274 return response
1275 return raw
1278_DEFAULT_LOCAL_ENDPOINT = "http://localhost:11434/v1"
1281def _http_only_opener():
1282 """An opener that handles ONLY http/https (issue #291, SSRF defense).
1284 The default ``urllib`` opener honors ``file://`` and ``ftp://``, so an
1285 attacker-influenced ``endpoint`` could read local files or reach other
1286 schemes. This OpenerDirector registers no ``FileHandler``/``FTPHandler``, so
1287 any non-http(s) URL raises ``URLError("unknown url type")`` regardless of
1288 config validation — defense in depth alongside ``config._endpoint_issues``.
1290 It also registers NO ``HTTPRedirectHandler`` (review of #291): otherwise a
1291 malicious/compromised endpoint could 302-redirect to an internal/metadata
1292 host (e.g. ``169.254.169.254``) and the opener would follow it, bypassing the
1293 configured-URL validation. Without the handler a 3xx surfaces as an
1294 ``HTTPError`` (a failed review) and is never followed.
1295 """
1296 import urllib.request
1298 opener = urllib.request.OpenerDirector()
1299 for handler in (
1300 urllib.request.HTTPHandler,
1301 urllib.request.HTTPSHandler,
1302 urllib.request.HTTPDefaultErrorHandler,
1303 urllib.request.HTTPErrorProcessor,
1304 # UnknownHandler raises URLError("unknown url type: …") for any scheme
1305 # without a registered handler — so file://, ftp://, etc. fail loudly
1306 # instead of silently resolving to None.
1307 urllib.request.UnknownHandler,
1308 ):
1309 opener.add_handler(handler())
1310 return opener
1313def _open(target, timeout):
1314 """Open an http/https URL or Request via the restricted opener (issue #291).
1316 Single seam for every local-adapter HTTP call so the SSRF-safe opener (no
1317 file/ftp handlers) is always used.
1318 """
1319 return _http_only_opener().open(target, timeout=timeout)
1322def list_local_models(endpoint: str = _DEFAULT_LOCAL_ENDPOINT) -> list[str]:
1323 """Model ids a local server lists, or ``[]`` — see :func:`local_model_listing`.
1325 ``[]`` means both "the server lists none" and "the listing failed". Callers that
1326 must tell those apart (the doctor: a server with nothing pulled cannot review)
1327 use :func:`local_model_listing`, which answers ``None`` for a failed listing.
1328 """
1329 return local_model_listing(endpoint) or []
1332def local_model_listing(endpoint: str = _DEFAULT_LOCAL_ENDPOINT) -> list[str] | None:
1333 """List model ids from a local OpenAI-compatible server (issue #109).
1335 GETs ``{endpoint}/models`` (the OpenAI-compatible listing that Ollama,
1336 vLLM, LM Studio, etc. expose) and returns the model ids in their reported
1337 order. Best-effort and stdlib-only: any failure (server down, bad JSON)
1338 returns ``None`` — distinct from ``[]``, a server that answered and lists no
1339 model — so callers can fall back gracefully.
1341 The endpoint is validated here at the seam (issue #309) so EVERY caller —
1342 including the un-gated ``jury init --local-endpoint`` discovery path — gets
1343 the same SSRF gate that ``config._endpoint_issues`` enforces for config-file
1344 endpoints: a non-``http(s)`` scheme or a non-loopback host (without the
1345 ``JURY_ALLOW_REMOTE_ENDPOINT`` opt-in) yields ``None`` without any network call.
1346 """
1347 import json as _json
1349 from .config import _endpoint_issues
1351 base = (endpoint or _DEFAULT_LOCAL_ENDPOINT).rstrip("/")
1352 try:
1353 # SSRF gate INSIDE the try (review of #309): `_endpoint_issues` calls
1354 # urlsplit, which raises ValueError on a malformed URL (e.g. `http://[::1`);
1355 # keep the best-effort "any failure -> None" contract rather than crashing.
1356 if _endpoint_issues(base, "local-endpoint")[0]: # hard-error issues -> refuse
1357 return None
1358 url = base if base.endswith("/models") else f"{base}/models"
1359 with _open(url, _VERSION_PROBE_TIMEOUT) as resp: # noqa: S310
1360 data = _json.loads(resp.read(_MAX_RESPONSE_BYTES).decode("utf-8", errors="replace"))
1361 except Exception: # noqa: BLE001 - discovery is best-effort
1362 return None
1363 if not isinstance(data, dict) or "data" not in data:
1364 return None
1365 models = data["data"]
1366 if models is None:
1367 # Ollama with nothing pulled answers `{"object": "list", "data": null}`, not
1368 # `"data": []` (measured on Ollama 0.34.1) — the very server #849 is about.
1369 return []
1370 if not isinstance(models, list):
1371 return None
1372 ids = [m.get("id") for m in models if isinstance(m, dict) and m.get("id")]
1373 return [str(i) for i in ids]
1376class LocalAdapter(Adapter):
1377 """Open-weight / local-model reviewer over an OpenAI-compatible API (issue #43).
1379 Targets the ``/v1/chat/completions`` endpoint exposed by common local servers
1380 (Ollama, llama.cpp ``llama-server``, vLLM, LM Studio). It talks plain HTTP via
1381 the stdlib (``urllib``) — no new dependencies and no subprocess — so one panel
1382 seat can run free and fully offline, adding model diversity (the load-bearing
1383 advantage) at zero marginal cost.
1385 Configure as a normal ``[[agent]]`` with ``vendor = "local"``, an
1386 ``endpoint`` (base URL, default ``http://localhost:11434/v1``), and a
1387 ``model``. ``extra_args`` is unused. An unreachable server fails with the
1388 typed ``connection_error`` code (issue #29) rather than a crash.
1390 ``temperature`` is sent as configured, else the greedy ``0``. Greedy is the
1391 right default for a reviewer, but some models do not survive it: gpt-oss
1392 loops in its reasoning at 0 until its output cap and never answers.
1393 """
1395 SUPPORTS_HEADLESS = True
1396 SUPPORTS_MODEL_SELECTION = True
1397 SPAWNS_PROCESS = False # plain HTTP, no subprocess
1399 @property
1400 def endpoint(self) -> str:
1401 return (self.spec.endpoint or _DEFAULT_LOCAL_ENDPOINT).rstrip("/")
1403 def completions_url(self) -> str:
1404 """Resolve the chat-completions URL from the configured base endpoint.
1406 Accepts either a base URL (``…/v1``) or a full completions URL; pure so it
1407 can be unit-tested without network.
1408 """
1409 base = self.endpoint
1410 if base.endswith("/chat/completions"):
1411 return base
1412 return f"{base}/chat/completions"
1414 def build_payload(self, prompt: str) -> dict:
1415 """Build the OpenAI-compatible chat-completions request body (pure)."""
1416 return {
1417 "model": self.resolved_model(),
1418 "messages": [{"role": "user", "content": prompt}],
1419 "stream": False,
1420 # Unset keeps the literal `0` every earlier release sent.
1421 "temperature": 0 if self.spec.temperature is None else self.spec.temperature,
1422 }
1424 @staticmethod
1425 def parse_content(data: dict) -> str:
1426 """Extract the assistant message text from a chat-completions response."""
1427 choices = data.get("choices") or []
1428 if not choices:
1429 return ""
1430 message = choices[0].get("message") or {}
1431 return (message.get("content") or "").strip()
1433 @staticmethod
1434 def classify_http_status(status: int) -> str:
1435 """Map an HTTP error status to a typed error code (issue #29)."""
1436 if status in (401, 403):
1437 return ERR_AUTH_REQUIRED
1438 if status == 429:
1439 return ERR_RATE_LIMITED
1440 return ERR_NONZERO_EXIT
1442 def available(self) -> bool:
1443 """A local agent is 'available' when its server answers a quick probe.
1445 Probes the OpenAI-compatible ``/v1/models`` (or the endpoint root) with a
1446 short timeout. Network-only; never raises.
1447 """
1448 # Only `urllib.error` here: the request itself goes through `_open`, whose
1449 # `_http_only_opener` imports `urllib.request` for it.
1450 import urllib.error
1452 url = f"{self.endpoint}/models"
1453 try:
1454 with _open(url, _VERSION_PROBE_TIMEOUT) as resp: # noqa: S310
1455 return 200 <= resp.status < 500
1456 except urllib.error.HTTPError as exc:
1457 # A 4xx (e.g. 404 on /models) still means the server is up.
1458 return exc.code < 500
1459 except Exception: # noqa: BLE001 - unreachable server -> not available
1460 return False
1462 def list_models(self) -> list[str] | None:
1463 """Model ids the local server advertises, or None when it has none."""
1464 return list_local_models(self.endpoint) or None
1466 def detect_capabilities(self) -> dict:
1467 reachable = self.available()
1468 return {
1469 "version": None,
1470 "supports_headless": self.SUPPORTS_HEADLESS,
1471 "supports_model_selection": self.SUPPORTS_MODEL_SELECTION,
1472 "raw_version_output": f"local endpoint {self.endpoint}",
1473 "status": CAP_OK if reachable else CAP_UNAVAILABLE,
1474 "warnings": ([] if reachable else [f"local server unreachable at {self.endpoint}"]),
1475 }
1477 def run(
1478 self,
1479 prompt: str,
1480 phase: str = "review",
1481 timeout: int | None = None,
1482 role_policy=None,
1483 ) -> AgentResult:
1484 import json as _json
1485 import urllib.error
1486 import urllib.request
1488 del phase
1489 # A network adapter has no tools, no shell and no filesystem, so a
1490 # write-enabled role changes nothing about how it is invoked (#661).
1491 del role_policy
1492 effective_timeout = self.spec.timeout
1493 if timeout is not None:
1494 effective_timeout = max(1, min(self.spec.timeout, int(timeout)))
1495 body = _json.dumps(self.build_payload(prompt)).encode("utf-8")
1496 req = urllib.request.Request(
1497 self.completions_url(),
1498 data=body,
1499 headers={"Content-Type": "application/json"},
1500 method="POST",
1501 )
1502 start = time.monotonic()
1503 try:
1504 with _open(req, effective_timeout) as resp: # noqa: S310
1505 raw = resp.read(_MAX_RESPONSE_BYTES).decode("utf-8", errors="replace")
1506 data = _json.loads(raw)
1507 except urllib.error.HTTPError as exc:
1508 detail = ""
1509 try:
1510 detail = exc.read(_MAX_RESPONSE_BYTES).decode("utf-8", errors="replace")[:300]
1511 except Exception: # noqa: BLE001
1512 detail = exc.reason or ""
1513 # The body is from a possibly-untrusted endpoint and is surfaced in
1514 # the report; redact recognized secrets before embedding (#293/F-8).
1515 detail = redaction.redact(detail)[0]
1516 return AgentResult(
1517 self.name,
1518 self.spec.vendor,
1519 False,
1520 "",
1521 time.monotonic() - start,
1522 f"HTTP {exc.code}: {detail}",
1523 error_code=self.classify_http_status(exc.code),
1524 )
1525 except TimeoutError:
1526 return AgentResult(
1527 self.name,
1528 self.spec.vendor,
1529 False,
1530 "",
1531 time.monotonic() - start,
1532 f"timed out after {effective_timeout}s",
1533 error_code=ERR_TIMEOUT,
1534 )
1535 except urllib.error.URLError as exc:
1536 return AgentResult(
1537 self.name,
1538 self.spec.vendor,
1539 False,
1540 "",
1541 time.monotonic() - start,
1542 f"could not reach local server at {self.endpoint}: {redaction.redact(str(exc.reason))[0]}",
1543 error_code=ERR_CONNECTION,
1544 )
1545 except Exception as exc: # noqa: BLE001 - surface any other failure
1546 return AgentResult(
1547 self.name,
1548 self.spec.vendor,
1549 False,
1550 "",
1551 time.monotonic() - start,
1552 f"local request failed: {redaction.redact(str(exc))[0]}",
1553 error_code=ERR_UNKNOWN,
1554 )
1555 dur = time.monotonic() - start
1556 content = self.parse_content(data)
1557 if not content:
1558 return AgentResult(
1559 self.name,
1560 self.spec.vendor,
1561 False,
1562 "",
1563 dur,
1564 "local model returned empty content",
1565 error_code=ERR_EMPTY_OUTPUT,
1566 )
1567 no_review = no_review_reason(content)
1568 if no_review is not None:
1569 return AgentResult(
1570 self.name,
1571 self.spec.vendor,
1572 False,
1573 "",
1574 dur,
1575 f"no review returned: {no_review}",
1576 error_code=ERR_NO_REVIEW,
1577 )
1578 return AgentResult(self.name, self.spec.vendor, True, content, dur)
1581# Hosted vendor API endpoints (issue #430). Fixed, not configurable: unlike
1582# `local`'s user-supplied `endpoint` (which needs the SSRF validation in
1583# config._endpoint_issues), a hosted vendor's URL is a known constant, not an
1584# attacker- or operator-influenceable value, so there is nothing to validate.
1585_ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages"
1586_ANTHROPIC_API_VERSION = "2023-06-01"
1587_OPENAI_API_URL = "https://api.openai.com/v1/chat/completions"
1588_XAI_API_URL = "https://api.x.ai/v1/chat/completions"
1589# The Anthropic Messages API requires max_tokens on every request; there is no
1590# server-side default. Generous enough for a review response, small enough to
1591# bound cost/latency if a run is ever misconfigured to loop.
1592_HOSTED_API_MAX_TOKENS = 4096
1595def _hosted_api_status_code(status: int) -> str:
1596 """Map a hosted-API HTTP status to a typed error code (issue #430).
1598 Shared by every hosted-API adapter — identical mapping to
1599 ``LocalAdapter.classify_http_status`` (401/403 → auth, 429 → rate limit),
1600 kept as a free function since it has no per-adapter state.
1601 """
1602 if status in (401, 403):
1603 return ERR_AUTH_REQUIRED
1604 if status == 429:
1605 return ERR_RATE_LIMITED
1606 return ERR_NONZERO_EXIT
1609def _post_json(
1610 url: str, payload: dict, headers: dict[str, str], timeout: int
1611) -> tuple[dict | None, str | None, str | None]:
1612 """POST a JSON body and parse a JSON response (issue #430).
1614 Shared HTTP mechanics for the hosted-API adapters: build the request,
1615 route it through the SSRF-safe opener (``_open``, no file/ftp handlers, no
1616 redirect following — the same seam ``LocalAdapter`` uses), cap the response
1617 read at ``_MAX_RESPONSE_BYTES``, and classify any failure into a typed
1618 error code. Returns ``(response_dict, None, None)`` on success or
1619 ``(None, error_message, error_code)`` on failure — exactly one shape.
1620 Response bodies are redacted before being returned in an error message
1621 since they originate from the network and are surfaced in the report.
1622 """
1623 import json as _json
1624 import urllib.error
1625 import urllib.request
1627 body = _json.dumps(payload).encode("utf-8")
1628 req = urllib.request.Request(url, data=body, headers=headers, method="POST")
1629 try:
1630 with _open(req, timeout) as resp: # noqa: S310
1631 raw = resp.read(_MAX_RESPONSE_BYTES).decode("utf-8", errors="replace")
1632 return _json.loads(raw), None, None
1633 except urllib.error.HTTPError as exc:
1634 detail = ""
1635 try:
1636 detail = exc.read(_MAX_RESPONSE_BYTES).decode("utf-8", errors="replace")[:300]
1637 except Exception: # noqa: BLE001 - reading the error body is best-effort
1638 detail = exc.reason or ""
1639 detail = redaction.redact(detail)[0]
1640 return None, f"HTTP {exc.code}: {detail}", _hosted_api_status_code(exc.code)
1641 except TimeoutError:
1642 return None, f"timed out after {timeout}s", ERR_TIMEOUT
1643 except urllib.error.URLError as exc:
1644 return (
1645 None,
1646 f"could not reach {url}: {redaction.redact(str(exc.reason))[0]}",
1647 ERR_CONNECTION,
1648 )
1649 except Exception as exc: # noqa: BLE001 - surface any other failure
1650 return None, f"request failed: {redaction.redact(str(exc))[0]}", ERR_UNKNOWN
1653class _HostedApiAdapter(Adapter):
1654 """Shared base for hosted-vendor-API reviewers keyed by an env-var API key.
1656 No CLI install, no interactive login, no subprocess: just an HTTP call
1657 over stdlib ``urllib`` to the vendor's real hosted API (issue #430), the
1658 same no-subprocess/no-new-dependency design as ``LocalAdapter`` but
1659 pointed at a hosted endpoint instead of a local server. The API key is
1660 read from the environment ONLY, never from ``jury.toml``, so it cannot
1661 leak into a checked-in config; the endpoint is a fixed per-vendor
1662 constant, not a config value, so there is no SSRF surface to guard the
1663 way `local`'s `endpoint` needs.
1664 """
1666 SUPPORTS_HEADLESS = True
1667 SUPPORTS_MODEL_SELECTION = True
1668 SPAWNS_PROCESS = False # plain HTTP, no subprocess
1670 # The environment variable this vendor's credential is read FROM. A name,
1671 # never a value — deliberately not called `_API_KEY_*`: the constant holds
1672 # public configuration, and a credential-shaped name on a non-credential is
1673 # how both a reader and a static analyzer end up misreading this path.
1674 # Subclasses override.
1675 _ENV_VAR_NAME: str = "OPENAI_API_KEY"
1677 def _env_var_name(self) -> str:
1678 """Name of the environment variable holding this agent's credential.
1680 Rebuilt through :func:`redaction.safe_env_var_name`, because this value
1681 is *displayed* — it reaches ``jury --doctor``, its JSON export, and
1682 warning text — while ``[[agent]] api_key_env`` is an arbitrary operator
1683 string. The sanitizer both bounds it to a real env var name (so a config
1684 value cannot splice a newline into a JSON document) and severs it from
1685 the credential-shaped config field it came from. The credential VALUE
1686 never travels this way; see :meth:`_api_key`.
1687 """
1688 return redaction.safe_env_var_name(
1689 getattr(self.spec, "api_key_env", None), self._ENV_VAR_NAME
1690 )
1692 def _api_key(self) -> str:
1693 """The credential itself. NEVER rendered — only compared and sent.
1695 Kept under a deliberately sensitive name so any future flow from here
1696 into a log or an export is reported rather than blending in.
1697 """
1698 return os.environ.get(self._env_var_name(), "")
1700 def _api_url(self) -> str: # pragma: no cover - overridden
1701 raise NotImplementedError
1703 def _invalid_key_reason(self) -> str | None:
1704 """None if the key is safe to use as an HTTP header value; else why not.
1706 A key containing a control character (most plausibly a stray
1707 trailing ``\\n`` from a file/k8s-secret/`.env` mount) trips CPython's
1708 ``http.client`` header-injection guard. That guard reports the
1709 rejected value via ``repr()`` (e.g. an embedded newline becomes the
1710 two literal characters ``\\`` ``n``), which does **not** byte-for-byte
1711 match the raw key — so a literal substring scrub of the exception
1712 text (see :meth:`_scrub_secret`) cannot reliably catch it; the
1713 transformed text is no longer equal to the original secret. Validate
1714 and reject *before* the key ever reaches a header instead of trying
1715 to scrub it back out afterward.
1716 """
1717 if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in self._api_key()):
1718 return (
1719 f"{self._env_var_name()} contains a control character (e.g. a stray "
1720 f"trailing newline from how the secret was loaded) and cannot be "
1721 f"used as an HTTP header value"
1722 )
1723 return None
1725 def _scrub_secret(self, text: str) -> str:
1726 """Strip the literal API key value from an error message (issue #430).
1728 Defense-in-depth alongside ``redaction.redact()`` (which only
1729 recognizes known vendor-token *shapes* via regex) for any leak path
1730 NOT already ruled out by :meth:`_invalid_key_reason` — e.g. a
1731 well-formed key that still ends up quoted in some other library's
1732 error text. Not a substitute for that check: once a value contains
1733 control characters, downstream formatting (``repr()``, percent-
1734 encoding, ...) can transform it before it reaches an error message,
1735 and a literal match against the *original* key would then silently
1736 miss it — which is exactly why control characters are rejected
1737 upfront in :meth:`run` instead of relying on this alone.
1738 """
1739 key = self._api_key()
1740 if key and key in text:
1741 return text.replace(key, "[REDACTED]")
1742 return text
1744 def available(self) -> bool:
1745 """Available when a *usable* API key is set — a fast, network-free check.
1747 Unlike ``LocalAdapter.available()`` (which probes the server, since a
1748 local endpoint's reachability is genuinely uncertain), a hosted
1749 vendor's API is assumed reachable; the two real unknowns locally are
1750 whether the operator configured a key at all, and whether it's
1751 actually usable as a header value (see :meth:`_invalid_key_reason`) —
1752 a key that will be rejected by :meth:`run` should not report as
1753 available here either, or a capability check (``jury --doctor``)
1754 would give a falsely reassuring answer.
1755 """
1756 return bool(self._api_key()) and self._invalid_key_reason() is None
1758 def detect_capabilities(self) -> dict:
1759 key_set = bool(self._api_key())
1760 invalid_reason = self._invalid_key_reason() if key_set else None
1761 has_key = key_set and invalid_reason is None
1762 if not key_set:
1763 warnings = [f"{self._env_var_name()} is not set in the environment"]
1764 elif invalid_reason:
1765 warnings = [invalid_reason]
1766 else:
1767 warnings = []
1768 return {
1769 "version": None,
1770 "supports_headless": self.SUPPORTS_HEADLESS,
1771 "supports_model_selection": self.SUPPORTS_MODEL_SELECTION,
1772 "raw_version_output": f"hosted API {self._api_url()}",
1773 "status": CAP_OK if has_key else CAP_UNAVAILABLE,
1774 "warnings": warnings,
1775 }
1777 def build_payload(self, prompt: str) -> dict: # pragma: no cover - overridden
1778 raise NotImplementedError
1780 def _headers(self) -> dict[str, str]: # pragma: no cover - overridden
1781 raise NotImplementedError
1783 @staticmethod
1784 def parse_content(data: dict) -> str: # pragma: no cover - overridden
1785 raise NotImplementedError
1787 def run(
1788 self,
1789 prompt: str,
1790 phase: str = "review",
1791 timeout: int | None = None,
1792 role_policy=None,
1793 ) -> AgentResult:
1794 del phase
1795 # A network adapter has no tools, no shell and no filesystem, so a
1796 # write-enabled role changes nothing about how it is invoked (#661).
1797 del role_policy
1798 # Checked independently of available() (not just "not available()"):
1799 # available() now also returns False for a key that IS set but
1800 # invalid, and that case needs its own distinct error_code/message
1801 # below rather than the misleading "is not set" one.
1802 if not self._api_key():
1803 return AgentResult(
1804 self.name,
1805 self.spec.vendor,
1806 False,
1807 "",
1808 0.0,
1809 f"{self._env_var_name()} is not set in the environment",
1810 error_code=ERR_MISSING_API_KEY,
1811 )
1812 invalid_reason = self._invalid_key_reason()
1813 if invalid_reason is not None:
1814 # Reject before the key ever reaches a header — see
1815 # _invalid_key_reason for why post-hoc scrubbing can't be trusted
1816 # here. This message never echoes the key itself.
1817 return AgentResult(
1818 self.name,
1819 self.spec.vendor,
1820 False,
1821 "",
1822 0.0,
1823 invalid_reason,
1824 error_code=ERR_INVALID_API_KEY,
1825 )
1826 effective_timeout = self.spec.timeout
1827 if timeout is not None:
1828 effective_timeout = max(1, min(self.spec.timeout, int(timeout)))
1829 start = time.monotonic()
1830 data, err_msg, err_code = _post_json(
1831 self._api_url(), self.build_payload(prompt), self._headers(), effective_timeout
1832 )
1833 dur = time.monotonic() - start
1834 if err_msg is not None:
1835 return AgentResult(
1836 self.name,
1837 self.spec.vendor,
1838 False,
1839 "",
1840 dur,
1841 self._scrub_secret(err_msg),
1842 error_code=err_code,
1843 )
1844 content = self.parse_content(data or {})
1845 if not content:
1846 return AgentResult(
1847 self.name,
1848 self.spec.vendor,
1849 False,
1850 "",
1851 dur,
1852 "hosted API returned empty content",
1853 error_code=ERR_EMPTY_OUTPUT,
1854 )
1855 no_review = no_review_reason(content)
1856 if no_review is not None:
1857 return AgentResult(
1858 self.name,
1859 self.spec.vendor,
1860 False,
1861 "",
1862 dur,
1863 f"no review returned: {no_review}",
1864 error_code=ERR_NO_REVIEW,
1865 )
1866 return AgentResult(self.name, self.spec.vendor, True, content, dur)
1869class AnthropicApiAdapter(_HostedApiAdapter):
1870 """Hosted Anthropic Messages API reviewer, keyed by ``ANTHROPIC_API_KEY`` (issue #430).
1872 Configure as a normal ``[[agent]]`` with ``vendor = "anthropic-api"`` and a
1873 ``model`` (e.g. a current Claude model id) — no ``command``, no ``claude``
1874 CLI install or interactive login needed.
1875 """
1877 _ENV_VAR_NAME = "ANTHROPIC_API_KEY"
1879 def _api_url(self) -> str:
1880 return _ANTHROPIC_API_URL
1882 def build_payload(self, prompt: str) -> dict:
1883 """Build the Anthropic Messages API request body (pure).
1885 With an effort level configured, extended thinking is enabled with the
1886 mapped token budget. ``max_tokens`` must exceed that budget (thinking
1887 tokens are drawn from the same allowance), so it is raised to leave the
1888 original response allowance on top of it — bounded by
1889 :data:`_ANTHROPIC_MAX_TOKENS_CEILING`, since per-model ``max_tokens``
1890 caps vary and an unbounded sum would build a request some models reject.
1891 """
1892 payload = {
1893 "model": self.resolved_model(),
1894 "max_tokens": _HOSTED_API_MAX_TOKENS,
1895 "messages": [{"role": "user", "content": prompt}],
1896 }
1897 payload.update(self.effort_plan().payload)
1898 thinking = payload.get("thinking")
1899 if isinstance(thinking, dict):
1900 # Clamped here too, not only in effort_args, so `budget < max_tokens
1901 # <= ceiling` holds for any plan handed to this builder.
1902 budget = min(
1903 int(thinking["budget_tokens"]),
1904 _ANTHROPIC_MAX_TOKENS_CEILING - _HOSTED_API_MAX_TOKENS,
1905 )
1906 payload["thinking"] = {**thinking, "budget_tokens": budget}
1907 payload["max_tokens"] = budget + _HOSTED_API_MAX_TOKENS
1908 return payload
1910 def _headers(self) -> dict[str, str]:
1911 return {
1912 "Content-Type": "application/json",
1913 "x-api-key": self._api_key(),
1914 "anthropic-version": _ANTHROPIC_API_VERSION,
1915 }
1917 @staticmethod
1918 def parse_content(data: dict) -> str:
1919 """Extract the assistant text from a Messages API response."""
1920 if not isinstance(data, dict):
1921 return ""
1922 blocks = data.get("content") or []
1923 texts = [
1924 block.get("text", "")
1925 for block in blocks
1926 if isinstance(block, dict) and block.get("type") == "text"
1927 ]
1928 return "".join(texts).strip()
1931class OpenAiApiAdapter(_HostedApiAdapter):
1932 """Hosted OpenAI Chat Completions API reviewer, keyed by ``OPENAI_API_KEY`` (issue #430).
1934 Configure as a normal ``[[agent]]`` with ``vendor = "openai-api"`` and a
1935 ``model`` (e.g. a current GPT model id) — no ``command``, no ``codex`` CLI
1936 install or interactive login needed. Same request/response shape as
1937 ``LocalAdapter`` (both are OpenAI-compatible chat completions), just
1938 against the real hosted API with an ``Authorization`` header.
1939 """
1941 _ENV_VAR_NAME = "OPENAI_API_KEY"
1943 def _api_url(self) -> str:
1944 return _OPENAI_API_URL
1946 def build_payload(self, prompt: str) -> dict:
1947 """Build the OpenAI chat-completions request body (pure)."""
1948 payload = {
1949 "model": self.resolved_model(),
1950 "messages": [{"role": "user", "content": prompt}],
1951 }
1952 payload.update(self.effort_plan().payload)
1953 return payload
1955 def _headers(self) -> dict[str, str]:
1956 return {
1957 "Content-Type": "application/json",
1958 "Authorization": f"Bearer {self._api_key()}",
1959 }
1961 @staticmethod
1962 def parse_content(data: dict) -> str:
1963 """Extract the assistant message text from a chat-completions response."""
1964 if not isinstance(data, dict):
1965 return ""
1966 choices = data.get("choices") or []
1967 if not choices:
1968 return ""
1969 message = choices[0].get("message") or {}
1970 return (message.get("content") or "").strip()
1973class XaiApiAdapter(OpenAiApiAdapter):
1974 """Hosted xAI (Grok) API reviewer, keyed by ``XAI_API_KEY`` (issue #701).
1976 Configure as a normal ``[[agent]]`` with ``vendor = "xai-api"`` and a
1977 ``model`` (a Grok model id) — no ``command``, no CLI install. xAI serves
1978 the OpenAI chat-completions shape at its own host, so this is
1979 :class:`OpenAiApiAdapter` with a different URL and a different credential
1980 env var; the request body, the response parsing and the effort knob
1981 (``reasoning_effort``) are inherited rather than re-stated, because a
1982 second copy of them is a second thing to keep in step.
1984 ``vendor = "openai-compatible"`` with ``endpoint = "https://api.x.ai/v1"``
1985 still works and is still documented; this spelling exists so a Grok seat
1986 can carry the vendor identity ``xai-api`` instead of borrowing OpenAI's.
1987 """
1989 _ENV_VAR_NAME = "XAI_API_KEY"
1991 def _api_url(self) -> str:
1992 return _XAI_API_URL
1995_GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
1998class GoogleApiAdapter(_HostedApiAdapter):
1999 """Hosted Google Gemini API reviewer, keyed by ``GEMINI_API_KEY`` (issue #432).
2001 Configure as a normal ``[[agent]]`` with ``vendor = "google-api"`` and a
2002 ``model`` (e.g. a current Gemini model id) — no ``command``, no ``agy``
2003 CLI install or interactive login needed.
2005 Two differences from the other two hosted adapters:
2007 - The Gemini API embeds the model id in the URL **path**
2008 (``.../models/{model}:generateContent``), not the request body, so
2009 ``_api_url()`` is built from ``self.spec.model`` on every call rather
2010 than returning a fixed constant like the other two adapters.
2011 - The key is sent via the ``x-goog-api-key`` header. Gemini also accepts
2012 the key as a ``?key=...`` query parameter, but a query-string key is a
2013 much easier accidental-leak vector (proxy/access logs, anything that
2014 prints the request URL) than a header — deliberately not supported.
2016 A prompt blocked by Gemini's safety filters comes back with an empty
2017 ``candidates`` list (and a ``promptFeedback.blockReason``); this is not
2018 distinguished from a genuinely empty response and both currently surface
2019 as the same generic ``ERR_EMPTY_OUTPUT`` — a possible future refinement,
2020 not required for parity with the other two adapters.
2021 """
2023 _ENV_VAR_NAME = "GEMINI_API_KEY"
2025 def _api_url(self) -> str:
2026 # Escape the model id as a single path segment (issue #432 review): an
2027 # operator-configured model containing reserved URL characters
2028 # (`/`, `?`, `#`, ...) would otherwise change the request's path/query
2029 # semantics instead of staying a single `{model}` segment.
2030 import urllib.parse
2032 model = urllib.parse.quote(self.resolved_model(), safe="")
2033 return f"{_GEMINI_API_BASE}/{model}:generateContent"
2035 def build_payload(self, prompt: str) -> dict:
2036 """Build the Gemini ``generateContent`` request body (pure)."""
2037 payload: dict = {"contents": [{"parts": [{"text": prompt}]}]}
2038 payload.update(self.effort_plan().payload)
2039 return payload
2041 def _headers(self) -> dict[str, str]:
2042 return {
2043 "Content-Type": "application/json",
2044 "x-goog-api-key": self._api_key(),
2045 }
2047 @staticmethod
2048 def parse_content(data: dict) -> str:
2049 """Extract the assistant text from a ``generateContent`` response."""
2050 if not isinstance(data, dict):
2051 return ""
2052 candidates = data.get("candidates") or []
2053 if not candidates or not isinstance(candidates[0], dict):
2054 return ""
2055 content = candidates[0].get("content")
2056 if not isinstance(content, dict):
2057 return ""
2058 parts = content.get("parts") or []
2059 texts = [
2060 part.get("text", "")
2061 for part in parts
2062 if isinstance(part, dict) and isinstance(part.get("text", ""), str)
2063 ]
2064 return "".join(texts).strip()
2067class MockAdapter(Adapter):
2068 """Offline adapter for tests and ``--mock`` runs.
2070 Produces deterministic, phase-aware text so the full orchestration pipeline
2071 can run end-to-end without live CLIs, auth, or token spend.
2072 """
2074 # Synthetic capabilities: the mock is offline and runs no real CLI.
2075 SUPPORTS_HEADLESS = True
2076 SUPPORTS_MODEL_SELECTION = False
2078 def available(self) -> bool:
2079 return True
2081 def detect_capabilities(self) -> dict:
2082 """Deterministic fake capabilities so doctor/tests stay stable offline."""
2083 return {
2084 "version": "mock-1.0",
2085 "supports_headless": self.SUPPORTS_HEADLESS,
2086 "supports_model_selection": self.SUPPORTS_MODEL_SELECTION,
2087 "raw_version_output": "mock-1.0",
2088 "status": CAP_OK,
2089 "warnings": [],
2090 }
2092 def run(
2093 self,
2094 prompt: str,
2095 phase: str = "review",
2096 timeout: int | None = None,
2097 role_policy=None,
2098 ) -> AgentResult:
2099 del timeout, role_policy
2100 n = self.name
2101 emit_origin = "```json" not in (prompt or "") or '"origin"' in (prompt or "")
2102 origin_intro = '"origin": "introduced", ' if emit_origin else ""
2103 origin_pre = '"origin": "pre_existing", ' if emit_origin else ""
2104 if phase == "review":
2105 body = (
2106 # The two lines the review prompt asks every reviewer to open
2107 # with (#700). The mock speaks the shape a real reviewer is asked
2108 # for, so `--mock` exercises the scope/testing lift rather than
2109 # only the inference fallback behind it.
2110 "Checked: src/example.py\n"
2111 "Tested: nothing run (offline mock reviewer)\n"
2112 f"- **[major]** `src/example.py:42` — {n}: unchecked return value "
2113 f"may swallow an error.\n"
2114 f"- **[minor]** `src/example.py:7` — {n}: missing docstring.\n\n"
2115 "```json\n"
2116 "[\n"
2117 ' {"severity": "major", "file": "src/example.py", "line": 42, '
2118 f'"claim": "{n}: unchecked return value may swallow an error", '
2119 '"evidence": "the added code ignores the return value of int(x)", '
2120 '"suggested_fix": "check the result and raise on failure", '
2121 f'"confidence": "high", {origin_intro}"reviewer": "{n}"}},\n'
2122 ' {"severity": "minor", "file": "src/example.py", "line": 7, '
2123 f'"claim": "{n}: missing docstring", '
2124 '"evidence": "the existing function parse() has no docstring", '
2125 '"suggested_fix": "add a one-line docstring", '
2126 f'"confidence": "medium", {origin_pre}"reviewer": "{n}"}}\n'
2127 "]\n"
2128 "```"
2129 )
2130 elif phase == "debate":
2131 body = (
2132 f"## AGREE\n- {n}: confirm the unchecked-return finding at "
2133 f"`src/example.py:42`.\n"
2134 f"## DISPUTE\n- {n}: the missing-docstring finding is a nit, not blocking.\n"
2135 f"## MISSED\n- {n}: no test covers the error branch."
2136 )
2137 elif phase == "verify":
2138 body = (
2139 "Verification: confirming the unchecked-return finding at "
2140 "`src/example.py:42`; the missing-docstring claim at `:7` is a nit "
2141 "not supported as blocking.\n\n"
2142 "```json\n"
2143 "[\n"
2144 ' {"file": "src/example.py", "line": 42, '
2145 '"claim": "unchecked return value may swallow an error", '
2146 '"status": "verified", '
2147 '"reasoning": "the added code ignores the return value of int(x)"},\n'
2148 ' {"file": "src/example.py", "line": 7, '
2149 '"claim": "missing docstring", '
2150 '"status": "unsupported", '
2151 '"reasoning": "a missing docstring is not a defect the diff introduces"}\n'
2152 "]\n"
2153 "```"
2154 )
2155 else: # synthesis
2156 body = (
2157 "## Verdict\nREQUEST CHANGES — one confirmed major issue.\n\n"
2158 "## Consensus findings\n- **[major]** `src/example.py:42` — unchecked "
2159 "return value (raised by all reviewers).\n\n"
2160 "## Disputed findings\n- Missing docstring: ruled non-blocking.\n\n"
2161 "## Notable single-reviewer findings\n- Missing test for the error branch."
2162 )
2163 return AgentResult(n, self.spec.vendor, True, body, 0.0)
2166class GenericOpenAICompatibleAdapter(_HostedApiAdapter):
2167 """Hosted OpenAI-compatible API reviewer (OpenRouter, DeepSeek, Groq, Mistral API, LiteLLM, etc.).
2169 Supports custom ``endpoint``, custom ``api_key_env``, and extra HTTP ``headers``.
2170 """
2172 _ENV_VAR_NAME = "OPENAI_API_KEY"
2174 def _api_url(self) -> str:
2175 endpoint = (self.spec.endpoint or _OPENAI_API_URL).rstrip("/")
2176 if endpoint.endswith("/chat/completions"): 2176 ↛ 2177line 2176 didn't jump to line 2177 because the condition on line 2176 was never true
2177 return endpoint
2178 return f"{endpoint}/chat/completions"
2180 def build_payload(self, prompt: str) -> dict:
2181 payload = {
2182 "model": self.resolved_model(),
2183 "messages": [{"role": "user", "content": prompt}],
2184 }
2185 payload.update(self.effort_plan().payload)
2186 return payload
2188 def _headers(self) -> dict[str, str]:
2189 hdrs = {
2190 "Content-Type": "application/json",
2191 "Authorization": f"Bearer {self._api_key()}",
2192 }
2193 if self.spec.headers: 2193 ↛ 2195line 2193 didn't jump to line 2195 because the condition on line 2193 was always true
2194 hdrs.update(self.spec.headers)
2195 return hdrs
2197 @staticmethod
2198 def parse_content(data: dict) -> str:
2199 if not isinstance(data, dict): 2199 ↛ 2200line 2199 didn't jump to line 2200 because the condition on line 2199 was never true
2200 return ""
2201 choices = data.get("choices") or []
2202 if not choices or not isinstance(choices, list):
2203 return ""
2204 first = choices[0]
2205 if not isinstance(first, dict): 2205 ↛ 2206line 2205 didn't jump to line 2206 because the condition on line 2205 was never true
2206 return ""
2207 msg = first.get("message") or {}
2208 if not isinstance(msg, dict): 2208 ↛ 2209line 2208 didn't jump to line 2209 because the condition on line 2208 was never true
2209 return ""
2210 raw_content = msg.get("content")
2211 if isinstance(raw_content, str):
2212 return raw_content.strip()
2213 if isinstance(raw_content, list): 2213 ↛ 2224line 2213 didn't jump to line 2224 because the condition on line 2213 was always true
2214 parts = []
2215 for item in raw_content:
2216 if isinstance(item, dict): 2216 ↛ 2221line 2216 didn't jump to line 2221 because the condition on line 2216 was always true
2217 if (item.get("type") == "text" or "text" in item) and isinstance( 2217 ↛ 2215line 2217 didn't jump to line 2215 because the condition on line 2217 was always true
2218 item.get("text"), str
2219 ):
2220 parts.append(item["text"])
2221 elif isinstance(item, str):
2222 parts.append(item)
2223 return "".join(parts).strip()
2224 return ""
2227class GenericCLIAdapter(Adapter):
2228 """Generic CLI adapter for arbitrary coding-agent CLIs (Aider, Goose, OpenHands, Copilot CLI, etc.).
2230 Supports configurable prompt delivery modes:
2231 - ``prompt_mode = "stdin"`` (default): prompt passed via STDIN
2232 - ``prompt_mode = "arg"``: prompt passed as positional argument on argv
2233 """
2235 def _prompt_mode(self) -> str:
2236 return (self.spec.prompt_mode or "stdin").lower()
2238 def build_argv(self, prompt: str) -> list[str]:
2239 """Read-only argv for a configured `cli` profile.
2241 Implemented rather than inherited (the base raises) so this adapter goes
2242 through the same ``build_argv_for_role`` seam as every other one — the
2243 role policy is then decided in exactly one place for every vendor.
2244 """
2245 argv = [self.spec.command, *_read_only_extra_args(self.spec)]
2246 return [*argv, prompt] if self._prompt_mode() == "arg" else argv
2248 def build_write_argv(self, prompt: str) -> list[str]:
2249 """Write-capable argv.
2251 A `cli` profile has no vendor-specific sandbox flag to add or remove, so
2252 this resolves to the same configured ``extra_args`` as the read-only
2253 argv. It is still routed through :func:`_write_extra_args` so the rule
2254 lives with every other vendor's rather than being special-cased here.
2255 """
2256 argv = [self.spec.command, *_write_extra_args(self.spec)]
2257 return [*argv, prompt] if self._prompt_mode() == "arg" else argv
2259 def _stdin_for(self, prompt: str) -> str | None:
2260 return None if self._prompt_mode() == "arg" else prompt
2262 def _argv_too_long_hint(self, exc: BaseException, prompt: str) -> str:
2263 """Why the spawn failed, when the prompt on argv made the command line too long (#901).
2265 ``prompt_mode = "arg"`` puts the whole prompt in one argument. Linux caps
2266 one argument at 128 KiB (measured: 131071 bytes spawned, 131072 failed
2267 with ``E2BIG``), below the 200000-byte ``[jury.diff] max_bytes`` default;
2268 macOS caps the whole command line at ``ARG_MAX`` (1 MiB, also ``E2BIG``);
2269 Windows at 32767 characters, which ``CreateProcess`` reports as error 206
2270 (Microsoft's documentation; not measured here). Said, so the operator is
2271 not left with a bare "Argument list too long".
2272 """
2273 too_long = isinstance(exc, OSError) and (
2274 exc.errno == errno.E2BIG or getattr(exc, "winerror", None) == 206
2275 )
2276 if not too_long or self._prompt_mode() != "arg":
2277 return ""
2278 size = len(prompt.encode("utf-8"))
2279 return (
2280 f"; the prompt ({size} bytes) is one command-line argument "
2281 f'(prompt_mode = "arg"), longer than this system allows. Use '
2282 f'prompt_mode = "stdin" if the CLI reads its prompt from stdin, or lower '
2283 f"[jury.diff] max_bytes / chunk_max_bytes."
2284 )
2286 def available(self) -> bool:
2287 command = self.spec.command or ""
2288 if not command: 2288 ↛ 2289line 2288 didn't jump to line 2289 because the condition on line 2288 was never true
2289 return False
2290 return shutil.which(command) is not None
2292 def detect_capabilities(self) -> dict:
2293 if not self.available():
2294 return {
2295 "version": None,
2296 "supports_headless": None,
2297 "supports_model_selection": None,
2298 "raw_version_output": "",
2299 "status": CAP_UNAVAILABLE,
2300 "warnings": [f"command '{self.spec.command}' not found on PATH"],
2301 }
2302 return {
2303 "version": "generic-cli",
2304 "supports_headless": True,
2305 "supports_model_selection": bool(self.spec.model),
2306 "raw_version_output": "generic-cli",
2307 "status": CAP_OK,
2308 "warnings": [],
2309 }
2311 def run(
2312 self,
2313 prompt: str,
2314 phase: str = "review",
2315 timeout: int | None = None,
2316 role_policy=None,
2317 ) -> AgentResult:
2318 del phase
2319 if not self.available():
2320 return AgentResult(
2321 agent=self.spec.name,
2322 vendor=self.spec.vendor,
2323 ok=False,
2324 output="",
2325 duration_s=0.0,
2326 error=f"command '{self.spec.command}' not found on PATH.",
2327 error_code=ERR_MISSING_CLI,
2328 )
2329 effective_timeout = timeout if timeout is not None else self.spec.timeout
2330 argv = self.build_argv_for_role(prompt, role_policy)
2331 stdin_content = self._stdin_for(prompt)
2333 start = time.monotonic()
2334 try:
2335 res = _spawn(argv, stdin_content, timeout=effective_timeout)
2336 except subprocess.TimeoutExpired:
2337 return AgentResult(
2338 self.spec.name,
2339 self.spec.vendor,
2340 False,
2341 "",
2342 effective_timeout,
2343 f"execution timed out after {effective_timeout}s.",
2344 error_code=ERR_TIMEOUT,
2345 )
2346 except Exception as exc:
2347 duration = time.monotonic() - start
2348 return AgentResult(
2349 self.spec.name,
2350 self.spec.vendor,
2351 False,
2352 "",
2353 duration,
2354 f"failed to spawn '{self.spec.command}': {redaction.redact(str(exc))[0]}"
2355 f"{self._argv_too_long_hint(exc, prompt)}",
2356 error_code=ERR_SPAWN_FAILED,
2357 )
2359 duration = time.monotonic() - start
2360 out = (res.stdout or "").strip()
2361 err = (res.stderr or "").strip()
2363 if res.returncode != 0:
2364 detail = err or out or f"exited with code {res.returncode}"
2365 safe_detail = redaction.redact(detail)[0]
2366 err_code = classify_stderr(res.returncode, err or out)
2367 return AgentResult(
2368 self.spec.name,
2369 self.spec.vendor,
2370 False,
2371 "",
2372 duration,
2373 f"exit {res.returncode}: {safe_detail[:500]}",
2374 error_code=err_code,
2375 exit_code=res.returncode,
2376 )
2378 if not out: 2378 ↛ 2379line 2378 didn't jump to line 2379 because the condition on line 2378 was never true
2379 return AgentResult(
2380 self.spec.name,
2381 self.spec.vendor,
2382 False,
2383 "",
2384 duration,
2385 "agent produced empty output",
2386 error_code=ERR_EMPTY_OUTPUT,
2387 exit_code=res.returncode,
2388 )
2390 no_review = no_review_reason(out)
2391 if no_review is not None:
2392 return AgentResult(
2393 self.spec.name,
2394 self.spec.vendor,
2395 False,
2396 "",
2397 duration,
2398 f"no review returned: {no_review}: {redaction.redact(out)[0][:200]}",
2399 error_code=ERR_NO_REVIEW,
2400 exit_code=res.returncode,
2401 )
2403 return AgentResult(
2404 self.spec.name, self.spec.vendor, True, out, duration, exit_code=res.returncode
2405 )
2408#: The adapter registry: protocol name -> the class that builds its argv. Keyed
2409#: by vendor name because a vendor's shipped adapter IS its default protocol —
2410#: which is also why the vendor vocabulary doubles as the ``adapter`` vocabulary
2411#: (``config.recognised_adapters``). A seat naming ``adapter`` picks a row here
2412#: directly instead of inheriting its vendor's (issue #705).
2413_VENDOR_ADAPTERS: dict[str, type[Adapter]] = {
2414 "anthropic": ClaudeAdapter,
2415 "openai": CodexAdapter,
2416 "google": AgyAdapter,
2417 "local": LocalAdapter,
2418 "anthropic-api": AnthropicApiAdapter,
2419 "openai-api": OpenAiApiAdapter,
2420 "google-api": GoogleApiAdapter,
2421 "xai-api": XaiApiAdapter,
2422 "openai-compatible": GenericOpenAICompatibleAdapter,
2423 # `xai` is a bring-your-own-CLI seat (Grok through Cursor's `cursor-agent`,
2424 # issue #701): the operator supplies `command`/`extra_args`, exactly as for
2425 # `cli`, but the seat keeps its own vendor identity at the panel gate.
2426 "xai": GenericCLIAdapter,
2427 "cli": GenericCLIAdapter,
2428}
2431def register_adapter(vendor: str, adapter_cls: type[Adapter]) -> None:
2432 """Register a custom adapter class for a vendor string.
2434 The name registered is usable as BOTH a ``vendor`` and an ``adapter``
2435 (issue #705): the registry is the adapter vocabulary, so a custom adapter is
2436 selectable by a seat that keeps some other vendor identity.
2438 Registering also teaches ``config`` the name (issue #701): a vendor with an
2439 adapter behind it is a vendor this run genuinely knows, so it must not warn
2440 as unknown and must not be folded into the generic ``cli`` identity at the
2441 cross-vendor gate. The two registries are updated together so they cannot
2442 disagree about what "known" means.
2443 """
2444 name = config_module.normalise_vendor(vendor)
2445 if not name:
2446 # One guard, ahead of both tables. `register_vendor` ignores a name that is
2447 # empty after normalisation, and this used to write the adapter under the
2448 # key "" regardless — the two registries disagreeing for exactly the input
2449 # they were joined to agree on.
2450 raise ValueError("register_adapter: vendor name is empty after normalisation")
2451 config_module.register_vendor(name)
2452 # The class's own answer (#903), so a custom HTTP adapter written as a direct
2453 # `Adapter` subclass — the documented example — can say it runs no process.
2454 # Only an explicit `False` opts out: a class that says nothing, or says
2455 # `None`, spawns, which keeps it under the audit.
2456 config_module.register_adapter_transport(
2457 name, spawns=getattr(adapter_cls, "SPAWNS_PROCESS", True) is not False
2458 )
2459 _VENDOR_ADAPTERS[name] = adapter_cls
2462def _registry_state() -> tuple[dict[str, type[Adapter]], set[str], dict[str, bool]]:
2463 """A copy of every table :func:`register_adapter` writes (#904).
2465 Three tables in two modules: the adapter classes here, and ``config``'s
2466 registered vendor names and transports. Tests that register an adapter must
2467 put all three back, and restoring them one dict at a time left the ones each
2468 test forgot — a leaked name failed tests in another module, depending on the
2469 order the modules ran in. The list of tables lives here, beside the function
2470 that writes them, so a fourth table is added to the snapshot in the same place.
2471 """
2472 return (
2473 dict(_VENDOR_ADAPTERS),
2474 set(config_module._REGISTERED_VENDORS),
2475 dict(config_module._REGISTERED_ADAPTER_SPAWNS),
2476 )
2479def _restore_registry_state(state: tuple[dict, set, dict]) -> None:
2480 """Put back a :func:`_registry_state` snapshot, in place.
2482 In place, not by rebinding: other modules hold the tables by reference
2483 (``from ai_jury.adapters import _VENDOR_ADAPTERS``), and a rebound name would
2484 leave them reading the old object.
2485 """
2486 adapter_classes, vendors, spawns = state
2487 for table, saved in (
2488 (_VENDOR_ADAPTERS, adapter_classes),
2489 (config_module._REGISTERED_VENDORS, vendors),
2490 (config_module._REGISTERED_ADAPTER_SPAWNS, spawns),
2491 ):
2492 table.clear()
2493 table.update(saved)
2496def make_adapter(spec: AgentSpec, mock: bool = False) -> Adapter:
2497 """The adapter that builds *spec*'s command line.
2499 Selected by the seat's ADAPTER key, which is its ``vendor`` unless the
2500 operator named one (issue #705). Keying this on the vendor made the two
2501 inseparable: a GPT model reached through Cursor's ``cursor-agent`` got
2502 ``codex exec`` argv it cannot parse, and the only way to a passthrough argv
2503 was ``vendor = "cli"``, which cost the seat its identity at the panel gate.
2504 Nothing else about the seat moves — the ballot, the report and
2505 ``min_vendors`` all still read ``spec.vendor``.
2507 Raises ``ConfigError`` when the seat NAMES an adapter this build does not
2508 have (issue #708). The generic fall-through below still catches an unknown
2509 *vendor* — that seat named no protocol, so inheriting the generic one is the
2510 documented behaviour — but it must never catch a named one: falling through
2511 there is the silent guess #705 exists to remove, and it made every reader
2512 that builds a seat without validating the config — a caller of
2513 ``load_config`` with its default ``validate=False``, or of this function
2514 directly — disagree with the run about the very same file.
2515 """
2516 # ``or None`` mirrors ``AgentSpec.__post_init__``: an adapter that
2517 # normalises to nothing is no adapter at all, and falls back to the vendor.
2518 # A raw dict-built or hand-made spec must read the same as a loaded one.
2519 adapter_error = config_module.unknown_adapter_error(
2520 getattr(spec, "adapter", None) or None, getattr(spec, "name", "") or ""
2521 )
2522 if adapter_error is not None:
2523 raise config_module.ConfigError(adapter_error)
2524 if mock:
2525 return MockAdapter(spec)
2526 return adapter_class(spec)(spec)
2529def adapter_class(spec) -> type[Adapter]:
2530 """The adapter class :func:`make_adapter` builds for *spec* (pure, duck-typed).
2532 The ADAPTER key decides first: a registered name always gets its class,
2533 whatever else the seat carries — so an ``endpoint`` on a ``cli``, ``claude``,
2534 ``codex`` or ``agy`` seat changes nothing about how it runs. Only a seat with
2535 no registered adapter falls through to the ``endpoint``/``command`` guess.
2536 """
2537 cls = _VENDOR_ADAPTERS.get(config_module.spec_adapter(spec))
2538 if cls is not None:
2539 return cls
2540 command = getattr(spec, "command", "") or ""
2541 if getattr(spec, "endpoint", None) or (getattr(spec, "api_key_env", None) and not command):
2542 return GenericOpenAICompatibleAdapter
2543 if command:
2544 return GenericCLIAdapter
2545 return AgyAdapter