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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import json
4from dataclasses import dataclass
5from datetime import UTC, datetime
6from pathlib import Path
7from typing import Any
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
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."""
50@dataclass(frozen=True)
51class ProviderAnswer:
52 """What a provider's process said, read by the protocol of its kind."""
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)."""
65class CommandAgentProvider:
66 """Provider-neutral adapter for a locally installed agent CLI.
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 """
73 stdout_media_type = "application/json"
75 def __init__(self, configuration: CommandAgentConfiguration) -> None:
76 self.configuration = configuration
77 self.provider_id = configuration.provider_id
79 def capabilities(self) -> tuple[str, ...]:
80 return ("external_cli", "structured_json")
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
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
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 )
132 def failure_summary(self, result: ProcessResult) -> str:
133 return f"Agent CLI exited with {result.exit_code}"
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
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
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)
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 )
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
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
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
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
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 }
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}
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 )