Coverage for src/governed_harness/agents/contract.py: 100%

175 statements  

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

1"""The versioned JSON contract between a parent and an agent call (wave 11, #97). 

2 

3A *request contract* travels in the ``agentContract`` key of every request of a run that sets 

4``agentContract`` in ``project.yaml``. It states, in one place: the assigned task, the allowed 

5context, the authorized files and resources, the execution constraints, the token budget, the 

6time limit, the iteration number, the expected response and the minimal result that goes back to 

7the parent. A *response contract* is what the parent receives: the final status, a bounded 

8summary, the minimal ``result`` and, when a limit or the contract itself stopped the call, which 

9one. Both are validated; a violation fails closed with a structured result. 

10 

11The module is pure: it reads no file and calls no agent.""" 

12 

13from __future__ import annotations 

14 

15import json 

16from typing import Any, Final, Literal 

17 

18from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator 

19from pydantic.alias_generators import to_camel 

20 

21from governed_harness.agents.requests import CallKind 

22from governed_harness.configuration.agent_contract import ( 

23 MAX_ITERATIONS_CEILING, 

24 AgentContractConfig, 

25) 

26from governed_harness.evidence.hashing import sha256_json 

27 

28CONTRACT_VERSION: Final = "1.0" 

29REQUEST_KEY: Final = "agentContract" 

30"""The key of a request that carries the contract.""" 

31 

32SizeName = Literal["S", "M", "L"] 

33AgentStatus = Literal["PASSED", "FAILED", "BLOCKED"] 

34FinalStatus = Literal[ 

35 "PASSED", 

36 "FAILED", 

37 "BLOCKED", 

38 "ERROR", 

39 "CANCELLED", 

40 "LIMIT_REACHED", 

41 "CONTRACT_VIOLATION", 

42 "ITERATIONS_EXHAUSTED", 

43] 

44LimitName = Literal["tokens", "time"] 

45 

46TASK_FIELDS: Final[dict[str, tuple[str, ...]]] = { 

47 "clarify": ( 

48 "task_id", 

49 "title", 

50 "intent", 

51 "constraints", 

52 "requirements", 

53 "acceptance_criteria", 

54 "contract", 

55 ), 

56 "plan": ("task_id", "title", "intent", "constraints", "requirements", "acceptance_criteria"), 

57 "acceptance": ("task_id", "title", "intent", "requirements", "acceptance_criteria"), 

58 "locate": ("task_id", "title", "intent", "requirements", "acceptance_criteria"), 

59 "architecture": ("task_id", "title", "intent", "constraints", "requirements"), 

60 "review": ("task_id", "title", "constraints", "requirements", "acceptance_criteria"), 

61} 

62"""The fields of the task each read-only call kind needs; the others are not sent. An 

63``implement`` request keeps the whole task, which the agent implements.""" 

64 

65RESULT_KEYS: Final[dict[str, tuple[str, ...]]] = { 

66 "implement": (), 

67 "clarify": ("questions",), 

68 "review": ("findings",), 

69 "plan": ("subtasks",), 

70 "acceptance": ("tests",), 

71 "locate": ("locations", "questions"), 

72 "architecture": ( 

73 "style", 

74 "summary", 

75 "layers", 

76 "allow", 

77 "options", 

78 # The survey under ``architecture.documentation: project`` (reverse engineering). 

79 "organization", 

80 "components", 

81 "conventions", 

82 "guidance", 

83 # The expert's organization plan under ``architecture.catalogue: experts``. 

84 "structure", 

85 "practices", 

86 ), 

87} 

88"""The keys the ``result`` object of each call kind may carry.""" 

89 

90PANEL_RESULT_KEYS: Final[tuple[str, ...]] = ("verdict", "summary", "findings", "model") 

91"""The keys a reviewer of the review panel answers with (``review.contract``): a ``review`` 

92call whose answer is the panel's verdict object, not the single reviewer's ``findings``.""" 

93 

