Coverage for src/governed_harness/orchestration/agent_contract.py: 98%

191 statements  

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

1"""The agent contract of a run (wave 11, #97), wired into the agent calls. 

2 

3With ``agentContract`` in ``project.yaml`` every agent call of a run: 

4 

5* receives the minimal request of its kind (``agents/contract.py``) with the request contract 

6 in ``agentContract``: task, allowed context, authorized resources, constraints, token budget, 

7 time limit, iteration, expected response and what returns to the parent; 

8* counts as one iteration of its agent against one cap (default 5, at most 6): the first 

9 attempt, corrections, contract retries, escalations and calls cut by a limit all count; 

10* ends in a controlled way when it reaches the time limit (the process is stopped) or the token 

11 budget (checked on the usage the provider reports: fresh input, cache creation, output and 

12 reasoning; prompt-cache reads are recorded but not counted), with a structured result; 

13* returns to the parent only the bounded response, and the harness records what was sent and 

14 what was received (``harness agent-contract calls``). 

15 

16Absent the section, nothing here runs.""" 

17 

18from __future__ import annotations 

19 

20import json 

21from dataclasses import replace 

22from typing import Any, Final, cast 

23 

24from governed_harness.agents import AgentCallResult, AgentExecutionResult 

25from governed_harness.agents.contract import ( 

26 CONTRACT_VERSION, 

27 PANEL_RESULT_KEYS, 

28 REQUEST_KEY, 

29 AgentCallRequestContract, 

30 AgentCallResponse, 

31 AuthorizedResources, 

32 ExecutionConstraints, 

33 FinalStatus, 

34 Iteration, 

35 LimitName, 

36 ReturnToParent, 

37 SizeName, 

38 TaskAssignment, 

39 Usage, 

40 check_answer, 

41 expected_response, 

42 limit_summary, 

43 minimal_task, 

44 objective_of, 

45 request_bytes, 

46 request_digest, 

47 validate_request_contract, 

48) 

49from governed_harness.agents.requests import CallKind 

50from governed_harness.agents.routing import classify_size 

51from governed_harness.agents.script_contracts import BLACK_BOX_NOTICE, brief, registry 

52from governed_harness.configuration.agent_contract import AgentContractConfig 

53from governed_harness.domain.enums import FindingSeverity, ResultStatus 

54from governed_harness.domain.models import Execution, PhaseExecution, ResourceUsage, Task 

55from governed_harness.orchestration.agent_contract_types import CallLimits, SentInfo 

56from governed_harness.orchestration.engine_types import AgentCallOutcome, PhaseOutcome 

57 

58ITERATION_EVENT: Final = "agent.iteration" 

59RECORD_EVENT: Final = "agent.call.recorded" 

60EXHAUSTED_EVENT: Final = "agent.iterations.exhausted" 

61ITERATIONS_RULE: Final = "agent.iterations.exhausted" 

62LIMIT_RULE: Final = "agent.limit.reached" 

63VIOLATION_RULE: Final = "agent.contract.violation" 

64DENIED_PATHS: Final[tuple[str, ...]] = (".git", ".harness") 

65 

66POSSIBLE_CAUSES: Final[tuple[str, ...]] = ( 

67 "badly structured prompt: the task text is vague, contradictory or too long", 

68 "wrong or insufficient context: the agent lacks the files or facts it needs", 

69 "excessive context: so much is sent that the agent loses the point", 

70 "badly delimited task: it asks for more than one thing, or its limits are not clear", 

71) 

72RECOMMENDATION: Final = ( 

73 "Do not run the task again unchanged. Restructure the input first: rewrite the task in one " 

74 "clear objective, name the files it owns and the criteria that prove it, split it when it " 

75 "asks for more than one thing, then start a new run." 

76) 

77 

78_FINAL = { 

79 ResultStatus.PASSED: "PASSED", 

80 ResultStatus.FAILED: "FAILED", 

81 ResultStatus.BLOCKED: "BLOCKED", 

82 ResultStatus.CANCELLED: "CANCELLED", 

83} 

