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

1"""Agent adapters — each wraps one native coding-agent CLI in headless mode. 

2 

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

7 

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

15 

16from __future__ import annotations 

17 

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 

29 

30from . import config as config_module 

31from . import privilege, redaction 

32from .config import AgentSpec 

33from .findings import emitted_findings_block 

34 

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 

39 

40 

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

49 

50 

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. 

55 

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) 

83 

84 

85@contextlib.contextmanager 

86def _review_workdir(isolate: bool): 

87 """A fresh, empty directory for one reviewer process, removed afterwards. 

88 

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. 

96 

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 

106 

107 

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. 

110 

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) 

124 

125 

126def _write_extra_args(spec: AgentSpec) -> list[str]: 

127 """The agent's ``extra_args`` with its vendor write/tool mode enabled (#661). 

128 

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) 

133 

134 

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 

138 

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+)?") 

141 

142# Capability/version probe statuses. 

143CAP_OK = "ok" 

144CAP_UNKNOWN_VERSION = "unknown_version" 

145CAP_UNAVAILABLE = "unavailable" 

146 

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" 

186 

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) 

205 

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) 

220 

221 

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

231 

232 

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) 

267 

268 

269def classify_stderr(returncode: int, stderr: str) -> str: 

270 """Classify a nonzero-exit failure into a typed error code from its stderr. 

271 

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 

289 

290 

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. 

298 

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 

303 

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 

307 

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. 

316 

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) 

326 

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) 

337 

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) 

347 

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) 

358 

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.+-]*$") 

361 

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) 

380 

381 

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 

386 

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) 

399 

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) 

405 

406#: How much text must follow a pivot before it can carry a review claim. 

407_PIVOT_MIN_CHARS = 20 

408 

409 

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 

419 

420 

421def _is_whole_output_refusal(body: str) -> bool: 

422 """True when the output *is* a decline, not a review that mentions a limit. 

423 

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) 

436 

437 

438def _is_cli_banner(body: str) -> bool: 

439 """True when ``body`` *is* a launcher's banner, not prose that mentions one. 

440 

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) 

460 

461 

462def no_review_reason(text: str) -> str | None: 

463 """Why ``text`` cannot be a review, or ``None`` when it could be one. 

464 

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. 

470 

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 

490 

491 

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. 

500 

501#: The effort levels accepted by ``[[agent]] effort`` and ``--effort``. 

502EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high") 

503 

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) 

518 

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) 

527 

528 

529@dataclass(frozen=True) 

530class EffortPlan: 

531 """How one vendor expresses a reasoning-effort level. 

532 

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

537 

538 supported: bool = True 

539 model: str | None = None 

540 payload: dict = field(default_factory=dict) 

541 warning: str | None = None 

542 

543 

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 

547 

548 

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 ) 

555 

556 

557def _effort_uses_model_listing(vendor: str) -> bool: 

558 """Whether *vendor* expresses effort through the model id (pure). 

559 

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" 

564 

565 

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

573 

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. 

578 

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

591 

592 name = config_module.normalise_vendor(vendor) 

593 

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) 

618 

619 if name == "anthropic-api": 

620 return EffortPlan( 

621 payload={ 

622 "thinking": { 

623 "type": "enabled", 

624 "budget_tokens": _anthropic_budget(level), 

625 } 

626 } 

627 ) 

628 

629 if name in ("openai-api", "xai-api", "openai-compatible"): 

630 return EffortPlan(payload={"reasoning_effort": level}) 

631 

632 if name == "google-api": 

633 return EffortPlan( 

634 payload={ 

635 "generationConfig": { 

636 "thinkingConfig": {"thinkingBudget": _GEMINI_THINKING_BUDGET[level]} 

637 } 

638 } 

639 ) 

640 

641 return EffortPlan(supported=False, warning=f"effort unsupported for {vendor}, ignored") 

642 

643 

644def effort_warnings(agents, adapter_factory=None) -> list[str]: 

645 """Deduped, ordered effort warnings for a panel — one message per run. 

646 

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. 

649 

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 

688 

689 

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 

694 

695 

696def parse_model_list(raw: str) -> list[str]: 