94FILE_CONTENT_KEYS: Final[frozenset[str]] = frozenset( 

95 {"content", "contents", "filecontent", "filecontents", "source", "sourcecode", "body"} 

96) 

97"""Keys under which a ``result`` would carry the content of a file; only ``acceptance`` returns 

98files (the tests it writes), every other kind returns a conclusion.""" 

99 

100OBJECTIVE_CHARS: Final = 500 

101RETURN_FIELDS: Final[tuple[str, ...]] = ("finalStatus", "summary", "result", "limitReached") 

102RETURN_FORBIDDEN: Final[tuple[str, ...]] = ( 

103 "the request or its context", 

104 "the content of files when a conclusion is required", 

105 "reasoning or internal notes", 

106 "information the parent does not need for its next decision", 

107) 

108 

109 

110class _Contract(BaseModel): 

111 model_config = ConfigDict( 

112 extra="forbid", populate_by_name=True, frozen=True, alias_generator=to_camel 

113 ) 

114 

115 

116class TaskAssignment(_Contract): 

117 """The task the call assigns: its id, the kind of call, a short objective and the task 

118 fields the request carries (the others were left out).""" 

119 

120 task_id: str = Field(min_length=1) 

121 call_kind: CallKind 

122 objective: str = Field(max_length=OBJECTIVE_CHARS) 

123 fields: tuple[str, ...] 

124 

125 

126class AuthorizedResources(_Contract): 

127 """What the call may read, write and run. Context files remain guidance: reads are not 

128 blocked, writes are confined as the agent sandbox does.""" 

129 

130 read_paths: tuple[str, ...] 

131 write_paths: tuple[str, ...] 

132 guidance_paths: tuple[str, ...] = () 

133 """The context files the request lists: guidance, never a restriction on reads.""" 

134 deny_paths: tuple[str, ...] = () 

135 commands: tuple[str, ...] = () 

136 scripts: tuple[str, ...] = () 

137 """Ids of the scripts and commands registered as black boxes (``harness agent-contract 

138 scripts``); the call uses their contract, not their source.""" 

139 

140 

141class ExecutionConstraints(_Contract): 

142 read_only: bool 

143 workspace: str 

144 scripts_are_black_boxes: bool = True 

145 context_files_are_guidance: bool = True 

146 

147 

148class Iteration(_Contract): 

149 """The call's place in the cap of iterations of the agent in this run.""" 

150 

151 number: int = Field(ge=1) 

152 max: int = Field(ge=1, le=MAX_ITERATIONS_CEILING) 

153 

154 @model_validator(mode="after") 

155 def _within_cap(self) -> Iteration: 

156 if self.number > self.max: 

157 raise ValueError(f"iteration {self.number} is above the cap of {self.max}") 

158 return self 

159 

160 

161class ExpectedResponseLimits(_Contract): 

162 summary_chars: int = Field(ge=1) 

163 result_bytes: int = Field(ge=1) 

164 field_chars: int = Field(ge=1) 

165 

166 

167class ExpectedResponse(_Contract): 

168 """The answer the call must give: the 1.0 protocol object, the keys of its ``result`` and 

169 the caps per field.""" 

170 

171 protocol: Literal["1.0"] = "1.0" 

172 result_keys: tuple[str, ...] 

173 limits: ExpectedResponseLimits 

174 file_contents_allowed: bool 

175 

176 

177class ReturnToParent(_Contract): 

178 """The minimal result that reaches the parent and what never does.""" 

179 

180 fields: tuple[str, ...] = RETURN_FIELDS 

181 never: tuple[str, ...] = RETURN_FORBIDDEN 

182 

183 

184class AgentCallRequestContract(_Contract): 

185 """The request contract (schema ``agent-call-request.schema.json``).""" 

186 

187 contract_version: Literal["1.0"] = CONTRACT_VERSION 

188 call_kind: CallKind 

189 task: TaskAssignment 

190 allowed_context: tuple[str, ...] = Field(min_length=1) 

191 """The top-level keys of the request, all of them: what the call receives.""" 

