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

1from __future__ import annotations 

2 

3import json 

4from dataclasses import dataclass 

5from datetime import UTC, datetime 

6from typing import Any 

7 

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 

27 

28 

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

47 

48 

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 {} 

85 

86 

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 } 

116 

117 

118class SimulatedAgentProvider: 

119 """Deterministic provider used for tests, evaluation fixtures and offline demonstrations.""" 

120 

121 provider_id = "simulated" 

122 

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

124 return ("structured_patch", "command", "deterministic", "offline") 

125 

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 ) 

246 

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)