697 """Model ids out of a CLI's model listing (pure, best-effort, order-preserving). 

698 

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 [] 

706 

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) 

728 

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] 

737 

738 

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

771 

772 

773class Adapter: 

774 """Base adapter. Subclasses build the argv for their CLI.""" 

775 

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 

781 

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 

796 

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 

805 

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

809 

810 def __init__(self, spec: AgentSpec): 

811 self.spec = spec 

812 

813 @property 

814 def name(self) -> str: 

815 return self.spec.name 

816 

817 def available(self) -> bool: 

818 return shutil.which(self.spec.command) is not None 

819 

820 def build_argv(self, prompt: str) -> list[str]: # pragma: no cover - overridden 

821 raise NotImplementedError 

822 

823 def build_write_argv(self, prompt: str) -> list[str]: 

824 """Argv for a WRITE-capable invocation of this CLI (issue #661). 

825 

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) 

832 

833 def build_argv_for_role(self, prompt: str, policy=None) -> list[str]: 

834 """Argv for one ``jury run-agent`` role (issue #661). 

835 

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. 

840 

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) 

852 

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 

857 

858 def _text_from_stdout(self, raw: str) -> str: 

859 """The reviewer's prose, given the CLI's raw stdout. 

860 

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 

865 

866 def _version_argv(self) -> list[str]: 

867 """Argv used to probe the CLI's version.""" 

868 return [self.spec.command, *self._VERSION_ARGS] 

869 

870 def effort_plan(self) -> EffortPlan: 

871 """This agent's resolved effort mapping (see :func:`effort_args`). 

872 

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

884 

885 def resolved_model(self) -> str: 

886 """The model id this adapter sends, byte-for-byte (issue #709). 

887 

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. 

894 

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

907 

908 def list_models(self) -> list[str] | None: 

909 """Model ids this agent could be pointed at, or None when unknown. 

910 

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 

916 

917 def detect_capabilities(self) -> dict: 

918 """Best-effort probe of this agent's version and capabilities. 

919 

920 Returns a dict shaped like:: 

921 

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 } 

930 

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 } 

944 

945 # Not on PATH: report unavailable without spawning a subprocess. 

946 if not self.available(): 

947 return caps 

948 

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 

966 

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 

980 

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) 

1092 

1093 

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 

1100 

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 

1107 

1108 def build_argv(self, prompt: str) -> list[str]: 

1109 del prompt 

1110 return self._head_argv() + _read_only_extra_args(self.spec) 

1111 

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) 

1116 

1117 def _stdin_for(self, prompt: str) -> str | None: 

1118 return prompt 

1119 

1120 

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 

1127 

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" 

1135 

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 

1142 

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" 

1147 

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 

1155 

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) 

1160 

1161 def _stdin_for(self, prompt: str) -> str | None: 

1162 return prompt 

1163 

1164 

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

1183 

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 

1187 

1188 # `agy models` lists the model ids the CLI can be pointed at. 

1189 _MODELS_ARGS = ("models",) 

1190 

1191 def effort_plan(self) -> EffortPlan: 

1192 """agy's effort IS the model id, so check the mapping against its listing. 

1193 

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

1209 

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 

1215 

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 

1224 

1225 def build_argv(self, prompt: str) -> list[str]: 

1226 del prompt 

1227 return self._head_argv() + _read_only_extra_args(self.spec) 

1228 

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) 

1233 

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 

1245 

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" 

1249 

1250 def _text_from_stdout(self, raw: str) -> str: 

1251 """The `result` event's response, out of the NDJSON stream. 

1252 

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 

1276 

1277 

1278_DEFAULT_LOCAL_ENDPOINT = "http://localhost:11434/v1" 

1279 

1280 

1281def _http_only_opener(): 

1282 """An opener that handles ONLY http/https (issue #291, SSRF defense). 

1283 

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

1289 

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 

1297 

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 

1311 

1312 

1313def _open(target, timeout): 

1314 """Open an http/https URL or Request via the restricted opener (issue #291). 

1315 

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) 

1320 

1321 

1322def list_local_models(endpoint: str = _DEFAULT_LOCAL_ENDPOINT) -> list[str]: 

1323 """Model ids a local server lists, or ``[]`` — see :func:`local_model_listing`. 

1324 

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 [] 

1330 

1331 

1332def local_model_listing(endpoint: str = _DEFAULT_LOCAL_ENDPOINT) -> list[str] | None: 

1333 """List model ids from a local OpenAI-compatible server (issue #109). 

1334 

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. 

1340 

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 

1348 

1349 from .config import _endpoint_issues 

1350 

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] 

1374 

1375 

