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
« 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).
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.
11The module is pure: it reads no file and calls no agent."""
13from __future__ import annotations
15import json
16from typing import Any, Final, Literal
18from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
19from pydantic.alias_generators import to_camel
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
28CONTRACT_VERSION: Final = "1.0"
29REQUEST_KEY: Final = "agentContract"
30"""The key of a request that carries the contract."""
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"]
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."""
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."""
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``."""
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."""
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)
110class _Contract(BaseModel):
111 model_config = ConfigDict(
112 extra="forbid", populate_by_name=True, frozen=True, alias_generator=to_camel
113 )
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)."""
120 task_id: str = Field(min_length=1)
121 call_kind: CallKind
122 objective: str = Field(max_length=OBJECTIVE_CHARS)
123 fields: tuple[str, ...]
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."""
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."""
141class ExecutionConstraints(_Contract):
142 read_only: bool
143 workspace: str
144 scripts_are_black_boxes: bool = True
145 context_files_are_guidance: bool = True
148class Iteration(_Contract):
149 """The call's place in the cap of iterations of the agent in this run."""
151 number: int = Field(ge=1)
152 max: int = Field(ge=1, le=MAX_ITERATIONS_CEILING)
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
161class ExpectedResponseLimits(_Contract):
162 summary_chars: int = Field(ge=1)
163 result_bytes: int = Field(ge=1)
164 field_chars: int = Field(ge=1)
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."""
171 protocol: Literal["1.0"] = "1.0"
172 result_keys: tuple[str, ...]
173 limits: ExpectedResponseLimits
174 file_contents_allowed: bool
177class ReturnToParent(_Contract):
178 """The minimal result that reaches the parent and what never does."""
180 fields: tuple[str, ...] = RETURN_FIELDS
181 never: tuple[str, ...] = RETURN_FORBIDDEN
184class AgentCallRequestContract(_Contract):
185 """The request contract (schema ``agent-call-request.schema.json``)."""
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
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
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."""
219class AgentCallResponse(_Contract):
220 """What the parent receives from a call (schema ``agent-call-response.schema.json``)."""
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, ...] = ()
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
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}
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)
261def request_bytes(request: dict[str, Any]) -> int:
262 return len(json.dumps(request, sort_keys=True).encode("utf-8"))
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]
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 )
283def validate_request_contract(value: object) -> AgentCallRequestContract:
284 """The request contract or ``ValueError`` listing every violation."""
285 return _validated(AgentCallRequestContract, value)
288def validate_response_contract(value: object) -> AgentCallResponse:
289 """The response the parent receives or ``ValueError`` listing every violation."""
290 return _validated(AgentCallResponse, value)
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
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
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]
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
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")