84_REPORTED = frozenset({"PASSED", "FAILED", "BLOCKED"}) 

85 

86 

87def budgeted_tokens(usage: ResourceUsage | None) -> tuple[int, int]: 

88 """The tokens of a call that count against its budget, and its prompt-cache reads. 

89 

90 The budget counts the work of the call: input (fresh and cache creation), output and 

91 reasoning. Prompt-cache reads are part of the reported input but do not count; they are 

92 returned apart, never more than the input they are part of. A provider that reports no 

93 cache-read split counts its whole input, as before.""" 

94 if usage is None: 

95 return 0, 0 

96 inputs = usage.input_tokens or 0 

97 reads = min(usage.cache_read_tokens or 0, inputs) 

98 counted = inputs - reads + (usage.output_tokens or 0) + (usage.reasoning_tokens or 0) 

99 return counted, reads 

100 

101 

102class AgentContractFlow: 

103 def __init__(self, results: Any) -> None: 

104 self.results = results 

105 

106 @property 

107 def config(self) -> AgentContractConfig | None: 

108 config: AgentContractConfig | None = self.results.project.agent_contract 

109 return config 

110 

111 @property 

112 def enabled(self) -> bool: 

113 config = self.config 

114 return config is not None and config.enabled 

115 

116 # ----- iterations ---------------------------------------------------------------------- 

117 def used(self, execution: Execution, kind: str) -> int: 

118 """The iterations the ``kind`` agent has begun in this run.""" 

119 return sum( 

120 1 

121 for item in self.results.s.events.list(execution.execution_id) 

122 if item.event_type == ITERATION_EVENT and item.payload.get("callKind") == kind 

123 ) 

124 

125 def begin(self, execution: Execution, phase: PhaseExecution, kind: str) -> PhaseOutcome | None: 

126 """Count the iteration a call is about to be; ``None`` when it may go ahead, else the 

127 blocked outcome of an agent that used its cap.""" 

128 config = self.config 

129 if config is None or not config.enabled: 

130 return None 

131 used = self.used(execution, kind) 

132 if used >= config.iterations: 

133 return self._exhausted(execution, phase, kind, used, config.iterations) 

134 self.results.s.events.append( 

135 execution.execution_id, 

136 ITERATION_EVENT, 

137 {"callKind": kind, "number": used + 1, "max": config.iterations}, 

138 phase_execution_id=phase.phase_execution_id, 

139 ) 

140 return None 

141 

142 def _exhausted( 

143 self, execution: Execution, phase: PhaseExecution, kind: str, used: int, cap: int 

144 ) -> PhaseOutcome: 

145 message = ( 

146 f"{ITERATIONS_RULE}: the {kind} agent used {used} of {cap} iterations in this run " 

147 "without finishing. The input may be badly structured (a badly structured prompt, " 

148 "wrong or insufficient context, excessive context or a badly delimited task). " 

149 f"{RECOMMENDATION}" 

150 ) 

151 events = self.results.s.events.list(execution.execution_id) 

152 if any( 152 ↛ 156line 152 didn't jump to line 156 because the condition on line 152 was never true

153 item.event_type == EXHAUSTED_EVENT and item.payload.get("callKind") == kind 

154 for item in events 

155 ): 

156 return PhaseOutcome(ResultStatus.BLOCKED, message) 

157 history = [ 

158 { 

159 key: item.payload.get(key) 

160 for key in ("iteration", "finalStatus", "limitReached", "violations", "summary") 

161 } 

162 for item in events 

163 if item.event_type == RECORD_EVENT and item.payload.get("callKind") == kind 

164 ] 

165 config = self.config or AgentContractConfig() 

166 # #149: what the parent receives instead of a call, as a response contract. 

167 response = AgentCallResponse( 

168 call_kind=cast(CallKind, kind), 

169 iteration=max(1, used), 

170 final_status="ITERATIONS_EXHAUSTED", 

171 summary=limit_summary(message, config.summary_chars)[0], 

172 ) 