1376class LocalAdapter(Adapter): 

1377 """Open-weight / local-model reviewer over an OpenAI-compatible API (issue #43). 

1378 

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. 

1384 

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. 

1389 

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

1394 

1395 SUPPORTS_HEADLESS = True 

1396 SUPPORTS_MODEL_SELECTION = True 

1397 SPAWNS_PROCESS = False # plain HTTP, no subprocess 

1398 

1399 @property 

1400 def endpoint(self) -> str: 

1401 return (self.spec.endpoint or _DEFAULT_LOCAL_ENDPOINT).rstrip("/") 

1402 

1403 def completions_url(self) -> str: 

1404 """Resolve the chat-completions URL from the configured base endpoint. 

1405 

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" 

1413 

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 } 

1423 

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

1432 

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 

1441 

1442 def available(self) -> bool: 

1443 """A local agent is 'available' when its server answers a quick probe. 

1444 

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 

1451 

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 

1461 

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 

1465 

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 } 

1476 

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 

1487 

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) 

1579 

1580 

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 

1593 

1594 

1595def _hosted_api_status_code(status: int) -> str: 

1596 """Map a hosted-API HTTP status to a typed error code (issue #430). 

1597 

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 

1607 

1608 

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

1613 

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 

1626 

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 

1651 

1652 

1653class _HostedApiAdapter(Adapter): 

1654 """Shared base for hosted-vendor-API reviewers keyed by an env-var API key. 

1655 

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

1665 

1666 SUPPORTS_HEADLESS = True 

1667 SUPPORTS_MODEL_SELECTION = True 

1668 SPAWNS_PROCESS = False # plain HTTP, no subprocess 

1669 

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" 

1676 

1677 def _env_var_name(self) -> str: 

1678 """Name of the environment variable holding this agent's credential. 

1679 

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 ) 

1691 

1692 def _api_key(self) -> str: 

