Coverage for src/governed_harness/agents/native.py: 86%

401 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""Built-in adapters for agent CLIs (``agentProviders.<id>.kind``, since 2.0). 

2 

3A command provider has to speak the harness JSON protocol, so every agent needed a wrapper 

4written by the user. A built-in adapter runs the agent CLI itself in its documented 

5non-interactive mode, renders the request (task, plan, governed memory, the feedback of a 

6correction attempt and, with ``provenance.selfReport``, the self-report instructions) as a 

7prompt, and reads the CLI's own output: the status, a summary, the session id and, when the CLI 

8reports them, tokens and cost as ``REPORTED`` usage. 

9 

10The adapters run through the same governed process runner as any provider: the executable needs 

11a ``process.execute`` grant, the call runs under ``runtime.agentSandbox`` and receives only the 

12environment the provider declares (``passEnv``, ``env``). The command lines below follow each 

13CLI's documentation; they are covered by tests against fake CLIs that print the documented 

14output formats, not against the live agents. 

15 

16=========== ============ =================================================================== 

17kind executable arguments (before ``args``) 

18=========== ============ =================================================================== 

19claude-code ``claude`` ``-p --output-format json --permission-mode acceptEdits`` 

20 (``--model``); prompt on stdin 

21codex ``codex`` ``exec --json --full-auto --skip-git-repo-check`` (``--model``); 

22 prompt on stdin (``-``) 

23gemini-cli ``gemini`` ``--output-format json --approval-mode auto_edit`` (``--model``); 

24 prompt on stdin, ``--prompt`` points to it 

25aider ``aider`` ``--yes-always --no-auto-commits --no-dirty-commits --no-stream 

26 --no-pretty --no-gitignore --no-check-update --analytics-disable`` 

27 and history files in the null device (``--model``); prompt in 

28 ``--message`` 

29=========== ============ =================================================================== 

30 

31A read-only request (``readOnly: true``: ``clarify``, ``plan``, ``acceptance``, ``locate``, 

32``architecture``, ``review`` and the reviewers of the panel) runs with the CLI's read-only 

