Coverage for src/governed_harness/agents/command.py: 95%

159 statements  

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

1from __future__ import annotations 

2 

3import json 

4from dataclasses import dataclass 

5from datetime import UTC, datetime 

6from pathlib import Path 

7from typing import Any 

8 

9from governed_harness.agents.base import AgentCallResult, AgentContext, AgentExecutionResult 

10from governed_harness.agents.environment import ProviderEnvironment 

11from governed_harness.agents.requests import CallKind 

12from governed_harness.agents.self_report import REQUEST_BLOCK 

13from governed_harness.domain.enums import ( 

14 ActorType, 

15 ErrorKind, 

16 MetricQuality, 

17 PhaseId, 

18 ResultStatus, 

19) 

20from governed_harness.domain.ids import new_id 

21from governed_harness.domain.models import ( 

22 Actor, 

23 AgentInvocation, 

24 HarnessErrorRecord, 

25 Plan, 

26 ResourceUsage, 

27 Task, 

28 ToolInvocation, 

29) 

30from governed_harness.evidence.hashing import sha256_json 

31from governed_harness.runtime.process_runner import CommandSpec, ProcessResult 

32 

33 

34@dataclass(frozen=True) 

35class CommandAgentConfiguration: 

36 provider_id: str 

37 argv_prefix: tuple[str, ...] 

38 model: str | None = None 

39 sandbox_prefix: tuple[str, ...] = () 

40 """Write-confinement wrapper (``runtime.agentSandbox: enforce``); empty runs unconfined.""" 

41 environment: ProviderEnvironment | None = None 

42 """``passEnv`` and ``env`` of the provider (since 2.0); ``None`` passes only the runner's 

43 minimal environment, as in 1.0.0.""" 

44 self_report: bool = False 

45 """``provenance.selfReport``: ask for and read the agent's self-report (since 2.0).""" 

46 extra_args: tuple[str, ...] = () 

47 """``args`` of a built-in adapter.""" 

48 

49 

50@dataclass(frozen=True) 

51class ProviderAnswer: 

52 """What a provider's process said, read by the protocol of its kind.""" 

53 

54 status: ResultStatus 

55 summary: str 

56 usage: dict[str, Any] | None = None 

57 usage_limitations: tuple[str, ...] = () 

58 session_id: str | None = None 

59 self_report: Any = None 

60 result: Any = None 

61 """The structured ``result`` of a ``clarify``, ``acceptance``, ``plan`` or ``review`` 

62 answer (since 2.0).""" 

63 

64 

65class CommandAgentProvider: 

66 """Provider-neutral adapter for a locally installed agent CLI. 

67 

68 The CLI must read a JSON request from stdin and return JSON on stdout. It remains 

69 constrained by the same process capability grant as any other tool and, when the 

70 configuration carries a sandbox prefix, runs inside that write confinement. 

71 """ 

72 

73 stdout_media_type = "application/json" 

74 

75 def __init__(self, configuration: CommandAgentConfiguration) -> None: 

76 self.configuration = configuration 

77 self.provider_id = configuration.provider_id 

78 

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

80 return ("external_cli", "structured_json") 

81 

82 # ----- hooks of the built-in adapters ------------------------------------------------ 

83 def build_request(self, task: Task, plan: Plan, context: AgentContext) -> dict[str, object]: 

84 request: dict[str, object] = { 

85 "schemaVersion": "1.0", 

86 "task": task.model_dump(mode="json"), 

87 "plan": plan.model_dump(mode="json"), 

88 } 

89 # The governed memory selected in PLANNING reaches the agent only when there is any, so 

90 # a request without memory is identical to the one sent before memory was wired in. 

91 if context.memory_context and context.memory_context.get("records"): 

92 request["context"] = context.memory_context 

93 # Feedback exists only on a correction attempt with runtime.providerFeedback enabled, so 

94 # every other request keeps its previous form and prompt digest. 

95 if context.feedback: 

96 request["feedback"] = context.feedback 

97 if self.configuration.self_report: 

98 request["selfReport"] = dict(REQUEST_BLOCK) 