1693 """The credential itself. NEVER rendered — only compared and sent. 

1694 

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(), "") 

1699 

1700 def _api_url(self) -> str: # pragma: no cover - overridden 

1701 raise NotImplementedError 

1702 

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. 

1705 

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 

1724 

1725 def _scrub_secret(self, text: str) -> str: 

1726 """Strip the literal API key value from an error message (issue #430). 

1727 

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 

1743 

1744 def available(self) -> bool: 

1745 """Available when a *usable* API key is set — a fast, network-free check. 

1746 

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 

1757 

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 } 

1776 

1777 def build_payload(self, prompt: str) -> dict: # pragma: no cover - overridden 

1778 raise NotImplementedError 

1779 

1780 def _headers(self) -> dict[str, str]: # pragma: no cover - overridden 

1781 raise NotImplementedError 

1782 

1783 @staticmethod 

1784 def parse_content(data: dict) -> str: # pragma: no cover - overridden 

1785 raise NotImplementedError 

1786 

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) 

1867 

1868 

1869class AnthropicApiAdapter(_HostedApiAdapter): 

1870 """Hosted Anthropic Messages API reviewer, keyed by ``ANTHROPIC_API_KEY`` (issue #430). 

1871 

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

1876 

1877 _ENV_VAR_NAME = "ANTHROPIC_API_KEY" 

1878 

1879 def _api_url(self) -> str: 

1880 return _ANTHROPIC_API_URL 

1881 

1882 def build_payload(self, prompt: str) -> dict: 

1883 """Build the Anthropic Messages API request body (pure). 

1884 

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 

1909 

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 } 

1916 

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

1929 

1930 

1931class OpenAiApiAdapter(_HostedApiAdapter): 

1932 """Hosted OpenAI Chat Completions API reviewer, keyed by ``OPENAI_API_KEY`` (issue #430). 

1933 

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

1940 

1941 _ENV_VAR_NAME = "OPENAI_API_KEY" 

1942 

1943 def _api_url(self) -> str: 

1944 return _OPENAI_API_URL 

1945 

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 

1954 

1955 def _headers(self) -> dict[str, str]: 

1956 return { 

1957 "Content-Type": "application/json", 

1958 "Authorization": f"Bearer {self._api_key()}", 

1959 } 

1960 

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

1971 

1972 

1973class XaiApiAdapter(OpenAiApiAdapter): 

1974 """Hosted xAI (Grok) API reviewer, keyed by ``XAI_API_KEY`` (issue #701). 

1975 

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. 

1983 

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

1988 

1989 _ENV_VAR_NAME = "XAI_API_KEY" 

1990 

1991 def _api_url(self) -> str: 

1992 return _XAI_API_URL 

1993 

1994 

1995_GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta/models" 

1996 

1997 

1998class GoogleApiAdapter(_HostedApiAdapter): 

1999 """Hosted Google Gemini API reviewer, keyed by ``GEMINI_API_KEY`` (issue #432). 

2000 

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. 

2004 

2005 Two differences from the other two hosted adapters: 

2006 

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. 

2015 

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

2022 

2023 _ENV_VAR_NAME = "GEMINI_API_KEY" 

2024 

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 

2031 

2032 model = urllib.parse.quote(self.resolved_model(), safe="") 

2033 return f"{_GEMINI_API_BASE}/{model}:generateContent" 

2034 

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 

2040 

2041 def _headers(self) -> dict[str, str]: 

2042 return { 

2043 "Content-Type": "application/json", 

2044 "x-goog-api-key": self._api_key(), 

2045 } 

2046 

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

2065 

2066 

2067class MockAdapter(Adapter): 

2068 """Offline adapter for tests and ``--mock`` runs. 

2069 

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

2073 

2074 # Synthetic capabilities: the mock is offline and runs no real CLI. 

2075 SUPPORTS_HEADLESS = True 

2076 SUPPORTS_MODEL_SELECTION = False 

2077 

2078 def available(self) -> bool: 

2079 return True 

2080 

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 } 

2091 

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) 

2164 

2165 

2166class GenericOpenAICompatibleAdapter(_HostedApiAdapter): 

2167 """Hosted OpenAI-compatible API reviewer (OpenRouter, DeepSeek, Groq, Mistral API, LiteLLM, etc.). 

2168 

2169 Supports custom ``endpoint``, custom ``api_key_env``, and extra HTTP ``headers``. 

2170 """ 

2171 

2172 _ENV_VAR_NAME = "OPENAI_API_KEY" 

2173 

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" 

2179 

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 

2187 

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 

2196 

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

2225 

2226 

2227class GenericCLIAdapter(Adapter): 

2228 """Generic CLI adapter for arbitrary coding-agent CLIs (Aider, Goose, OpenHands, Copilot CLI, etc.). 

2229 

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

2234 

2235 def _prompt_mode(self) -> str: 

2236 return (self.spec.prompt_mode or "stdin").lower() 

2237 

2238 def build_argv(self, prompt: str) -> list[str]: 

2239 """Read-only argv for a configured `cli` profile. 

2240 

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 

2247 

2248 def build_write_argv(self, prompt: str) -> list[str]: 

2249 """Write-capable argv. 

2250 

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 

2258 

2259 def _stdin_for(self, prompt: str) -> str | None: 

2260 return None if self._prompt_mode() == "arg" else prompt 

2261 

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

2264 

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 ) 

2285 

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 

2291 

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 } 

2310 

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) 

2332 

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 ) 

2358 

2359 duration = time.monotonic() - start 

2360 out = (res.stdout or "").strip() 

2361 err = (res.stderr or "").strip() 

2362 

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 ) 

2377 

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 ) 

2389 

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 ) 

2402 

2403 return AgentResult( 

2404 self.spec.name, self.spec.vendor, True, out, duration, exit_code=res.returncode 

2405 ) 

2406 

2407 

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} 

2429 

2430 

2431def register_adapter(vendor: str, adapter_cls: type[Adapter]) -> None: 

2432 """Register a custom adapter class for a vendor string. 

2433 

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. 

2437 

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 

2460 

2461 

2462def _registry_state() -> tuple[dict[str, type[Adapter]], set[str], dict[str, bool]]: 

2463 """A copy of every table :func:`register_adapter` writes (#904). 

2464 

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 ) 

2477 

2478 

2479def _restore_registry_state(state: tuple[dict, set, dict]) -> None: 

2480 """Put back a :func:`_registry_state` snapshot, in place. 

2481 

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) 

2494 

2495 

2496def make_adapter(spec: AgentSpec, mock: bool = False) -> Adapter: 

2497 """The adapter that builds *spec*'s command line. 

2498 

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

2506 

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) 

2527 

2528 

2529def adapter_class(spec) -> type[Adapter]: 

2530 """The adapter class :func:`make_adapter` builds for *spec* (pure, duck-typed). 

2531 

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