33arguments instead (#92), so that the agent has no tool to write with; the workspace comparison 

34of the harness stays as the check that does not depend on the CLI: 

35 

36=========== ======================================================================== 

37kind arguments of a read-only call (before ``args``) 

38=========== ======================================================================== 

39claude-code ``-p --output-format json --permission-mode default --allowedTools 

40 Read,Grep,Glob`` and ``--disallowedTools Write Edit MultiEdit 

41 NotebookEdit Bash`` (a reviewer keeps its own allowlist without those) 

42codex ``exec --json --sandbox read-only --skip-git-repo-check`` 

43gemini-cli ``--output-format json --approval-mode default``: without an approval 

44 mode that accepts edits, the non-interactive CLI leaves out the tools 

45 that ask (write, edit, shell); it has no tool allowlist option here 

46aider the base arguments with ``--chat-mode ask --dry-run 

47 --no-suggest-shell-commands``: aider has no read-only sandbox; these ask 

48 it to answer without editing or running commands 

49=========== ======================================================================== 

50 

51Like the base arguments, the read-only ones follow each CLI's documentation and are not 

52verified against the live agents. 

53""" 

54 

55from __future__ import annotations 

56 

57import json 

58import os 

59import re 

60from collections.abc import Mapping 

61from typing import Any 

62 

63from governed_harness.agents.base import AgentContext 

64from governed_harness.agents.command import ( 

65 CommandAgentConfiguration, 

66 CommandAgentProvider, 

67 ProviderAnswer, 

68 request_routing, 

69) 

70from governed_harness.agents.self_report import PROMPT_INSTRUCTIONS, extract_from_text 

71from governed_harness.configuration.models import NATIVE_DEFAULT_COMMANDS 

72from governed_harness.domain.enums import ResultStatus 

73from governed_harness.runtime.process_runner import ProcessResult 

74 

75SUMMARY_CHARS = 2000 

76STDERR_TAIL_CHARS = 400 

77PROMPT_PLACEHOLDER = "<prompt>" 

78"""Recorded in place of a prompt passed on the command line (aider).""" 

79MCP_PLACEHOLDER = "<mcp-config>" 

80"""Recorded in place of the MCP configuration of a reviewer (it may carry credentials).""" 

81 

82READ_ONLY_TOOLS: tuple[str, ...] = ("Read", "Grep", "Glob") 

83"""The Claude Code tools of a read-only call (#92).""" 

84CLAUDE_WRITE_TOOLS: tuple[str, ...] = ("Write", "Edit", "MultiEdit", "NotebookEdit", "Bash") 

85"""The Claude Code tools a read-only call is denied: the ones that write files and the shell.""" 

86_OUTPUT_FORMAT = "--output-format" 

87_PERMISSION_MODE = "--permission-mode" 

88_APPROVAL_MODE = "--approval-mode" 

89_SKIP_GIT_CHECK = "--skip-git-repo-check" 

90 

91DEFAULT_EXECUTABLES = NATIVE_DEFAULT_COMMANDS 

92 

93 

94def render_prompt(request: dict[str, Any], *, self_report: bool) -> str: 

95 """The request as instructions for an agent that reads text.""" 

96 task = request["task"] 

97 plan = request.get("plan") or {} 

98 lines = [ 

99 ( 

100 "You are implementing a task in the repository in the current directory, under the " 

101 "Governed Agent Harness. Edit the files needed to meet the acceptance criteria. Do not " 

102 "commit, push or create branches; the harness verifies your change and a person " 

103 "decides." 

104 ), 

105 "", 

106 f"# Task {task['task_id']}: {task['title']}", 

107 "", 

108 str(task["intent"]).strip(), 

109 ] 

110 lines += _task_sections(task) 

111 lines += _change_sections(task) 

112 if plan.get("steps"): 

113 lines += ["", "## Plan"] 

114 lines += [ 

115 f"{index}. {step['description']}" for index, step in enumerate(plan["steps"], start=1) 

116 ] 

117 lines += _memory_section(request.get("context")) 

118 lines += _closing_sections(request, self_report=self_report) 

119 return "\n".join(lines).rstrip() + "\n" 

120 

121 

122def _task_sections(task: dict[str, Any]) -> list[str]: 

123 """The requirements, acceptance criteria and constraints of the task.""" 

124 lines: list[str] = [] 

125 if task.get("requirements"): 125 ↛ 126line 125 didn't jump to line 126 because the condition on line 125 was never true

126 lines += ["", "## Requirements"] 

127 lines += [f"- {item['requirement_id']}: {item['text']}" for item in task["requirements"]] 

128 if task.get("acceptance_criteria"): 

129 lines += ["", "## Acceptance criteria"] 

130 for item in task["acceptance_criteria"]: 

131 hint = ( 

132 f" (verify: {item['verification_hint']})" if item.get("verification_hint") else "" 

133 ) 

134 lines.append( 

135 f"- {item['criterion_id']} [{item.get('priority', 'MUST')}]: {item['text']}{hint}" 

136 ) 

137 if task.get("constraints"): 137 ↛ 138line 137 didn't jump to line 138 because the condition on line 137 was never true

138 lines += ["", "## Constraints"] 

139 lines += [f"- {item}" for item in task["constraints"]] 

140 return lines 

141 

142 

143def _change_sections(task: dict[str, Any]) -> list[str]: 

144 """The patches to apply (patch mode) and the files the agent may change.""" 

145 lines: list[str] = [] 

146 owned = (task.get("metadata") or {}).get("ownedPaths") 

147 implementation = task.get("implementation") or {} 

148 if implementation.get("mode") == "patch": 148 ↛ 149line 148 didn't jump to line 149 because the condition on line 148 was never true

149 owned = owned or [patch["path"] for patch in implementation.get("patches", [])] 

150 lines += ["", "## Changes to apply"] 

151 for patch in implementation.get("patches", []): 

152 lines.append(f"- {patch['operation']} {patch['path']}") 

153 if patch.get("content") is not None: 

154 lines += ["```", str(patch["content"]).rstrip("\n"), "```"] 

155 if owned: 

156 lines += ["", "## Files you may change"] 

157 lines += [f"- {path}" for path in owned] 

158 return lines 

159 

160 

161def _memory_section(context: Any) -> list[str]: 

162 """The project memory records approved for the task; none without records.""" 

163 if not context or not context.get("records"): 163 ↛ 165line 163 didn't jump to line 165 because the condition on line 163 was always true

164 return [] 

165 lines = ["", "## Project memory approved for this task"] 

166 for record in context["records"]: 

167 value = record.get("value") 

168 text = value.get("text") if isinstance(value, dict) else None 

169 lines.append(f"- {text or json.dumps(value, sort_keys=True)}") 

170 return lines 

171 

172 

173def _closing_sections(request: dict[str, Any], *, self_report: bool) -> list[str]: 

174 """The feedback, the agent-results extras, the quoted untrusted content and the 

175 self-report instructions, in that order.""" 

176 lines: list[str] = [] 

177 feedback = request.get("feedback") 

178 if feedback: 

179 lines += ["", *_feedback_lines(feedback)] 

180 extras = implement_extras_lines(request) 

181 if extras: 

182 lines += ["", *extras] 

183 untrusted = request.get("untrustedContent") 

184 if isinstance(untrusted, dict): 

185 from governed_harness.capabilities.repository import quoted_lines 

186 

187 lines += ["", *quoted_lines(untrusted)] 

188 if self_report: 

189 lines += ["", "## Self-report", PROMPT_INSTRUCTIONS] 

190 return lines 

191 

192 

193def _feedback_lines(feedback: dict[str, Any]) -> list[str]: 

194 lines = [ 

195 f"## Why the previous attempt was not accepted (attempt {feedback.get('attempt')}, " 

196 f"{feedback.get('trigger')})" 

197 ] 

198 gate = feedback.get("gate") or {} 

199 if gate: 

200 codes = ", ".join(gate.get("reasonCodes") or []) or "none" 

201 lines.append(f"Gate {gate.get('gateId')}: {gate.get('status')} ({codes})") 

202 for finding in feedback.get("findings") or []: 

203 lines.append(_feedback_finding_line(finding)) 

204 for validator in feedback.get("validators") or []: 

205 lines += _feedback_validator_lines(validator) 

206 decision = feedback.get("decision") 

207 if decision: 207 ↛ 208line 207 didn't jump to line 208 because the condition on line 207 was never true

208 lines.append( 

209 f"The reviewer ({decision.get('actorId')}) asked for changes: " 

210 f"{decision.get('rationale')}" 

211 ) 

212 return lines 

213 

214 

215def _feedback_finding_line(finding: dict[str, Any]) -> str: 

216 location = finding.get("location") or {} 

217 where = location.get("path") or "" 

218 if where and location.get("startLine"): 218 ↛ 220line 218 didn't jump to line 220 because the condition on line 218 was always true

219 where = f"{where}:{location['startLine']}" 

220 return ( 

221 f"- {finding.get('severity')} {finding.get('ruleId')}" 

222 f"{' at ' + where if where else ''}: {finding.get('message')}" 

223 ) 

224 

225 

226def _feedback_validator_lines(validator: dict[str, Any]) -> list[str]: 

227 lines = [ 

228 f"Validator {validator.get('validatorId')} {validator.get('status')} " 

229 f"(exit {validator.get('exitCode')})" 

230 ] 

231 for stream in ("stdout", "stderr"): 

232 text = (validator.get(stream) or "").strip() 

233 if text: 

234 lines += [f"{stream}:", "```", text, "```"] 

235 return lines 

236 

237 

238_CALL_KEYS_LEFT_OUT = frozenset({"instructions", "schemaVersion", "kind", "readOnly", "isolation"}) 

239_IMPLEMENT_EXTRAS = ( 

240 "gate", 

241 "permissions", 

242 "contextFiles", 

243 "lessons", 

244 "acceptanceTests", 

245 "budget", 

246 "commandPolicy", 

247 "agentContract", 

248 "scriptContracts", 

249) 

250 

251 

252def render_call_prompt(request: dict[str, Any]) -> str: 

253 """A read-only request (``clarify``, ``acceptance``, ``plan``, ``review``, since 2.0) as 

254 text: the rendered instructions, then the request itself as JSON.""" 

255 payload = {key: value for key, value in request.items() if key not in _CALL_KEYS_LEFT_OUT} 

256 return ( 

257 f"{request.get('instructions', '')}\n\n" 

258 "The request, as JSON:\n\n```json\n" 

259 f"{json.dumps(payload, indent=2, sort_keys=True)}\n```\n\n" 

260 "End your answer with the JSON object described above, on its own, so the harness can " 

261 "read it.\n" 

262 ) 

263 

264 

265def implement_extras_lines(request: dict[str, Any]) -> list[str]: 

266 """What the agent-results settings add to an implement request (gate contract, 

267 permissions, context manifest, lessons, frozen acceptance tests, budget), as text.""" 

268 present = {key: request[key] for key in _IMPLEMENT_EXTRAS if request.get(key)} 

269 if not present: 

270 return [] 

271 return [ 

272 "## What the harness will check and what you may use", 

273 "```json", 

274 json.dumps(present, indent=2, sort_keys=True), 

275 "```", 

276 ] 

277 

278 

279def extract_call_result(text: str) -> Any: 

280 """The ``result`` object of a read-only call from a CLI's output: the last JSON object 

281 with a ``result`` key found in the output or in any text field of it.""" 

282 candidates: list[str] = [text] 

283 for line in [text, *text.splitlines()]: 

284 try: 

285 value = json.loads(line) 

286 except ValueError: 

287 continue 

288 candidates.extend(_strings(value)) 

289 for candidate in reversed(candidates): 

290 found = _last_result_object(candidate) 

291 if found is not None: 

292 return found 

293 return None 

294 

295 

296def _strings(value: Any) -> list[str]: 

297 if isinstance(value, str): 

298 return [value] 

299 if isinstance(value, dict): 

300 return [text for item in value.values() for text in _strings(item)] 

301 if isinstance(value, list): 301 ↛ 302line 301 didn't jump to line 302 because the condition on line 301 was never true

302 return [text for item in value for text in _strings(item)] 

303 return [] 

304 

305 

306def _last_result_object(text: str) -> Any: 

307 decoder = json.JSONDecoder() 

308 found: Any = None 

309 index = text.find("{") 

310 while index != -1: 

311 try: 

312 value, end = decoder.raw_decode(text, index) 

313 except ValueError: 

314 index = text.find("{", index + 1) 

315 continue 

316 if isinstance(value, dict) and isinstance(value.get("result"), dict): 316 ↛ 318line 316 didn't jump to line 318 because the condition on line 316 was always true

317 found = value["result"] 

318 index = text.find("{", end) 

319 return found 

320 

321 

322def _tail(text: str, chars: int = STDERR_TAIL_CHARS) -> str: 

323 text = " ".join(text.strip().split()) 

324 return text[-chars:] 

325 

326 

327def _summary(text: Any) -> str: 

328 value = str(text or "").strip() 

329 return value[:SUMMARY_CHARS] if value else "" 

330 

331 

332def _int(value: Any) -> int | None: 

333 return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None 

334 

335 

336def _usage(**values: int | float | None) -> dict[str, int | float] | None: 

337 kept = {name: value for name, value in values.items() if value is not None} 

338 return kept or None 

339 

340 

341class NativeAgentProvider(CommandAgentProvider): 

342 """Base of the built-in adapters: a prompt instead of the JSON request, the CLI's own 

343 output instead of the protocol answer.""" 

344 

345 kind = "" 

346 stdout_media_type = "text/plain" 

347 prompt_on_stdin = True 

348 

349 def capabilities(self) -> tuple[str, ...]: 

350 return ("external_cli", "native_adapter", self.kind) 

351 

352 def base_args(self) -> tuple[str, ...]: 

353 raise NotImplementedError 

354 

355 def isolated_args(self, isolation: Mapping[str, Any]) -> tuple[str, ...] | None: 

356 """The base arguments of a reviewer of the review panel (#57): read-only, with the 

357 reviewer's tool allowlist and a strict MCP configuration, read from the request's 

358 isolation mapping (``tools``, ``mcpConfig``). ``None``: the CLI has no such options and 

359 keeps its base arguments (the agent sandbox and the workspace comparison still keep the 

360 call read-only); the adapters that have them override this method.""" 

361 return None 

362 

363 def read_only_args(self) -> tuple[str, ...] | None: 

364 """The base arguments of a read-only call (#92): the CLI's mode without write tools. 

365 ``None``: the CLI has none and keeps its base arguments.""" 

366 return None 

367 

368 def call_args(self, request: Mapping[str, object]) -> tuple[str, ...]: 

369 """The base arguments of a request: a reviewer's isolation first, then the read-only 

370 mode of a request that says ``readOnly``, else the arguments that let the agent edit.""" 

371 isolation = request.get("isolation") 

372 chosen = self.isolated_args(isolation) if isinstance(isolation, Mapping) else None 

373 if chosen is None and request.get("readOnly") is True: 

374 chosen = self.read_only_args() 

375 return chosen if chosen is not None else self.base_args() 

376 

377 def policy_args( 

378 self, 

379 policy: Any, 

380 *, 

381 read_only: bool = False, # NOSONAR(S1172) hook: the CLI adapters override it 

382 ) -> tuple[str, ...]: 

383 """The CLI options of the command policy (#5) and, for a read-only call, of the tools 

384 it is denied (#92); none for a CLI without them.""" 

385 return () 

386 

387 def model_args(self, routing: Mapping[str, str] | None = None) -> tuple[str, ...]: 

388 """``--model`` of the configured model, or of the model the router chose for the call 

389 (``agentRouting``, since 2.0), followed by the CLI's effort option.""" 

390 routing = routing or {} 

391 model = routing.get("model") or self.configuration.model 

392 effort = routing.get("effort") 

393 return (("--model", model) if model else ()) + (self.effort_args(effort) if effort else ()) 

394 

395 def effort_args(self, effort: str) -> tuple[str, ...]: # NOSONAR(S1172) hook to override 

396 """The CLI's reasoning-effort option; a CLI without one ignores the router's effort.""" 

397 return () 

398 

399 def prompt_args(self, prompt: str) -> tuple[str, ...]: # NOSONAR(S1172) hook to override 

400 return () 

401 

402 def process_input( 

403 self, request: dict[str, object], context: AgentContext 

404 ) -> tuple[tuple[str, ...], bytes | None, tuple[str, ...]]: 

405 kind = request.get("kind") 

406 if kind is not None and kind != "implement": 

407 prompt = render_call_prompt(request) 

408 else: 

409 prompt = render_prompt(request, self_report=self.configuration.self_report) 

410 head = ( 

411 *self.configuration.argv_prefix, 

412 *self.call_args(request), 

413 *self.model_args(request_routing(request)), 

414 *self.policy_args( 

415 request.get("commandPolicy"), read_only=request.get("readOnly") is True 

416 ), 

417 *self.configuration.extra_args, 

418 ) 

419 tail = self.prompt_args(prompt) 

420 recorded = ( 

421 *(MCP_PLACEHOLDER if item.startswith('{"mcpServers"') else item for item in head), 

422 *(PROMPT_PLACEHOLDER if item == prompt else item for item in tail), 

423 ) 

424 stdin = prompt.encode("utf-8") if self.prompt_on_stdin else None 

425 return (*head, *tail), stdin, recorded 

426 

427 def failure_summary(self, result: ProcessResult) -> str: 

428 tail = _tail(result.stderr.decode("utf-8", "replace")) or _tail( 

429 result.stdout.decode("utf-8", "replace") 

430 ) 

431 summary = f"{self.kind} exited with {result.exit_code}" 

432 return f"{summary}: {tail}" if tail else summary 

433 

434 def _self_report_from(self, text: str) -> Any: 

435 return extract_from_text(text) if self.configuration.self_report else None 

436 

437 def extract_result(self, result: ProcessResult) -> Any: 

438 return extract_call_result(result.stdout.decode("utf-8", "replace")) 

439 

440 

441class ClaudeCodeProvider(NativeAgentProvider): 

442 """``claude -p --output-format json``: one JSON object with ``result``, ``is_error``, 

443 ``session_id``, ``total_cost_usd`` and ``usage``.""" 

444 

445 kind = "claude-code" 

446 

447 def base_args(self) -> tuple[str, ...]: 

448 return ("-p", _OUTPUT_FORMAT, "json", _PERMISSION_MODE, "acceptEdits") 

449 

450 def read_only_args(self) -> tuple[str, ...] | None: 

451 return self._allowing(READ_ONLY_TOOLS) 

452 

453 @staticmethod 

454 def _allowing(tools: tuple[str, ...]) -> tuple[str, ...]: 

455 """Print mode without accepted edits and with ``tools`` as the allowlist.""" 

456 return ( 

457 "-p", 

458 _OUTPUT_FORMAT, 

459 "json", 

460 _PERMISSION_MODE, 

461 "default", 

462 "--allowedTools", 

463 ",".join(tools), 

464 ) 

465 

466 def isolated_args(self, isolation: Mapping[str, Any]) -> tuple[str, ...] | None: 

467 # #92: a reviewer never keeps a tool that writes, whatever its definition lists. 

468 tools = tuple( 

469 str(item) 

470 for item in isolation.get("tools") or [] 

471 if str(item).split("(", 1)[0] not in CLAUDE_WRITE_TOOLS 

472 ) 

473 servers = isolation.get("mcpConfig") 

474 mcp = {"mcpServers": dict(servers) if isinstance(servers, Mapping) else {}} 

475 return ( 

476 *self._allowing(tools), 

477 "--strict-mcp-config", 

478 "--mcp-config", 

479 json.dumps(mcp, sort_keys=True), 

480 "--setting-sources", 

481 "project", 

482 ) 

483 

484 def effort_args(self, effort: str) -> tuple[str, ...]: 

485 return ("--effort", effort) 

486 

487 def policy_args(self, policy: Any, *, read_only: bool = False) -> tuple[str, ...]: 

488 from governed_harness.capabilities.repository import CLAUDE_DISALLOWED 

489 

490 if read_only: 

491 # One option: denying Bash covers the destructive commands of the policy too. 

492 return ("--disallowedTools", *CLAUDE_WRITE_TOOLS) 

493 if isinstance(policy, Mapping) and policy.get("destructive") == "deny": 

494 return ("--disallowedTools", *CLAUDE_DISALLOWED) 

495 return () 

496 

497 def read_answer(self, result: ProcessResult) -> ProviderAnswer: 

498 value = _claude_result(json.loads(result.stdout)) 

499 failed = bool(value.get("is_error")) or value.get("subtype", "success") != "success" 

500 text = _summary(value.get("result")) 

501 return ProviderAnswer( 

502 status=ResultStatus.FAILED if failed else ResultStatus.PASSED, 

503 summary=text or f"claude-code {value.get('subtype', 'finished')}", 

504 usage=_claude_usage(value), 

505 usage_limitations=( 

506 "Claude Code: inputTokens adds input, cache-creation and cache-read tokens " 

507 "(cacheTokens is their cache part, cacheReadTokens its cache-read part); " 

508 "costUsd is total_cost_usd.", 

509 ), 

510 session_id=value.get("session_id") 

511 if isinstance(value.get("session_id"), str) 

512 else None, 

513 self_report=self._self_report_from(str(value.get("result") or "")), 

514 ) 

515 

516 

517def _claude_result(value: Any) -> dict[str, Any]: 

518 """The result object of Claude Code's output; a protocol error without one.""" 

519 if isinstance(value, list): # --verbose prints every message; the last one is the result 519 ↛ 520line 519 didn't jump to line 520 because the condition on line 519 was never true

520 results = [ 

521 item for item in value if isinstance(item, dict) and item.get("type") == "result" 

522 ] 

523 value = results[-1] if results else None 

524 if not isinstance(value, dict) or ("result" not in value and "is_error" not in value): 524 ↛ 525line 524 didn't jump to line 525 because the condition on line 524 was never true

525 raise ValueError("claude output is not a result object") 

526 return value 

527 

528 

529def _claude_usage(value: dict[str, Any]) -> dict[str, int | float] | None: 

530 """The usage of a Claude Code result: input adds the cache tokens (creation and read), 

531 the cache reads are also kept apart, cost is the total.""" 

532 raw_usage = value.get("usage") 

533 usage: dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {} 

534 inputs = [ 

535 _int(usage.get(name)) 

536 for name in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens") 

537 ] 

538 cost = value.get("total_cost_usd") 

539 return _usage( 

540 inputTokens=sum(item for item in inputs if item is not None) 

541 if any(item is not None for item in inputs) 

542 else None, 

543 outputTokens=_int(usage.get("output_tokens")), 

544 cacheTokens=sum(item for item in inputs[1:] if item is not None) 

545 if any(item is not None for item in inputs[1:]) 

546 else None, 

547 cacheReadTokens=inputs[2], 

548 costUsd=cost 

549 if isinstance(cost, int | float) and not isinstance(cost, bool) and cost >= 0 

550 else None, 

551 ) 

552 

553 

554class CodexProvider(NativeAgentProvider): 

555 """``codex exec --json``: one JSON event per line; ``turn.completed`` carries the usage, 

556 ``item.completed`` with an ``agent_message`` the answer, ``turn.failed`` or ``error`` a 

557 failure.""" 

558 

559 kind = "codex" 

560 

561 def base_args(self) -> tuple[str, ...]: 

562 return ("exec", "--json", "--full-auto", _SKIP_GIT_CHECK) 

563 

564 def read_only_args(self) -> tuple[str, ...] | None: 

565 return ("exec", "--json", "--sandbox", "read-only", _SKIP_GIT_CHECK) 

566 

567 def isolated_args(self, isolation: Mapping[str, Any]) -> tuple[str, ...] | None: 

568 return self.read_only_args() 

569 

570 def effort_args(self, effort: str) -> tuple[str, ...]: 

571 return ("-c", f'model_reasoning_effort="{effort}"') 

572 

573 def prompt_args(self, prompt: str) -> tuple[str, ...]: 

574 return ("-",) 

575 

576 def read_answer(self, result: ProcessResult) -> ProviderAnswer: 

577 events = _json_events(result.stdout) 

578 if not events: 578 ↛ 579line 578 didn't jump to line 579 because the condition on line 578 was never true

579 raise ValueError("codex printed no JSON events") 

580 run = _CodexRun() 

581 for event in events: 

582 run.add(event) 

583 totals, seen = run.totals, run.seen 

584 answer = run.messages[-1] if run.messages else "" 

585 return ProviderAnswer( 

586 status=ResultStatus.FAILED if run.failure else ResultStatus.PASSED, 

587 summary=_summary(run.failure or answer) or "codex finished", 

588 usage=_usage( 

589 inputTokens=totals["input"] if seen else None, 

590 outputTokens=totals["output"] if seen else None, 

591 reasoningTokens=totals["reasoning"] if seen and totals["reasoning"] else None, 

592 cacheTokens=totals["cache"] if seen and totals["cache"] else None, 

593 # Codex's cached_input_tokens are prompt-cache reads, part of input_tokens. 

594 cacheReadTokens=totals["cache"] if seen and totals["cache"] else None, 

595 ), 

596 usage_limitations=("Codex reports tokens per turn and no cost.",), 

597 session_id=run.session, 

598 self_report=self._self_report_from(answer), 

599 ) 

600 

601 

602def _json_events(stdout: bytes) -> list[dict[str, Any]]: 

603 """The JSON objects printed one per line; other lines are skipped.""" 

604 events = [] 

605 for line in stdout.decode("utf-8", "replace").splitlines(): 

606 line = line.strip() 

607 if not line.startswith("{"): 607 ↛ 608line 607 didn't jump to line 608 because the condition on line 607 was never true

608 continue 

609 try: 

610 event = json.loads(line) 

611 except json.JSONDecodeError: 

612 continue 

613 if isinstance(event, dict): 613 ↛ 605line 613 didn't jump to line 605 because the condition on line 613 was always true

614 events.append(event) 

615 return events 

616 

617 

618class _CodexRun: 

619 """What the events of one ``codex exec --json`` run report, folded in order.""" 

620 

621 def __init__(self) -> None: 

622 self.totals = {"input": 0, "output": 0, "reasoning": 0, "cache": 0} 

623 self.seen = False 

624 self.messages: list[str] = [] 

625 self.failure: str | None = None 

626 self.session: str | None = None 

627 

628 def add(self, event: dict[str, Any]) -> None: 

629 kind = event.get("type") 

630 if kind == "thread.started" and isinstance(event.get("thread_id"), str): 

631 self.session = event["thread_id"] 

632 elif kind == "turn.completed" and isinstance(event.get("usage"), dict): 

633 self._add_usage(event["usage"]) 

634 elif kind == "item.completed" and isinstance(event.get("item"), dict): 634 ↛ 636line 634 didn't jump to line 636 because the condition on line 634 was always true

635 self._add_item(event["item"]) 

636 elif kind in {"turn.failed", "error"}: 

637 error = event.get("error") 

638 message = error.get("message") if isinstance(error, dict) else event.get("message") 

639 self.failure = str(message or kind) 

640 

641 def _add_usage(self, usage: dict[str, Any]) -> None: 

642 self.seen = True 

643 self.totals["input"] += _int(usage.get("input_tokens")) or 0 

644 self.totals["output"] += _int(usage.get("output_tokens")) or 0 

645 self.totals["reasoning"] += _int(usage.get("reasoning_output_tokens")) or 0 

646 self.totals["cache"] += _int(usage.get("cached_input_tokens")) or 0 

647 

648 def _add_item(self, item: dict[str, Any]) -> None: 

649 if item.get("type") in {"agent_message", "assistant_message"} and isinstance( 649 ↛ exitline 649 didn't return from function '_add_item' because the condition on line 649 was always true

650 item.get("text"), str 

651 ): 

652 self.messages.append(item["text"]) 

653 

654 

655class GeminiCliProvider(NativeAgentProvider): 

656 """``gemini --output-format json``: ``response``, ``stats.models.<model>.tokens`` 

657 (``prompt``, ``candidates``, ``thoughts``, ``cached``) and ``error`` on failure.""" 

658 

659 kind = "gemini-cli" 

660 

661 def base_args(self) -> tuple[str, ...]: 

662 return (_OUTPUT_FORMAT, "json", _APPROVAL_MODE, "auto_edit") 

663 

664 def read_only_args(self) -> tuple[str, ...] | None: 

665 return (_OUTPUT_FORMAT, "json", _APPROVAL_MODE, "default") 

666 

667 def prompt_args(self, prompt: str) -> tuple[str, ...]: 

668 return ("--prompt", "Follow the instructions given on standard input.") 

669 

670 def read_answer(self, result: ProcessResult) -> ProviderAnswer: 

671 value = json.loads(result.stdout) 

672 if not isinstance(value, dict) or not ({"response", "error"} & set(value)): 672 ↛ 673line 672 didn't jump to line 673 because the condition on line 672 was never true

673 raise ValueError("gemini output is not a response object") 

674 error = value.get("error") 

675 response = str(value.get("response") or "") 

676 message = _gemini_error_message(error) 

677 return ProviderAnswer( 

678 status=ResultStatus.FAILED if error else ResultStatus.PASSED, 

679 summary=_summary(message or response) or "gemini-cli finished", 

680 usage=_gemini_usage(*_gemini_tokens(value)), 

681 usage_limitations=("Gemini CLI reports tokens per model and no cost.",), 

682 self_report=self._self_report_from(response), 

683 ) 

684 

685 

686def _gemini_error_message(error: Any) -> Any: 

687 """The message of Gemini's ``error`` field (an object with ``message`` or any value).""" 

688 if isinstance(error, dict): 688 ↛ 689line 688 didn't jump to line 689 because the condition on line 688 was never true

689 return error.get("message") 

690 if error: 690 ↛ 691line 690 didn't jump to line 691 because the condition on line 690 was never true

691 return str(error) 

692 return None 

693 

694 

695def _gemini_usage(totals: dict[str, int], seen: bool) -> dict[str, int | float] | None: 

696 """The usage of :func:`_gemini_tokens`' totals; nothing when no model reported tokens.""" 

697 if not seen: 697 ↛ 698line 697 didn't jump to line 698 because the condition on line 697 was never true

698 return None 

699 return _usage( 

700 inputTokens=totals["prompt"], 

701 outputTokens=totals["candidates"], 

702 reasoningTokens=totals["thoughts"] or None, 

703 # Gemini's cached tokens are prompt-cache reads, part of the prompt tokens. 

704 cacheTokens=totals["cached"] or None, 

705 cacheReadTokens=totals["cached"] or None, 

706 ) 

707 

708 

709def _gemini_tokens(value: dict[str, Any]) -> tuple[dict[str, int], bool]: 

710 """The ``prompt``, ``candidates``, ``thoughts`` and ``cached`` tokens summed over the 

711 models, and whether any model reported tokens.""" 

712 models = ( 

713 ((value.get("stats") or {}).get("models") or {}) 

714 if isinstance(value.get("stats"), dict) 

715 else {} 

716 ) 

717 totals = {"prompt": 0, "candidates": 0, "thoughts": 0, "cached": 0} 

718 seen = False 

719 for stats in models.values() if isinstance(models, dict) else (): 

720 tokens = stats.get("tokens") if isinstance(stats, dict) else None 

721 if not isinstance(tokens, dict): 721 ↛ 722line 721 didn't jump to line 722 because the condition on line 721 was never true

722 continue 

723 seen = True 

724 for name in totals: 

725 totals[name] += _int(tokens.get(name)) or 0 

726 return totals, seen 

727 

728 

729_AIDER_TOKENS = re.compile( 

730 r"Tokens: (?P<sent>[\d.,]+)(?P<sent_k>k?) sent,(?:.*?,)? (?P<received>[\d.,]+)(?P<received_k>k?) " 

731 r"received\.(?: Cost: \$(?P<message>[\d.,]+) message, \$(?P<session>[\d.,]+) session\.)?" 

732) 

733 

734 

735def _aider_count(number: str, thousands: str) -> int: 

736 value = float(number.replace(",", "")) 

737 return round(value * 1000) if thousands else round(value) 

738 

739 

740class AiderProvider(NativeAgentProvider): 

741 """``aider --message``: plain text; each model call prints ``Tokens: N sent, M received. 

742 Cost: $x message, $y session.``""" 

743 

744 kind = "aider" 

745 prompt_on_stdin = False 

746 

747 def base_args(self) -> tuple[str, ...]: 

748 return ( 

749 "--yes-always", 

750 "--no-auto-commits", 

751 "--no-dirty-commits", 

752 "--no-stream", 

753 "--no-pretty", 

754 "--no-gitignore", 

755 "--no-check-update", 

756 "--analytics-disable", 

757 "--input-history-file", 

758 os.devnull, 

759 "--chat-history-file", 

760 os.devnull, 

761 ) 

762 

763 def read_only_args(self) -> tuple[str, ...] | None: 

764 return ( 

765 *self.base_args(), 

766 "--chat-mode", 

767 "ask", 

768 "--dry-run", 

769 "--no-suggest-shell-commands", 

770 ) 

771 

772 def prompt_args(self, prompt: str) -> tuple[str, ...]: 

773 return ("--message", prompt) 

774 

775 def read_answer(self, result: ProcessResult) -> ProviderAnswer: 

776 text = result.stdout.decode("utf-8", "replace") 

777 sent = received = 0 

778 session_cost: float | None = None 

779 seen = False 

780 rounded = False 

781 for match in _AIDER_TOKENS.finditer(text): 

782 seen = True 

783 rounded = rounded or bool(match.group("sent_k") or match.group("received_k")) 

784 sent += _aider_count(match.group("sent"), match.group("sent_k")) 

785 received += _aider_count(match.group("received"), match.group("received_k")) 

786 if match.group("session"): 786 ↛ 781line 786 didn't jump to line 781 because the condition on line 786 was always true

787 session_cost = float(match.group("session").replace(",", "")) 

788 lines = [line.strip() for line in text.splitlines() if line.strip()] 

789 limitations = ["Aider prints the session cost; tokens are summed per message."] 

790 if rounded: 790 ↛ 792line 790 didn't jump to line 792 because the condition on line 790 was always true

791 limitations.append("Aider prints token counts above 1,000 rounded (for example 1.2k).") 

792 return ProviderAnswer( 

793 status=ResultStatus.PASSED, 

794 summary=_summary(lines[-1] if lines else "") or "aider finished", 

795 usage=_usage( 

796 inputTokens=sent if seen else None, 

797 outputTokens=received if seen else None, 

798 costUsd=session_cost, 

799 ), 

800 usage_limitations=tuple(limitations), 

801 self_report=self._self_report_from(text), 

802 ) 

803 

804 

805ADAPTERS: dict[str, type[NativeAgentProvider]] = { 

806 "claude-code": ClaudeCodeProvider, 

807 "codex": CodexProvider, 

808 "gemini-cli": GeminiCliProvider, 

809 "aider": AiderProvider, 

810} 

811 

812 

813def native_provider(kind: str, configuration: CommandAgentConfiguration) -> NativeAgentProvider: 

814 try: 

815 return ADAPTERS[kind](configuration) 

816 except KeyError as error: 

817 raise ValueError(f"unknown built-in agent adapter: {kind}") from error