Coverage for src/governed_harness/agents/simulated.py: 69%
112 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 typing import Any
8from governed_harness.agents.base import AgentCallResult, AgentContext, AgentExecutionResult
9from governed_harness.agents.requests import CallKind
10from governed_harness.domain.enums import ActorType, ErrorKind, PhaseId, ResultStatus
11from governed_harness.domain.ids import new_id
12from governed_harness.domain.models import (
13 Actor,
14 AgentInvocation,
15 CapabilityGrant,
16 HarnessErrorRecord,
17 Plan,
18 Provenance,
19 Task,
20 ToolInvocation,
21)
22from governed_harness.evidence.artifact_store import LocalArtifactStore
23from governed_harness.evidence.hashing import sha256_json
24from governed_harness.runtime.cancellation import CancellationToken
25from governed_harness.runtime.patches import PatchApplier
26from governed_harness.runtime.process_runner import CommandSpec, SafeProcessRunner
29@dataclass(frozen=True)
30class SimulatedAgentContext:
31 execution_id: str
32 workspace: Any
33 grants: list[CapabilityGrant]
34 artifact_store: LocalArtifactStore
35 process_runner: SafeProcessRunner
36 patch_applier: PatchApplier
37 provenance: Provenance
38 timeout_seconds: int
39 max_output_bytes: int
40 cancellation: CancellationToken
41 context_manifest_ref: str | None = None
42 memory_context: dict[str, Any] | None = None
43 feedback: dict[str, Any] | None = None
44 """Serialized ``ProviderFeedback`` for a correction attempt; ``None`` on a first attempt."""
45 request_extra: dict[str, Any] | None = None
46 """Keys the agent-results settings add to the provider request (``None``: the 1.0 form)."""
49def _call_result(kind: CallKind, request: dict[str, Any]) -> dict[str, Any]:
50 """The deterministic answer of a read-only request kind."""
51 if kind == "clarify": 51 ↛ 52line 51 didn't jump to line 52 because the condition on line 51 was never true
52 return {"questions": []}
53 if kind == "review" and "outputContract" in request:
54 # A reviewer of the review panel (#57) answers with its output contract.
55 return {"verdict": "PASS", "findings": [], "summary": "Simulated review: no finding."}
56 if kind == "review":
57 return {"findings": []}
58 if kind == "acceptance":
59 return {"tests": []}
60 if kind == "locate": 60 ↛ 61line 60 didn't jump to line 61 because the condition on line 60 was never true
61 return {"locations": [], "questions": []}
62 if kind == "architecture": 62 ↛ 82line 62 didn't jump to line 82 because the condition on line 62 was always true
63 # No layering inferred and no option proposed: nothing waits for a person (#56).
64 if request.get("mode") == "advise": 64 ↛ 65line 64 didn't jump to line 65 because the condition on line 64 was never true
65 return {"options": []}
66 if request.get("mode") == "organize": 66 ↛ 67line 66 didn't jump to line 67 because the condition on line 66 was never true
67 return {"summary": "Simulated organization: no plan.", "structure": [], "practices": []}
68 return {
69 "style": "custom",
70 "summary": "Simulated survey: no layering was inferred.",
71 "layers": [],
72 "allow": {},
73 # The documentation fields of architecture.documentation: project (#97); ignored
74 # when the key is off.
75 "organization": "Simulated survey: no organization was inferred.",
76 "components": [
77 {"name": "project", "path": ".", "responsibility": "Simulated component."}
78 ],
79 "conventions": [],
80 "guidance": ["Simulated survey: follow the existing structure."],
81 }
82 if kind == "plan":
83 return _plan_result(request)
84 return {}
87def _plan_result(request: dict[str, Any]) -> dict[str, Any]:
88 """The requirements in order, in sub-tasks of at most ``threshold`` requirements; the
89 acceptance criteria go to the last one."""
90 task = request.get("task") or {}
91 requirement_ids = [
92 str(item.get("requirement_id"))
93 for item in task.get("requirements") or []
94 if isinstance(item, dict)
95 ]
96 size = max(1, int(request.get("threshold") or len(requirement_ids) or 1))
97 groups = [
98 requirement_ids[index : index + size] for index in range(0, len(requirement_ids), size)
99 ] or [[]]
100 criteria = [
101 str(item.get("criterion_id"))
102 for item in task.get("acceptance_criteria") or []
103 if isinstance(item, dict)
104 ]
105 return {
106 "subtasks": [
107 {
108 "title": f"Part {number} of {len(groups)}",
109 "requirements": group,
110 "criteria": criteria if number == len(groups) else [],
111 "constraints": [],
112 }
113 for number, group in enumerate(groups, start=1)
114 ]
115 }
118class SimulatedAgentProvider:
119 """Deterministic provider used for tests, evaluation fixtures and offline demonstrations."""
121 provider_id = "simulated"
123 def capabilities(self) -> tuple[str, ...]:
124 return ("structured_patch", "command", "deterministic", "offline")
126 def implement(self, task: Task, plan: Plan, context: AgentContext) -> AgentExecutionResult:
127 actor = Actor(actor_type=ActorType.AGENT, actor_id="agent.simulated", version="1")
128 started = datetime.now(UTC)
129 prompt = {
130 "task": task.model_dump(mode="json"),
131 "plan": plan.model_dump(mode="json"),
132 "provider": self.provider_id,
133 }
134 prompt_digest = sha256_json(prompt)
135 tool_invocations: list[ToolInvocation] = []
136 status = ResultStatus.PASSED
137 summary = "No implementation action was requested"
138 error_record: HarnessErrorRecord | None = None
139 output: dict[str, Any] = {"mode": task.implementation.mode, "changedPaths": []}
140 try:
141 if context.cancellation.cancelled: 141 ↛ 142line 141 didn't jump to line 142 because the condition on line 141 was never true
142 status = ResultStatus.CANCELLED
143 summary = "Implementation cancelled before start"
144 elif task.implementation.mode == "patch": 144 ↛ 154line 144 didn't jump to line 154 because the condition on line 144 was always true
145 for patch in task.implementation.patches:
146 if context.cancellation.cancelled: 146 ↛ 147line 146 didn't jump to line 147 because the condition on line 146 was never true
147 status = ResultStatus.CANCELLED
148 summary = "Implementation cancelled"
149 break
150 path = context.patch_applier.apply(patch, actor=actor, grants=context.grants)
151 output["changedPaths"].append(str(path.relative_to(context.workspace)))
152 else:
153 summary = f"Applied {len(task.implementation.patches)} structured patch(es)"
154 elif task.implementation.mode == "command":
155 tool_started = datetime.now(UTC)
156 result = context.process_runner.run(
157 CommandSpec(
158 argv=task.implementation.argv,
159 cwd=context.workspace / task.implementation.cwd,
160 timeout_seconds=context.timeout_seconds,
161 max_output_bytes=context.max_output_bytes,
162 ),
163 actor=actor,
164 grants=context.grants,
165 cancellation=context.cancellation,
166 )
167 stdout_ref = context.artifact_store.put(
168 result.stdout,
169 media_type="text/plain",
170 metadata={"stream": "stdout", "phase": "IMPLEMENTATION"},
171 )
172 stderr_ref = context.artifact_store.put(
173 result.stderr,
174 media_type="text/plain",
175 metadata={"stream": "stderr", "phase": "IMPLEMENTATION"},
176 )
177 tool_invocations.append(
178 ToolInvocation(
179 invocation_id=new_id("tool"),
180 execution_id=context.execution_id,
181 phase_id=PhaseId.IMPLEMENTATION,
182 actor=actor,
183 tool_id="process.execute",
184 argv=task.implementation.argv,
185 cwd=task.implementation.cwd,
186 started_at=tool_started,
187 finished_at=datetime.now(UTC),
188 status=result.status,
189 exit_code=result.exit_code,
190 timed_out=result.timed_out,
191 cancelled=result.cancelled,
192 stdout_ref=stdout_ref.uri,
193 stderr_ref=stderr_ref.uri,
194 provenance=context.provenance.model_copy(update={"actor": actor}),
195 )
196 )
197 status = result.status
198 summary = f"Implementation command exited with {result.exit_code}"
199 output.update(
200 {
201 "exitCode": result.exit_code,
202 "stdoutRef": stdout_ref.uri,
203 "stderrRef": stderr_ref.uri,
204 }
205 )
206 except Exception as error: # converted into a structured provider error
207 status = ResultStatus.ERROR
208 summary = str(error)
209 error_record = HarnessErrorRecord(
210 error_id=new_id("err"),
211 kind=ErrorKind.PROVIDER_ERROR,
212 message=str(error),
213 actor=actor,
214 details={"provider": self.provider_id},
215 )
216 output_ref = context.artifact_store.put_json(
217 output,
218 metadata={"kind": "agent-output", "provider": self.provider_id},
219 )
220 finished = datetime.now(UTC)
221 invocation = AgentInvocation(
222 invocation_id=new_id("agentinv"),
223 execution_id=context.execution_id,
224 phase_id=PhaseId.IMPLEMENTATION,
225 actor=actor,
226 provider=self.provider_id,
227 model="deterministic-v1",
228 session_id=None,
229 started_at=started,
230 finished_at=finished,
231 status=status,
232 prompt_digest=prompt_digest,
233 context_manifest_ref=context.context_manifest_ref,
234 tool_invocation_ids=tuple(item.invocation_id for item in tool_invocations),
235 output_ref=output_ref.uri,
236 error=error_record,
237 )
238 return AgentExecutionResult(
239 status,
240 summary,
241 invocation,
242 tuple(tool_invocations),
243 output_ref.uri,
244 request_bytes=len(json.dumps(prompt, sort_keys=True).encode("utf-8")),
245 )
247 def call(
248 self,
249 kind: CallKind,
250 request: dict[str, Any],
251 context: AgentContext,
252 *,
253 phase_id: PhaseId,
254 ) -> AgentCallResult:
255 """Deterministic answers to the read-only request kinds: no clarification question, no
256 review finding, and a plan that splits the requirements in order into sub-tasks of at
257 most ``threshold`` requirements (the acceptance criteria go to the last one)."""
258 actor = Actor(actor_type=ActorType.AGENT, actor_id="agent.simulated", version="1")
259 started = datetime.now(UTC)
260 result = _call_result(kind, request)
261 output_ref = context.artifact_store.put_json(
262 {"kind": kind, "result": result},
263 metadata={"kind": "agent-output", "provider": self.provider_id},
264 )
265 invocation = AgentInvocation(
266 invocation_id=new_id("agentinv"),
267 execution_id=context.execution_id,
268 phase_id=phase_id,
269 actor=actor,
270 provider=self.provider_id,
271 model="deterministic-v1",
272 started_at=started,
273 finished_at=datetime.now(UTC),
274 status=ResultStatus.PASSED,
275 prompt_digest=sha256_json(request),
276 context_manifest_ref=context.context_manifest_ref,
277 output_ref=output_ref.uri,
278 call_kind=kind,
279 )
280 execution = AgentExecutionResult(
281 ResultStatus.PASSED,
282 f"Simulated {kind} answer",
283 invocation,
284 (),
285 output_ref.uri,
286 )
287 return AgentCallResult(execution, result)