173 record = { 

174 "callKind": kind, 

175 "used": used, 

176 "max": cap, 

177 "finalStatus": response.final_status, 

178 "response": response.model_dump(mode="json", by_alias=True), 

179 "iterations": history, 

180 "possibleCauses": list(POSSIBLE_CAUSES), 

181 "recommendation": RECOMMENDATION, 

182 } 

183 ref: str = self.results.record_json( 

184 execution, 

185 phase.phase_id, 

186 record, 

187 kind="agent-iteration-cap", 

188 summary=f"The {kind} agent used its {cap} iterations", 

189 ) 

190 self.results.s.events.append( 

191 execution.execution_id, 

192 EXHAUSTED_EVENT, 

193 {**record, "evidenceRef": ref}, 

194 phase_execution_id=phase.phase_execution_id, 

195 ) 

196 self.results.record_finding( 

197 execution, 

198 validator_id="harness.agent-contract", 

199 rule_id=ITERATIONS_RULE, 

200 category="agent-protocol", 

201 severity=FindingSeverity.HIGH, 

202 message=message, 

203 evidence_refs=(ref,), 

204 recommendation=RECOMMENDATION, 

205 ) 

206 return PhaseOutcome(ResultStatus.BLOCKED, message, (ref,)) 

207 

208 # ----- limits -------------------------------------------------------------------------- 

209 def limits(self, execution: Execution, task: Task, kind: str | None = None) -> CallLimits: 

210 """The token budget and the time limit for the size the router gives the task (and, 

211 under ``budgetProfile: by-kind``, for the call's ``kind``).""" 

212 config = self.config or AgentContractConfig() 

213 policy = self.results.project.agent_routing 

214 size, _rule = classify_size( 

215 self.results.task_signals(execution, task), policy.thresholds if policy else None 

216 ) 

217 tokens, seconds = config.budget_for(size, kind) 

218 return CallLimits(size, tokens, seconds) 

219 

220 @staticmethod 

221 def timeout(default: int, limits: CallLimits) -> int: 

222 """The time a process may run: the command timeout, or the limit of the task's size 

223 when that is shorter.""" 

224 return min(default, limits.seconds) 

225 

226 # ----- the request --------------------------------------------------------------------- 

227 def apply_read_only( 

228 self, execution: Execution, kind: CallKind, request: dict[str, Any], limits: CallLimits 

229 ) -> SentInfo: 

230 """Reduce the task of a read-only request to the fields its kind needs and add the 

231 request contract.""" 

232 task = request.get("task") 

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

234 omitted: tuple[str, ...] = () 

235 if isinstance(task, dict): 235 ↛ 239line 235 didn't jump to line 239 because the condition on line 235 was always true

236 request["task"] = minimal_task(kind, task) 

237 kept = tuple(request["task"]) 

238 omitted = tuple(name for name in task if name not in request["task"]) 

239 info = SentInfo(kept, omitted, self.used(execution, kind)) 

240 resources = AuthorizedResources( 

241 read_paths=(str(request.get("workspace", ".")),), 

242 write_paths=(), 

243 deny_paths=DENIED_PATHS, 

244 ) 

245 self._attach(request, kind, limits, resources, info, read_only=True) 

246 return info 

247 

248 def apply_implement( 

249 self, execution: Execution, task: Task, extra: dict[str, Any], limits: CallLimits 

250 ) -> None: 

251 """Add the request contract, the script contracts and the black-box notice to the 

252 extras of an implement request.""" 

253 owned = [str(item) for item in task.metadata.get("ownedPaths") or []] 

254 workspace = str(extra.get("workspace", ".")) 

255 gate = extra.get("gate") or {} 

256 ids = self._script_ids(gate) 

257 contracts = registry(self.results.gate.validators()) 

258 briefs = [brief(contracts[item]) for item in ids if item in contracts] 

259 if briefs: 

260 extra["scriptContracts"] = briefs 

261 manifest = extra.get("contextFiles") 

262 files = manifest.get("files", []) if isinstance(manifest, dict) else [] 