99 # The agent-results settings (gate contract, permissions, context manifest, lessons, 

100 # budget, routing) add their keys, and the kind and instructions with them; without 

101 # any of them the request keeps the 1.0 form. 

102 extra = context.request_extra 

103 if extra: 

104 request.update(extra) 

105 return request 

106 

107 def process_input( 

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

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

110 """The argv, the standard input and the argv recorded as evidence.""" 

111 request_bytes = json.dumps(request, sort_keys=True).encode("utf-8") 

112 return self.configuration.argv_prefix, request_bytes, self.configuration.argv_prefix 

113 

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

115 """Read the JSON protocol answer of a process that exited with 0; raise on a protocol 

116 error.""" 

117 response = json.loads(result.stdout) 

118 if not isinstance(response, dict) or response.get("status") not in { 118 ↛ 123line 118 didn't jump to line 123 because the condition on line 118 was never true

119 "PASSED", 

120 "FAILED", 

121 "BLOCKED", 

122 }: 

123 raise ValueError("agent response does not satisfy the minimal protocol") 

124 return ProviderAnswer( 

125 status=ResultStatus(response["status"]), 

126 summary=str(response.get("summary", f"Agent CLI exited with {result.exit_code}")), 

127 usage=response.get("usage"), 

128 self_report=response.get("selfReport") if self.configuration.self_report else None, 

129 result=response.get("result"), 

130 ) 

131 

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

133 return f"Agent CLI exited with {result.exit_code}" 

134 

135 def extract_result(self, result: ProcessResult) -> Any: # NOSONAR(S1172) hook to override 

136 """The ``result`` object of a read-only call when the answer did not carry it in the 

137 protocol field (built-in adapters read it from the agent's text).""" 

138 return None 

139 

140 # ----- the invocations ----------------------------------------------------------------- 

141 def implement(self, task: Task, plan: Plan, context: AgentContext) -> AgentExecutionResult: 

142 request = self.build_request(task, plan, context) 

143 execution, _ = self._invoke( 

144 request, 

145 context, 

146 phase_id=PhaseId.IMPLEMENTATION, 

147 call_kind="implement" if context.request_extra else None, 

148 ) 

149 return execution 

150 

151 def call( 

152 self, 

153 kind: CallKind, 

154 request: dict[str, Any], 

155 context: AgentContext, 

156 *, 

157 phase_id: PhaseId, 

158 ) -> AgentCallResult: 

159 """Send a read-only ``clarify``, ``acceptance``, ``plan`` or ``review`` request. A 

160 passing answer must carry a ``result`` object; otherwise it is a protocol error.""" 

161 execution, result = self._invoke( 

162 dict(request), context, phase_id=phase_id, call_kind=kind, require_result=True 

163 ) 

164 return AgentCallResult(execution, result) 

165 

166 def _invoke( 

167 self, 

168 request: dict[str, object], 

169 context: AgentContext, 

170 *, 

171 phase_id: PhaseId, 

172 call_kind: CallKind | None, 

173 require_result: bool = False, 

174 ) -> tuple[AgentExecutionResult, dict[str, Any] | None]: 

175 actor = self._agent_actor(context) 

176 started = datetime.now(UTC) 

177 prompt_digest = sha256_json(request) 

178 argv, stdin, recorded_argv = self.process_input(request, context) 

179 environment = self.configuration.environment 

180 result = context.process_runner.run( 

181 CommandSpec( 

182 argv=argv, 

183 cwd=Path(context.workspace), 

184 timeout_seconds=context.timeout_seconds, 

185 allowed_environment=environment.allowed if environment else (), 

186 max_output_bytes=context.max_output_bytes, 

187 stdin=stdin, 

188 sandbox_prefix=self.configuration.sandbox_prefix, 

189 ), 

190 actor=actor, 

191 grants=context.grants, 

192 extra_env=(environment.values or None) if environment else None, 

193 cancellation=context.cancellation, 

194 ) 

195 stdout_ref = context.artifact_store.put(result.stdout, media_type=self.stdout_media_type) 

196 stderr_ref = context.artifact_store.put(result.stderr, media_type="text/plain") 

197 tool = ToolInvocation( 

198 invocation_id=new_id("tool"), 

199 execution_id=context.execution_id, 

200 phase_id=phase_id, 

201 actor=actor, 

202 tool_id="agent.cli", 

203 argv=recorded_argv, 

204 cwd=".", 

205 started_at=started, 

206 finished_at=datetime.now(UTC), 

207 status=result.status, 

208 exit_code=result.exit_code, 

209 timed_out=result.timed_out, 

210 cancelled=result.cancelled, 

211 stdout_ref=stdout_ref.uri, 

212 stderr_ref=stderr_ref.uri, 

213 provenance=context.provenance.model_copy(update={"actor": actor}), 

214 ) 

215 error = None 

216 status = result.status 

217 summary = self.failure_summary(result) 

218 invocation_id = new_id("agentinv") 

219 usage: ResourceUsage | None = None 

220 usage_ref: str | None = None 

221 session_id: str | None = None 

222 self_report: Any = None 

223 structured: dict[str, Any] | None = None 

224 if result.status is ResultStatus.PASSED: 

225 try: 

226 answer = self.read_answer(result) 

227 usage, usage_ref = self._answer_usage(answer, context, invocation_id, started) 

228 status = answer.status 

229 summary = answer.summary 

230 session_id = answer.session_id 

231 self_report = answer.self_report 

232 if require_result and status is ResultStatus.PASSED: 

233 structured = self._structured_result(answer, result, call_kind) 

234 except Exception as exc: 

235 usage, usage_ref, structured = None, None, None 

236 status = ResultStatus.ERROR 

237 error = HarnessErrorRecord( 

238 error_id=new_id("err"), 

239 kind=ErrorKind.PROTOCOL_ERROR, 

240 message=str(exc), 

241 actor=actor, 

242 ) 

243 summary = str(exc) 

244 summary, error = _redact_configured(context, summary, error) 

245 routing = request_routing(request) 

246 invocation = AgentInvocation( 

247 invocation_id=invocation_id, 

248 execution_id=context.execution_id, 

249 phase_id=phase_id, 

250 actor=actor, 

251 provider=self.provider_id, 

252 model=routing.get("model") or self.configuration.model, 

253 session_id=session_id, 

254 started_at=started, 

255 finished_at=datetime.now(UTC), 

256 status=status, 

257 prompt_digest=prompt_digest, 

258 context_manifest_ref=context.context_manifest_ref, 

259 tool_invocation_ids=(tool.invocation_id,), 

260 usage_ref=usage_ref, 

261 output_ref=stdout_ref.uri, 

262 error=error, 

263 call_kind=call_kind, 

264 effort=routing.get("effort"), 

265 ) 

266 return ( 

267 AgentExecutionResult( 

268 status, 

269 summary, 

270 invocation, 

271 (tool,), 

272 stdout_ref.uri, 

273 usage, 

274 self_report, 

275 request_bytes=len(json.dumps(request, sort_keys=True).encode("utf-8")), 

276 ), 

277 structured, 

278 ) 

279 

280 def _agent_actor(self, context: AgentContext) -> Actor: 

281 """The context's actor when it is this provider's agent; otherwise a fresh one.""" 

282 actor = context.provenance.actor 

283 if actor.actor_type is not ActorType.AGENT or actor.actor_id != f"agent.{self.provider_id}": 283 ↛ 284line 283 didn't jump to line 284 because the condition on line 283 was never true

284 actor = Actor( 

285 actor_type=ActorType.AGENT, 

286 actor_id=f"agent.{self.provider_id}", 

287 version="1", 

288 ) 

289 return actor 

290 

291 def _answer_usage( 

292 self, 

293 answer: ProviderAnswer, 

294 context: AgentContext, 

295 invocation_id: str, 

296 started: datetime, 

297 ) -> tuple[ResourceUsage | None, str | None]: 

298 """The usage an answer reports and its stored reference; ``(None, None)`` without it.""" 

299 if answer.usage is None: 

300 return None, None 

301 usage = _reported_usage( 

302 answer.usage, 

303 execution_id=context.execution_id, 

304 invocation_id=invocation_id, 

305 wall_time_ms=int((datetime.now(UTC) - started).total_seconds() * 1000), 

306 limitations=answer.usage_limitations, 

307 ) 

308 usage_ref = context.artifact_store.put_json( 

309 usage.model_dump(mode="json", by_alias=True), 

310 metadata={"kind": "resource-usage", "provider": self.provider_id}, 

311 ).uri 

312 return usage, usage_ref 

313 

314 def _structured_result( 

315 self, answer: ProviderAnswer, result: ProcessResult, call_kind: CallKind | None 

316 ) -> dict[str, Any]: 

317 """The ``result`` object of a passing answer; a protocol error without one.""" 

318 value = answer.result if answer.result is not None else self.extract_result(result) 

319 if not isinstance(value, dict): 

320 raise ValueError(f"a {call_kind} response that passes needs a 'result' object") 

321 return value 

322 

323 

324def _redact_configured( 

325 context: AgentContext, summary: str, error: HarnessErrorRecord | None 

326) -> tuple[str, HarnessErrorRecord | None]: 

327 """The summary and error message with the configured secrets redacted.""" 

328 redactor = context.artifact_store.redactor 

329 if redactor.configured: 329 ↛ 335line 329 didn't jump to line 335 because the condition on line 329 was always true

330 summary = redactor.redact_configured_text(summary) 

331 if error is not None: 

332 error = error.model_copy( 

333 update={"message": redactor.redact_configured_text(error.message)} 

334 ) 

335 return summary, error 

336 

337 

338def request_routing(request: dict[str, object]) -> dict[str, str]: 

339 """The model and effort a request carries under ``agentRouting`` or a call's own setting 

340 (``routing``); empty without them.""" 

341 routing = request.get("routing") 

342 if not isinstance(routing, dict): 

343 return {} 

344 return { 

345 name: str(routing[name]) for name in ("model", "effort") if routing.get(name) is not None 

346 } 

347 

348 

349_USAGE_FIELDS = { 

350 "inputTokens": "input_tokens", 

351 "outputTokens": "output_tokens", 

352 "reasoningTokens": "reasoning_tokens", 

353 "costUsd": "cost_usd", 

354 "cacheTokens": "cache_tokens", 

355 "cacheReadTokens": "cache_read_tokens", 

356} 

357 

358 

359def _reported_usage( 

360 raw: Any, 

361 *, 

362 execution_id: str, 

363 invocation_id: str, 

364 wall_time_ms: int, 

365 limitations: tuple[str, ...] = (), 

366) -> ResourceUsage: 

367 """Usage the provider reports about its own model calls. It is optional, but a malformed 

368 report is a protocol error: the harness records what was reported, never an estimate.""" 

369 if not isinstance(raw, dict) or not raw: 369 ↛ 370line 369 didn't jump to line 370 because the condition on line 369 was never true

370 raise ValueError("agent usage must be a non-empty object") 

371 unknown = sorted(set(raw) - set(_USAGE_FIELDS)) 

372 if unknown: 372 ↛ 373line 372 didn't jump to line 373 because the condition on line 372 was never true

373 raise ValueError(f"unknown agent usage field(s): {', '.join(unknown)}") 

374 values: dict[str, int | float] = {} 

375 for name, field in _USAGE_FIELDS.items(): 

376 if name not in raw: 

377 continue 

378 value = raw[name] 

379 numeric = isinstance(value, int | float) and not isinstance(value, bool) 

380 if not numeric or value < 0 or (name != "costUsd" and not isinstance(value, int)): 

381 raise ValueError(f"agent usage field {name} must be a non-negative number") 

382 values[field] = value 

383 return ResourceUsage( 

384 usage_id=new_id("usage"), 

385 execution_id=execution_id, 

386 invocation_id=invocation_id, 

387 wall_time_ms=wall_time_ms, 

388 quality=MetricQuality.REPORTED, 

389 limitations=("Reported by the agent provider; the harness does not measure it.",) 

390 + limitations, 

391 **values, # type: ignore[arg-type] 

392 )