192 resources: AuthorizedResources 

193 constraints: ExecutionConstraints 

194 token_budget: int = Field(ge=1) 

195 time_limit_seconds: int = Field(ge=1) 

196 size_class: SizeName 

197 iteration: Iteration 

198 expected_response: ExpectedResponse 

199 return_to_parent: ReturnToParent 

200 

201 @model_validator(mode="after") 

202 def _consistent(self) -> AgentCallRequestContract: 

203 if self.task.call_kind != self.call_kind: 

204 raise ValueError("the task assignment and the contract name different call kinds") 

205 if self.constraints.read_only and self.resources.write_paths: 

206 raise ValueError("a read-only call cannot be authorized to write") 

207 return self 

208 

209 

210class Usage(_Contract): 

211 input_tokens: int | None = Field(default=None, ge=0) 

212 output_tokens: int | None = Field(default=None, ge=0) 

213 reasoning_tokens: int | None = Field(default=None, ge=0) 

214 cache_read_tokens: int | None = Field(default=None, ge=0) 

215 """The part of ``input_tokens`` read from the provider's prompt cache, when reported; the 

216 token budget does not count it.""" 

217 

218 

219class AgentCallResponse(_Contract): 

220 """What the parent receives from a call (schema ``agent-call-response.schema.json``).""" 

221 

222 contract_version: Literal["1.0"] = CONTRACT_VERSION 

223 call_kind: CallKind 

224 invocation_id: str | None = None 

225 iteration: int = Field(ge=1) 

226 status: AgentStatus | None = None 

227 """The status the agent reported (``None``: it reported none, for example on a timeout).""" 

228 final_status: FinalStatus 

229 summary: str = Field(max_length=5000) 

230 result: dict[str, Any] | None = None 

231 usage: Usage | None = None 

232 limit_reached: LimitName | None = None 

233 violations: tuple[str, ...] = () 

234 

235 @model_validator(mode="after") 

236 def _consistent(self) -> AgentCallResponse: 

237 if self.final_status == "LIMIT_REACHED" and self.limit_reached is None: 

238 raise ValueError("finalStatus LIMIT_REACHED needs limitReached") 

239 if self.final_status != "PASSED" and self.result is not None: 

240 raise ValueError("only a passed call returns a result") 

241 if self.final_status == "CONTRACT_VIOLATION" and not self.violations: 

242 raise ValueError("finalStatus CONTRACT_VIOLATION needs violations") 

243 return self 

244 

245 

246# ----- the minimal request ------------------------------------------------------------------- 

247def minimal_task(kind: str, task: dict[str, Any]) -> dict[str, Any]: 

248 """The task as a call of ``kind`` receives it: only the fields the kind needs. ``implement`` 

249 (and a kind without a list) keeps the whole task.""" 

250 fields = TASK_FIELDS.get(kind) 

251 if fields is None: 

252 return task 

253 return {name: task[name] for name in fields if name in task} 

254 

255 

256def request_digest(request: dict[str, Any]) -> str: 

257 """The digest of the request the provider received (the same one as its prompt digest).""" 

258 return sha256_json(request) 

259 

260 

261def request_bytes(request: dict[str, Any]) -> int: 

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

263 

264 

265def objective_of(task: dict[str, Any]) -> str: 

266 """A short objective for the assignment: the title, then the start of the intent.""" 

267 text = f"{task.get('title', '')}. {task.get('intent', '')}".strip() 

268 return text[:OBJECTIVE_CHARS] 

269 

270 

271def expected_response(kind: str, config: AgentContractConfig) -> ExpectedResponse: 

272 return ExpectedResponse( 

273 result_keys=RESULT_KEYS.get(kind, ()), 

274 limits=ExpectedResponseLimits( 

275 summary_chars=config.summary_chars, 

276 result_bytes=config.result_bytes(kind), 

277 field_chars=config.field_chars, 

278 ), 

279 file_contents_allowed=kind == "acceptance", 

280 ) 

281 

282 