263 resources = AuthorizedResources( 

264 read_paths=(workspace,), 

265 write_paths=tuple(owned) or (workspace,), 

266 guidance_paths=tuple(str(item["path"]) for item in files if item.get("path")), 

267 deny_paths=DENIED_PATHS, 

268 commands=(" ".join(gate["checkCommand"]),) if "checkCommand" in gate else (), 

269 scripts=tuple(ids), 

270 ) 

271 info = SentInfo(("task", "plan"), (), self.used(execution, "implement")) 

272 self._attach(extra, "implement", limits, resources, info, read_only=False, task=task) 

273 

274 @staticmethod 

275 def _script_ids(gate: dict[str, Any]) -> list[str]: 

276 if "checkCommand" in gate: 276 ↛ 277line 276 didn't jump to line 277 because the condition on line 276 was never true

277 return ["harness.check"] 

278 return [f"validator.{item['id']}" for item in gate.get("checkCommands") or []] 

279 

280 def _attach( 

281 self, 

282 request: dict[str, Any], 

283 kind: CallKind, 

284 limits: CallLimits, 

285 resources: AuthorizedResources, 

286 info: SentInfo, 

287 *, 

288 read_only: bool, 

289 task: Task | None = None, 

290 ) -> None: 

291 config = self.config or AgentContractConfig() 

292 task_view = request.get("task") if task is None else task.model_dump(mode="json") 

293 view = task_view if isinstance(task_view, dict) else {} 

294 keys = sorted({*request, REQUEST_KEY, *(() if read_only else ("task", "plan"))}) 

295 contract = AgentCallRequestContract( 

296 call_kind=kind, 

297 task=TaskAssignment( 

298 task_id=str(view.get("task_id", "")) or "-", 

299 call_kind=kind, 

300 objective=objective_of(view), 

301 fields=info.kept, 

302 ), 

303 allowed_context=tuple(keys), 

304 resources=resources, 

305 constraints=ExecutionConstraints( 

306 read_only=read_only, workspace=str(request.get("workspace", ".")) 

307 ), 

308 token_budget=limits.tokens, 

309 time_limit_seconds=limits.seconds, 

310 size_class=cast(SizeName, limits.size), 

311 iteration=Iteration(number=max(1, info.iteration), max=config.iterations), 

312 expected_response=expected_response(kind, config), 

313 return_to_parent=ReturnToParent(), 

314 ) 

315 request[REQUEST_KEY] = contract.model_dump(mode="json", by_alias=True) 

316 

317 @staticmethod 

318 def black_box_notice() -> str: 

319 return BLACK_BOX_NOTICE 

320 

321 # ----- the response -------------------------------------------------------------------- 

322 def judge_limit( 

323 self, 

324 answer: AgentExecutionResult, 

325 limits: CallLimits, 

326 timeout_seconds: int | None = None, 

327 ) -> tuple[str, str] | None: 

328 """The limit a finished call reached, as ``(name, description)``: its process was 

329 stopped at the time limit, or the usage the provider reported is above the token 

330 budget. ``None``: neither. 

331 

332 ``timeout_seconds`` is the time the call was allowed to run: the command timeout 

333 (``runtime.commandTimeoutSeconds``, bounded by the run budget) when it is shorter than 

334 the limit of the task's size. The description names the limit that stopped the call, 

335 the smaller of the two (#179); without it, the size's limit as before.""" 

336 timed_out = answer.status is ResultStatus.TIMED_OUT or any( 

337 item.timed_out for item in answer.tool_invocations 

338 ) 

339 if timed_out: 

340 if timeout_seconds is not None and timeout_seconds < limits.seconds: 

341 return "time", ( 

342 f"the call was stopped at the command timeout ({timeout_seconds} s), " 

343 f"shorter than its time limit ({limits.seconds} s)" 

344 ) 

345 return "time", f"the call was stopped at its time limit ({limits.seconds} s)" 

346 used, reads = budgeted_tokens(answer.usage) 

347 if used > limits.tokens: 

348 return "tokens", ( 

349 f"the call used {used} counted tokens (input, cache creation, output and " 

350 f"reasoning) of a budget of {limits.tokens}; {reads} prompt-cache read tokens " 

351 "were recorded and not counted" 

352 ) 

353 return None 

354 

355 def settle( 

356 self, 

357 execution: Execution, 

358 phase: PhaseExecution, 

359 kind: CallKind, 

360 outcome: AgentCallOutcome, 

361 answer: AgentCallResult, 

362 *, 

363 request: dict[str, Any], 

364 request_ref: str, 

365 limits: CallLimits, 

366 sent: SentInfo, 

367 timeout_seconds: int | None = None, 

368 ) -> AgentCallOutcome: 

369 """Judge a finished read-only call against the contract (limit reached, response out 

370 of bounds), record what was sent and received, and return the outcome the parent sees. 

371 ``timeout_seconds``: the time the call was allowed to run (``judge_limit``).""" 

372 config = self.config or AgentContractConfig() 

373 final, limit, violations, outcome = self._judge( 

374 kind, outcome, answer, limits, config, sent.iteration, timeout_seconds=timeout_seconds 

375 ) 

376 summary, cut = limit_summary(outcome.summary, config.summary_chars) 

377 outcome = replace(outcome, summary=summary) 

378 response = self._response( 

379 kind, outcome, answer.execution, final, sent.iteration, limit, violations 

380 ) 

381 self._record( 

382 execution, 

383 phase, 

384 kind, 

385 response, 

386 sent=sent, 

387 limits=limits, 

388 digest=request_digest(request), 

389 size=request_bytes(request), 

390 request_ref=request_ref, 

391 keys=sorted(request), 

392 answer=answer.execution, 

393 truncated=cut, 

394 ) 

395 return outcome 

396 

397 def settle_reviewer( 

398 self, 

399 execution: Execution, 

400 phase: PhaseExecution, 

401 reviewer: str, 

402 answer: AgentCallResult, 

403 *, 

404 request: dict[str, Any], 

405 request_ref: str | None, 

406 limits: CallLimits, 

407 ) -> str | None: 

408 """Judge the answer of one reviewer of the review panel as a ``review`` call (#149): 

409 the limit it reached and the result limits of the kind, with the keys of the panel's 

410 answer (``PANEL_RESULT_KEYS``); record what was sent and received. The reason the answer 

411 must be discarded (a limit reached or the contract broken), else ``None``. The iteration 

412 is the one the panel's batch began (``before_agent_call``).""" 

413 config = self.config or AgentContractConfig() 

414 iteration = self.used(execution, "review") 

415 result = answer.execution 

416 passed = result.status is ResultStatus.PASSED and isinstance(answer.response, dict) 

417 outcome = AgentCallOutcome( 

418 result.status, 

419 result.summary, 

420 answer.response if passed else None, 

421 result.invocation.invocation_id, 

422 (), 

423 ) 

424 final, limit, violations, outcome = self._judge( 

425 "review", outcome, answer, limits, config, iteration, keys=PANEL_RESULT_KEYS 

426 ) 

427 summary, cut = limit_summary(outcome.summary, config.summary_chars) 

428 outcome = replace(outcome, summary=summary) 

429 response = self._response("review", outcome, result, final, iteration, limit, violations) 

430 self._record( 

431 execution, 

432 phase, 

433 "review", 

434 response, 

435 sent=SentInfo((), (), iteration), 

436 limits=limits, 

437 digest=request_digest(request), 

438 size=request_bytes(request), 

439 request_ref=request_ref, 

440 keys=sorted(request), 

441 answer=result, 

442 truncated=cut, 

443 reviewer=reviewer, 

444 ) 

445 if final in {"LIMIT_REACHED", "CONTRACT_VIOLATION"}: 

446 return summary 

447 return None 

448 

449 def _judge( 

450 self, 

451 kind: CallKind, 

452 outcome: AgentCallOutcome, 

453 answer: AgentCallResult, 

454 limits: CallLimits, 

455 config: AgentContractConfig, 

456 iteration: int, 

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

458 timeout_seconds: int | None = None, 

459 ) -> tuple[str, str | None, tuple[str, ...], AgentCallOutcome]: 