283def validate_request_contract(value: object) -> AgentCallRequestContract: 

284 """The request contract or ``ValueError`` listing every violation.""" 

285 return _validated(AgentCallRequestContract, value) 

286 

287 

288def validate_response_contract(value: object) -> AgentCallResponse: 

289 """The response the parent receives or ``ValueError`` listing every violation.""" 

290 return _validated(AgentCallResponse, value) 

291 

292 

293def _validated[M: BaseModel](model: type[M], value: object) -> M: 

294 try: 

295 return model.model_validate(value) 

296 except ValidationError as error: 

297 problems = [ 

298 f"{'.'.join(str(part) for part in item['loc']) or '<root>'}: {item['msg']}" 

299 for item in error.errors() 

300 ] 

301 raise ValueError("; ".join(problems)) from error 

302 

303 

304# ----- the response limits ------------------------------------------------------------------- 

305def limit_summary(summary: str, chars: int) -> tuple[str, bool]: 

306 """The summary cut to ``chars`` characters and whether it was cut.""" 

307 if len(summary) <= chars: 

308 return summary, False 

309 return summary[: max(0, chars - 1)] + "…", True 

310 

311 

312def check_answer( 

313 kind: str, 

314 result: dict[str, Any] | None, 

315 config: AgentContractConfig, 

316 *, 

317 keys: tuple[str, ...] | None = None, 

318) -> list[str]: 

319 """What a passing answer's ``result`` does against the contract of its kind: unknown keys, 

320 a size above the cap, a text field above its cap, file contents where only a conclusion is 

321 due. ``keys``: the allowed keys when they are not the kind's (a reviewer of the panel). 

322 Empty: the answer keeps the contract.""" 

323 if result is None: 

324 return [] 

325 problems: list[str] = [] 

326 allowed = RESULT_KEYS.get(kind, ()) if keys is None else keys 

327 unknown = sorted(set(result) - set(allowed)) 

328 if unknown: 

329 problems.append(f"result carries keys outside the {kind} contract: {', '.join(unknown)}") 

330 size = len(json.dumps(result, sort_keys=True).encode("utf-8")) 

331 if size > config.result_bytes(kind): 

332 problems.append(f"result is {size} bytes, above the cap of {config.result_bytes(kind)}") 

333 problems.extend(_field_problems(kind, result, config.field_chars)) 

334 return problems[:20] 

335 

336 

337def _field_problems( 

338 kind: str, value: Any, field_chars: int, path: str = "result", *, layer_names: bool = False 

339) -> list[str]: 

340 """The problems of a ``result`` value. ``layer_names``: the keys of ``value`` are layer 

341 names (an architecture ``allow`` mapping), so a layer called ``source`` or ``content`` is 

342 not taken for file content; the values under those keys are still checked.""" 

343 problems: list[str] = [] 

344 if isinstance(value, dict): 

345 for key, item in value.items(): 

346 where = f"{path}.{key}" 

347 if not layer_names and kind != "acceptance" and str(key).lower() in FILE_CONTENT_KEYS: 

348 problems.append(f"{where} carries file content; a {kind} call returns a conclusion") 

349 continue 

350 allow = kind == "architecture" and not layer_names and key == "allow" 

351 problems.extend( 

352 _field_problems( 

353 kind, item, field_chars, where, layer_names=allow and isinstance(item, dict) 

354 ) 

355 ) 

356 elif isinstance(value, list): 

357 for index, item in enumerate(value): 

358 problems.extend(_field_problems(kind, item, field_chars, f"{path}[{index}]")) 

359 elif isinstance(value, str) and len(value) > field_chars and not _is_test_file(kind, path): 

360 problems.append(f"{path} has {len(value)} characters, above the cap of {field_chars}") 

361 return problems 

362 

363 

364def _is_test_file(kind: str, path: str) -> bool: 

365 """Only the content of a test an ``acceptance`` call writes may exceed a text-field cap.""" 

366 return kind == "acceptance" and path.endswith(".content")