460 reached = self.judge_limit(answer.execution, limits, timeout_seconds) 

461 if reached is not None: 

462 name, text = reached 

463 message = f"{LIMIT_RULE}: {text}; the call ended and counts as iteration {iteration}" 

464 return ( 

465 "LIMIT_REACHED", 

466 name, 

467 (), 

468 replace(outcome, status=ResultStatus.BLOCKED, summary=message, result=None), 

469 ) 

470 problems = ( 

471 check_answer(kind, outcome.result, config, keys=keys) 

472 if outcome.status is ResultStatus.PASSED 

473 else [] 

474 ) 

475 if problems: 

476 message = f"{VIOLATION_RULE}: {'; '.join(problems)}" 

477 return ( 

478 "CONTRACT_VIOLATION", 

479 None, 

480 tuple(problems), 

481 replace( 

482 outcome, 

483 status=ResultStatus.ERROR, 

484 summary=message, 

485 result=None, 

486 protocol_error=message, 

487 ), 

488 ) 

489 return _FINAL.get(outcome.status, "ERROR"), None, (), outcome 

490 

491 def _response( 

492 self, 

493 kind: CallKind, 

494 outcome: AgentCallOutcome, 

495 answer: AgentExecutionResult, 

496 final: str, 

497 iteration: int, 

498 limit: str | None, 

499 violations: tuple[str, ...], 

500 ) -> AgentCallResponse: 

501 usage = answer.usage 

502 reported = outcome.status.value if outcome.status.value in _REPORTED else None 

503 return AgentCallResponse( 

504 call_kind=kind, 

505 invocation_id=outcome.invocation_id, 

506 iteration=max(1, iteration), 

507 status=cast(Any, reported), 

508 final_status=cast(FinalStatus, final), 

509 summary=outcome.summary, 

510 result=outcome.result if final == "PASSED" else None, 

511 usage=Usage( 

512 input_tokens=usage.input_tokens, 

513 output_tokens=usage.output_tokens, 

514 reasoning_tokens=usage.reasoning_tokens, 

515 cache_read_tokens=usage.cache_read_tokens, 

516 ) 

517 if usage is not None 

518 else None, 

519 limit_reached=cast(LimitName | None, limit), 

520 violations=violations, 

521 ) 

522 

523 def _record( 

524 self, 

525 execution: Execution, 

526 phase: PhaseExecution, 

527 kind: CallKind, 

528 response: AgentCallResponse, 

529 *, 

530 sent: SentInfo, 

531 limits: CallLimits, 

532 digest: str, 

533 size: int | None, 

534 request_ref: str | None, 

535 keys: list[str], 

536 answer: AgentExecutionResult, 

537 truncated: bool, 

538 reviewer: str | None = None, 

539 ) -> str: 

540 received = response.model_dump(mode="json", by_alias=True) 

541 own = {"reviewer": reviewer} if reviewer is not None else {} 

542 record = { 

543 "contractVersion": CONTRACT_VERSION, 

544 "callKind": kind, 

545 **own, 

546 "iteration": sent.iteration, 

547 "provider": answer.invocation.provider, 

548 "invocationId": answer.invocation.invocation_id, 

549 "size": limits.size, 

550 "tokenBudget": limits.tokens, 

551 "timeLimitSeconds": limits.seconds, 

552 "sent": { 

553 "requestRef": request_ref, 

554 "digest": digest, 

555 "bytes": size, 

556 "topLevelKeys": keys, 

557 "taskFields": list(sent.kept), 

558 "taskFieldsOmitted": list(sent.omitted), 

559 }, 

560 "received": received, 

561 "receivedBytes": len(json.dumps(received, sort_keys=True).encode("utf-8")), 

562 "summaryTruncated": truncated, 

563 "raw": { 

564 "outputRef": answer.output_ref, 

565 "note": "The provider's full output, kept for diagnosis; the parent does not " 

566 "receive it.", 

567 }, 

568 } 

569 ref: str = self.results.record_json( 

570 execution, 

571 phase.phase_id, 

572 record, 

573 kind="agent-call-record", 

574 summary=f"{kind} call {sent.iteration}: sent and received ({response.final_status})", 

575 ) 

576 self.results.s.events.append( 

577 execution.execution_id, 

578 RECORD_EVENT, 

579 { 

580 "callKind": kind, 

581 **own, 

582 "iteration": sent.iteration, 

583 "finalStatus": response.final_status, 

584 "limitReached": response.limit_reached, 

585 "violations": list(response.violations), 

586 "summary": response.summary[:200], 

587 "invocationId": record["invocationId"], 

588 "provider": record["provider"], 

589 "size": limits.size, 

590 "sentBytes": size, 

591 "receivedBytes": record["receivedBytes"], 

592 "evidenceRef": ref, 

593 }, 

594 phase_execution_id=phase.phase_execution_id, 

595 ) 

596 if response.final_status in {"LIMIT_REACHED", "CONTRACT_VIOLATION"}: 

597 self._finding(execution, response, ref) 

598 return ref 

599 

600 def _finding(self, execution: Execution, response: AgentCallResponse, ref: str) -> None: 

601 rule = LIMIT_RULE if response.final_status == "LIMIT_REACHED" else VIOLATION_RULE 

602 self.results.record_finding( 

603 execution, 

604 validator_id="harness.agent-contract", 

605 rule_id=rule, 

606 category="agent-protocol", 

607 severity=FindingSeverity.HIGH 

608 if response.final_status == "LIMIT_REACHED" 

609 else FindingSeverity.MEDIUM, 

610 message=response.summary[:1000], 

611 evidence_refs=(ref,), 

612 recommendation="Narrow the task or raise the limit of its size (agentContract) " 

613 "and run again; the provider's output is kept as evidence.", 

614 ) 

615 

616 # ----- implement ----------------------------------------------------------------------- 

617 def settle_implement( 

618 self, 

619 execution: Execution, 

620 phase: PhaseExecution, 

621 answer: AgentExecutionResult, 

622 contract: dict[str, Any], 

623 *, 

624 timeout_seconds: int | None = None, 

625 ) -> PhaseOutcome | None: 

626 """Record an implement call and end it in a controlled way when it reached its time 

627 limit or its token budget; ``None`` otherwise (the phase goes on as before). 

628 ``timeout_seconds``: the time the call was allowed to run (``judge_limit``).""" 

629 config = self.config or AgentContractConfig() 

630 validated = validate_request_contract(contract) 

631 limits = CallLimits( 

632 validated.size_class, validated.token_budget, validated.time_limit_seconds 

633 ) 

634 iteration = validated.iteration.number 

635 reached = self.judge_limit(answer, limits, timeout_seconds) 

636 status = ResultStatus.BLOCKED if reached is not None else answer.status 

637 final = "LIMIT_REACHED" if reached is not None else _FINAL.get(status, "ERROR") 

638 message = ( 

639 f"{LIMIT_RULE}: {reached[1]}; the call ended and counts as iteration {iteration}" 

640 if reached is not None 

641 else answer.summary 

642 ) 

643 summary, cut = limit_summary(message, config.summary_chars) 

644 response = AgentCallResponse( 

645 call_kind="implement", 

646 invocation_id=answer.invocation.invocation_id, 

647 iteration=iteration, 

648 status=cast(Any, status.value if status.value in _REPORTED else None), 

649 final_status=cast(FinalStatus, final), 

650 summary=summary, 

651 limit_reached=cast(LimitName | None, reached[0] if reached is not None else None), 

652 ) 

653 ref = self._record( 

654 execution, 

655 phase, 

656 "implement", 

657 response, 

658 sent=SentInfo(validated.task.fields, (), iteration), 

659 limits=limits, 

660 digest=answer.invocation.prompt_digest, 

661 size=answer.request_bytes, 

662 request_ref=None, 

663 keys=list(validated.allowed_context), 

664 answer=answer, 

665 truncated=cut, 

666 ) 

667 if reached is None: 

668 return None 

669 return PhaseOutcome(ResultStatus.BLOCKED, summary, (ref,))