Coverage for src/governed_harness/orchestration/agent_results.py: 94%

570 statements  

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

1"""The agent-results settings of a run (#37-#44, #52), wired into the engine's phases. 

2 

3``RunEngine`` delegates every agent-results step to this class so that a project without any 

4of the settings runs exactly the 1.0.0 code path: ``active`` is false and the engine never calls 

5into it. Each step records what it did as evidence, events and findings on the run's chain.""" 

6 

7from __future__ import annotations 

8 

9import fnmatch 

10import json 

11from collections.abc import Callable 

12from typing import TYPE_CHECKING, Any 

13 

14from governed_harness.agents import ( 

15 AgentCallResult, 

16 AgentExecutionResult, 

17 AgentProvider, 

18 CommandAgentProvider, 

19 SimulatedAgentContext, 

20 render_instructions, 

21) 

22from governed_harness.agents.requests import READ_ONLY_KINDS, REQUEST_SCHEMA_VERSION, CallKind 

23from governed_harness.agents.risk_terms import legacy_security_words, security_terms 

24from governed_harness.agents.routing import ( 

25 RoutingHistory, 

26 TaskSignals, 

27 invoking_model, 

28 provider_family, 

29 select, 

30) 

31from governed_harness.capabilities import grants_from_rules 

32from governed_harness.configuration.agent_results import AgentCallConfig, BudgetConfig 

33from governed_harness.configuration.models import ProjectConfiguration 

34from governed_harness.domain.enums import ( 

35 ActorType, 

36 DecisionKind, 

37 ErrorKind, 

38 EvidenceKind, 

39 FindingSeverity, 

40 PhaseId, 

41 ResultStatus, 

42 ValidationKind, 

43) 

44from governed_harness.domain.errors import ConfigurationError, PolicyViolationError 

45from governed_harness.domain.ids import new_id 

46from governed_harness.domain.models import ( 

47 Actor, 

48 AgentInvocation, 

49 CapabilityGrant, 

50 ChangeRequestItem, 

51 Execution, 

52 Finding, 

53 FindingLocation, 

54 HumanDecision, 

55 PhaseExecution, 

56 ResourceUsage, 

57 Task, 

58 ValidationResult, 

59 utc_now, 

60) 

61from governed_harness.orchestration import budget as budget_rules 

62from governed_harness.orchestration.agent_contract_types import CallLimits, SentInfo 

63from governed_harness.orchestration.engine_types import READ_ONLY_RULE as READ_ONLY_RULE 

64from governed_harness.orchestration.engine_types import AgentCallOutcome as AgentCallOutcome 

65from governed_harness.orchestration.engine_types import PhaseOutcome 

66from governed_harness.orchestration.workspace_ops import ( 

67 Contents, 

68 changes_since, 

69 restore_changes, 

70 snapshot_contents, 

71) 

72from governed_harness.runtime import ( 

73 CancellationToken, 

74 PatchApplier, 

75 WorkspaceSnapshot, 

76 WorkspaceSnapshotter, 

77) 

78from governed_harness.runtime.snapshots import StoredSnapshot 

79from governed_harness.runtime.workspace import WorkspaceDiff 

80 

81if TYPE_CHECKING: 

82 from governed_harness.orchestration.engine_types import EngineServices 

83 from governed_harness.orchestration.hosts import EngineHost 

84 

85BUDGET_EXCEEDED_RULE = "budget.exceeded" 

86BUDGET_WARNING_RULE = "budget.warning" 

87 

88 

89class AgentResults: 

90 def __init__(self, engine: EngineHost) -> None: 

91 from governed_harness.orchestration.acceptance import AcceptanceTests 

92 from governed_harness.orchestration.agent_review import AgentReview 

93 from governed_harness.orchestration.corrections import Corrections 

94 from governed_harness.orchestration.decomposition import Decomposition 

95 from governed_harness.orchestration.differential import Differential 

96 from governed_harness.orchestration.gate_contract import GateContract 

97 from governed_harness.orchestration.intent_review import IntentReview 

98 from governed_harness.orchestration.lessons import Lessons 

99 from governed_harness.orchestration.stop_line import StopLine 

100 from governed_harness.orchestration.verification_checks import VerificationChecks 

101 

102 self.engine = engine 

103 self.intent = IntentReview(self) 

104 self.verification = VerificationChecks(self) 

105 self.differential = Differential(self) 

106 self.stop_line = StopLine(self) 

107 self.gate = GateContract(self) 

108 self.corrections = Corrections(self) 

109 self.agent_review = AgentReview(self) 

110 # Wave 7 (#57): the review panel replaces the single reviewer under review.panel. 

111 from governed_harness.orchestration.review_panel import PanelReview 

112 

113 self.panel = PanelReview(self) 

114 self.decomposition = Decomposition(self) 

115 self.lessons = Lessons(self) 

116 self.acceptance = AcceptanceTests(self) 

117 # #94: a frozen acceptance test the agent disputes waits for a person. 

118 from governed_harness.orchestration.acceptance_dispute import AcceptanceDisputes 

119 

120 self.disputes = AcceptanceDisputes(self, self.acceptance) 

121 # Wave 6 (#56): standards, principles, testing strategy, architecture, project setup. 

122 from governed_harness.orchestration.architecture import ArchitectureFlow 

123 from governed_harness.orchestration.engineering import Engineering 

124 from governed_harness.orchestration.project_setup import ProjectSetup 

125 

126 self.engineering = Engineering(self) 

127 self.architecture = ArchitectureFlow(self) 

128 self.project_setup = ProjectSetup(self) 

129 # Wave 11 (#97): the versioned request and response contract of agent calls. 

130 from governed_harness.orchestration.agent_contract import AgentContractFlow 

131 

132 self.agent_contract = AgentContractFlow(self) 

133 self._baselines: dict[str, StoredSnapshot | None] = {} 

134 

135 def after_verification( 

136 self, 

137 execution: Execution, 

138 change_set: Any, 

139 outputs: list[Any], 

140 ) -> list[Any]: 

141 """Reclassify failing validators against the baseline (``verification.differential``, 

142 ``verification.ratchet``).""" 

143 return self.differential.reclassify(execution, change_set, outputs) 

144 

145 def baseline_stored(self, execution: Execution) -> StoredSnapshot | None: 

146 """The workspace as DISCOVERY recorded it (1.0.0 text snapshot or manifest).""" 

147 key = execution.execution_id 

148 if key not in self._baselines: 

149 uri = self.s.state.get_flag(f"baseline:{key}") 

150 self._baselines[key] = self.engine.snapshots.load(uri) if uri else None 

151 return self._baselines[key] 

152 

153 def baseline_snapshot(self, execution: Execution) -> WorkspaceSnapshot | None: 

154 stored = self.baseline_stored(execution) 

155 return stored.snapshot if stored else None 

156 

157 def baseline_contents(self, execution: Execution) -> Contents | None: 

158 """The recorded bytes of the baseline's files (from the text it kept or from Git).""" 

159 stored = self.baseline_stored(execution) 

160 if stored is None: 160 ↛ 161line 160 didn't jump to line 161 because the condition on line 160 was never true

161 return None 

162 snapshots = self.engine.snapshots 

163 return Contents( 

164 lambda path: path in stored.snapshot.files, 

165 lambda path: snapshots.content(stored, path), 

166 ) 

167 

168 def baseline_text(self, execution: Execution) -> Callable[[str], str | None]: 

169 contents = self.baseline_contents(execution) 

170 

171 def text(path: str) -> str | None: 

172 if contents is None or not contents.existed(path): 172 ↛ 173line 172 didn't jump to line 173 because the condition on line 172 was never true

173 return None 

174 data = contents.content(path) 

175 return data.decode("utf-8", "replace") if data is not None else None 

176 

177 return text 

178 

179 def baseline_changes(self, execution: Execution) -> WorkspaceDiff | None: 

180 """Every change since DISCOVERY (not only the owned paths), with a unified diff.""" 

181 stored = self.baseline_stored(execution) 

182 if stored is None: 182 ↛ 183line 182 didn't jump to line 183 because the condition on line 182 was never true

183 return None 

184 snapshots = self.engine.snapshots 

185 return snapshots.diff(stored, snapshots.take()) 

186 

187 # ----- configuration ------------------------------------------------------------------- 

188 @property 

189 def s(self) -> EngineServices: 

190 return self.engine.s 

191 

192 @property 

193 def project(self) -> ProjectConfiguration: 

194 return self.s.resolved.project 

195 

196 @property 

197 def active(self) -> bool: 

198 """Whether any agent-results setting is configured; without one the engine runs the 

199 1.0.0 path and never calls into this class.""" 

200 project = self.project 

201 intake = project.intake 

202 verification = project.verification 

203 review = project.review 

204 runtime = project.runtime 

205 governance = project.governance_settings 

206 return any( 

207 ( 

208 intake is not None 

209 and ( 

210 intake.ambiguity_review is not None 

211 or intake.clarify_agent is not None 

212 or intake.validate_answers is not None 

213 ), 

214 verification is not None 

215 and any( 

216 getattr(verification, name) is not None 

217 for name in ( 

218 "interface", 

219 "architecture", 

220 "security_patterns", 

221 "constraints", 

222 "ratchet", 

223 "invariants", 

224 "differential", 

225 "weakened_controls", 

226 "test_quality", 

227 "secrets", 

228 "sarif", 

229 "risk_factors", 

230 "acceptance_tests", 

231 ) 

232 ), 

233 review is not None 

234 and ( 

235 review.agent_review is not None 

236 or review.reviewer is not None 

237 or review.structured_changes is not None 

238 or review.panel is not None 

239 ), 

240 runtime.gate_contract is not None or runtime.reproduce_first is not None, 

241 governance.stop_the_line is not None or governance.phase_permissions is not None, 

242 project.planning is not None, 

243 project.context is not None, 

244 project.budget is not None, 

245 project.memory is not None, 

246 project.agent_routing is not None, 

247 project.agent_contract is not None, 

248 self.engineering.configured, 

249 bool(governance.apply_repository_policies), 

250 ) 

251 ) 

252 

253 # ----- decisions: risk factors and structured change requests (#52) -------------------- 

254 def required_acknowledgements(self, execution: Execution, digest: str) -> list[str]: 

255 from governed_harness.orchestration.verification_checks import RISK_ACK_FLAG 

256 

257 value = self.flag_json(f"{RISK_ACK_FLAG}:{execution.execution_id}:{digest}") 

258 return [str(item) for item in value] if isinstance(value, list) else [] 

259 

260 def check_decision( 

261 self, 

262 execution: Execution, 

263 decision: DecisionKind, 

264 digest: str, 

265 acknowledged: tuple[str, ...], 

266 change_requests: tuple[ChangeRequestItem, ...], 

267 ) -> None: 

268 from governed_harness.configuration.agent_results import RISK_FACTORS 

269 

270 unknown = sorted(set(acknowledged) - set(RISK_FACTORS)) 

271 if unknown: 

272 raise ConfigurationError( 

273 f"unknown risk factor(s): {', '.join(unknown)}; known: {', '.join(RISK_FACTORS)}" 

274 ) 

275 if change_requests: 

276 review = self.project.review 

277 if decision is not DecisionKind.REQUEST_CHANGES: 277 ↛ 278line 277 didn't jump to line 278 because the condition on line 277 was never true

278 raise ConfigurationError("change requests need the REQUEST_CHANGES decision") 

279 if not (review and review.structured_changes): 

280 raise ConfigurationError( 

281 "change requests need review.structuredChanges: true in project.yaml" 

282 ) 

283 if decision in {DecisionKind.APPROVE, DecisionKind.APPROVE_EXCEPTION}: 

284 missing = [ 

285 item 

286 for item in self.required_acknowledgements(execution, digest) 

287 if item not in acknowledged 

288 ] 

289 if missing: 

290 raise PolicyViolationError( 

291 "this ChangeSet has risk factors a person must acknowledge before approving: " 

292 + ", ".join(missing) 

293 + " (use --acknowledge-risk for each)" 

294 ) 

295 

296 def open_change_requests(self, execution: Execution, decision: HumanDecision) -> None: 

297 """Keep the blocking items of a structured REQUEST_CHANGES as temporary criteria that 

298 every later VERIFICATION of the run checks.""" 

299 key = f"changerequests:{execution.execution_id}" 

300 current = self.flag_json(key) or [] 

301 current.extend( 

302 {**item.model_dump(mode="json", by_alias=True), "decisionId": decision.decision_id} 

303 for item in decision.change_requests 

304 ) 

305 self.set_flag_json(key, current) 

306 self.s.events.append( 

307 execution.execution_id, 

308 "change.requests.opened", 

309 { 

310 "decisionId": decision.decision_id, 

311 "items": [ 

312 item.model_dump(mode="json", by_alias=True) for item in decision.change_requests 

313 ], 

314 }, 

315 actor=decision.actor, 

316 ) 

317 

318 def change_requests(self, execution: Execution) -> list[dict[str, Any]]: 

319 value = self.flag_json(f"changerequests:{execution.execution_id}") 

320 return value if isinstance(value, list) else [] 

321 

322 @property 

323 def secrets_in_context(self) -> bool: 

324 verification = self.project.verification 

325 return bool(verification and verification.secrets == "context") 

326 

327 # ----- records ------------------------------------------------------------------------- 

328 def record_finding( 

329 self, 

330 execution: Execution, 

331 *, 

332 validator_id: str, 

333 rule_id: str, 

334 category: str, 

335 severity: FindingSeverity, 

336 message: str, 

337 path: str | None = None, 

338 line: int | None = None, 

339 evidence_refs: tuple[str, ...] = (), 

340 recommendation: str | None = None, 

341 introduced: bool | None = None, 

342 actor: Actor | None = None, 

343 ) -> Finding: 

344 provenance = self.engine._provenance(execution) 

345 if actor is not None: 

346 provenance = provenance.model_copy(update={"actor": actor}) 

347 finding = Finding( 

348 finding_id=new_id("finding"), 

349 execution_id=execution.execution_id, 

350 validator_id=validator_id, 

351 rule_id=rule_id, 

352 category=category, 

353 severity=severity, 

354 message=message, 

355 location=FindingLocation(path=path, start_line=line, end_line=line) 

356 if path or line 

357 else None, 

358 evidence_refs=evidence_refs, 

359 recommendation=recommendation, 

360 introduced=introduced, 

361 provenance=provenance, 

362 ) 

363 self.s.state.put( 

364 "finding", 

365 finding.finding_id, 

366 finding, 

367 execution_id=execution.execution_id, 

368 project_id=execution.project_id, 

369 ) 

370 self.s.events.append( 

371 execution.execution_id, 

372 "finding.recorded", 

373 finding.model_dump(mode="json"), 

374 actor=finding.provenance.actor, 

375 ) 

376 return finding 

377 

378 def record_validation( 

379 self, 

380 execution: Execution, 

381 *, 

382 validator_id: str, 

383 digest: str, 

384 status: ResultStatus, 

385 kind: ValidationKind, 

386 mandatory: bool, 

387 summary: str, 

388 findings: tuple[Finding, ...] = (), 

389 evidence_refs: tuple[str, ...], 

390 started_at: Any = None, 

391 ) -> ValidationResult: 

392 now = utc_now() 

393 actor = Actor(actor_type=ActorType.TOOL, actor_id=f"validator.{validator_id}", version="1") 

394 result = ValidationResult( 

395 validation_result_id=new_id("validation"), 

396 execution_id=execution.execution_id, 

397 validator_id=validator_id, 

398 change_set_digest=digest, 

399 status=status, 

400 kind=kind, 

401 mandatory=mandatory, 

402 summary=summary, 

403 finding_ids=tuple(item.finding_id for item in findings), 

404 evidence_refs=evidence_refs, 

405 started_at=started_at or now, 

406 finished_at=now, 

407 provenance=self.engine._provenance(execution).model_copy(update={"actor": actor}), 

408 ) 

409 self.s.state.put( 

410 "validation", 

411 result.validation_result_id, 

412 result, 

413 execution_id=execution.execution_id, 

414 project_id=execution.project_id, 

415 ) 

416 self.s.events.append( 

417 execution.execution_id, 

418 "validation.completed", 

419 result.model_dump(mode="json"), 

420 actor=result.provenance.actor, 

421 ) 

422 return result 

423 

424 def record_json( 

425 self, 

426 execution: Execution, 

427 phase_id: PhaseId, 

428 value: Any, 

429 *, 

430 kind: str, 

431 summary: str, 

432 evidence_kind: EvidenceKind = EvidenceKind.OTHER, 

433 supports: tuple[str, ...] = (), 

434 ) -> str: 

435 """Store ``value`` as a JSON artifact and record it as evidence of ``phase_id``.""" 

436 ref = self.s.artifacts.put_json( 

437 value, metadata={"kind": kind, "executionId": execution.execution_id} 

438 ) 

439 evidence = self.engine._record_evidence( 

440 execution, phase_id, evidence_kind, ref, summary, supports=supports 

441 ) 

442 return evidence.artifact_ref 

443 

444 def flag_json(self, key: str) -> Any: 

445 raw = self.s.state.get_flag(key) 

446 return json.loads(raw) if raw else None 

447 

448 def set_flag_json(self, key: str, value: Any) -> None: 

449 self.s.state.set_flag(key, json.dumps(value, sort_keys=True)) 

450 

451 # ----- budget (#42) -------------------------------------------------------------------- 

452 def _usage(self, invocations: list[AgentInvocation], project_id: str) -> budget_rules.Usage: 

453 ids = {item.invocation_id for item in invocations} 

454 usages = [ 

455 item 

456 for item in self.s.state.list("resource_usage", ResourceUsage, project_id=project_id) 

457 if item.invocation_id in ids 

458 ] 

459 return budget_rules.usage_of(invocations, usages) 

460 

461 def run_usage(self, execution: Execution) -> budget_rules.Usage: 

462 invocations = self.s.state.list( 

463 "agent_invocation", AgentInvocation, execution_id=execution.execution_id 

464 ) 

465 return self._usage(invocations, execution.project_id) 

466 

467 def task_usage(self, execution: Execution) -> budget_rules.Usage: 

468 runs = { 

469 item.execution_id 

470 for item in self.s.state.list("execution", Execution, project_id=execution.project_id) 

471 if item.task_id == execution.task_id 

472 } 

473 invocations = [ 

474 item 

475 for item in self.s.state.list( 

476 "agent_invocation", AgentInvocation, project_id=execution.project_id 

477 ) 

478 if item.execution_id in runs 

479 ] 

480 return self._usage(invocations, execution.project_id) 

481 

482 def raised_limits(self, execution: Execution) -> dict[str, dict[str, float]]: 

483 value = self.flag_json(f"budgetraise:{execution.execution_id}") 

484 return value if isinstance(value, dict) else {} 

485 

486 def budget_check( 

487 self, execution: Execution, call: budget_rules.Usage | None = None 

488 ) -> budget_rules.BudgetCheck | None: 

489 config = self.project.budget 

490 if config is None: 

491 return None 

492 usage: dict[budget_rules.Scope, budget_rules.Usage] = { 

493 "run": self.run_usage(execution), 

494 "task": self.task_usage(execution), 

495 } 

496 if call is not None: 

497 usage["call"] = call 

498 return budget_rules.evaluate(config, usage, self.raised_limits(execution)) 

499 

500 def remaining_budget(self, execution: Execution) -> dict[str, Any] | None: 

501 check = self.budget_check(execution) 

502 if check is None: 

503 return None 

504 return {"remaining": check.remaining} 

505 

506 def before_agent_call( 

507 self, execution: Execution, phase: PhaseExecution, kind: CallKind 

508 ) -> PhaseOutcome | None: 

509 """Fail closed before an agent call when a limit is already crossed (or a call crossed 

510 its per-call limit and no person raised it since). Under ``agentContract`` the call is 

511 first counted as one iteration of its agent, and refused when the agent used its cap.""" 

512 capped = self.agent_contract.begin(execution, phase, kind) 

513 if capped is not None: 

514 return capped 

515 return self.budget_block(execution, kind=kind, stopped=f"no {kind} call was made") 

516 

517 def before_phase(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome | None: 

518 """Fail closed before INDEPENDENT_REVIEW and DECISION when a limit is crossed: a limit 

519 crossed by the last agent call of a run (no further call to refuse) stops the run there, 

520 so it never reaches the decision as if it were within its budget (#157).""" 

521 return self.budget_block( 

522 execution, kind=None, stopped=f"the {phase.phase_id.value} phase was not started" 

523 ) 

524 

525 def budget_block( 

526 self, execution: Execution, *, kind: CallKind | None, stopped: str 

527 ) -> PhaseOutcome | None: 

528 """The ``BLOCKED`` outcome while a limit is crossed and no person raised it since.""" 

529 check = self.budget_check(execution) 

530 if check is None: 

531 return None 

532 crossings = list(check.exceeded) 

533 pending = self.flag_json(f"budgetblock:{execution.execution_id}") 

534 if isinstance(pending, list): 

535 raised = self.raised_limits(execution) 

536 for item in pending: 

537 limit = budget_rules.effective_limit( 

538 self.project.budget or BudgetConfig(), item["scope"], item["metric"], raised 

539 ) 

540 if limit is not None and item["used"] >= limit: 540 ↛ 536line 540 didn't jump to line 536 because the condition on line 540 was always true

541 crossings.append( 

542 budget_rules.Crossing(item["scope"], item["metric"], item["used"], limit) 

543 ) 

544 if not crossings: 

545 self.s.state.set_flag(f"budgetblock:{execution.execution_id}", "") 

546 return None 

547 self._record_crossings(execution, crossings, kind=kind, exceeded=True) 

548 reasons = "; ".join(item.describe() for item in crossings) 

549 return PhaseOutcome( 

550 ResultStatus.BLOCKED, 

551 f"{BUDGET_EXCEEDED_RULE}: {reasons}; {stopped}. Raise the limit with " 

552 "harness budget raise and continue the run.", 

553 ) 

554 

555 def after_agent_call( 

556 self, 

557 execution: Execution, 

558 phase: PhaseExecution, # NOSONAR(S1172) ResultsHost.after_agent_call signature 

559 result: AgentExecutionResult, 

560 ) -> None: 

561 """Account for a finished call: per-call limit, warnings at ``warnAt``, and a crossing 

562 that blocks the next call. First, the frozen acceptance tests the call changed are put 

563 back (``acceptanceTests.protect``, #94).""" 

564 self.acceptance.restore_frozen(execution) 

565 config = self.project.budget 

566 if config is None: 

567 return 

568 invocation = result.invocation 

569 usages = [result.usage] if result.usage is not None else [] 

570 call = budget_rules.usage_of([invocation], usages) 

571 check = self.budget_check(execution, call) 

572 if check is None: 572 ↛ 573line 572 didn't jump to line 573 because the condition on line 572 was never true

573 return 

574 if check.warnings: 

575 self._record_crossings(execution, list(check.warnings), kind=None, exceeded=False) 

576 if check.exceeded: 

577 self._record_crossings(execution, list(check.exceeded), kind=None, exceeded=True) 

578 self.set_flag_json( 

579 f"budgetblock:{execution.execution_id}", 

580 [item.as_dict() for item in check.exceeded if item.scope == "call"], 

581 ) 

582 

583 def _record_crossings( 

584 self, 

585 execution: Execution, 

586 crossings: list[budget_rules.Crossing], 

587 *, 

588 kind: str | None, 

589 exceeded: bool, 

590 ) -> None: 

591 key = f"budgetseen:{execution.execution_id}" 

592 seen = set(self.flag_json(key) or []) 

593 rule = BUDGET_EXCEEDED_RULE if exceeded else BUDGET_WARNING_RULE 

594 for crossing in crossings: 

595 marker = f"{rule}:{crossing.key}" 

596 event = "budget.exceeded" if exceeded else "budget.warning" 

597 self.s.events.append( 

598 execution.execution_id, 

599 event, 

600 {**crossing.as_dict(), "callKind": kind}, 

601 ) 

602 if marker in seen: 

603 continue 

604 seen.add(marker) 

605 self.record_finding( 

606 execution, 

607 validator_id="harness.budget", 

608 rule_id=rule, 

609 category="budget", 

610 severity=FindingSeverity.HIGH if exceeded else FindingSeverity.LOW, 

611 message=(f"Budget {'exceeded' if exceeded else 'warning'}: {crossing.describe()}"), 

612 recommendation=( 

613 "A person may raise the limit with harness budget raise (recorded) and " 

614 "continue the run." 

615 if exceeded 

616 else "The run is close to a budget limit." 

617 ), 

618 ) 

619 self.set_flag_json(key, sorted(seen)) 

620 

621 # ----- agent calls (#37, #38, #39) ----------------------------------------------------- 

622 def call_config(self, kind: CallKind) -> AgentCallConfig | None: 

623 """The configuration of a read-only call kind (``None``: the provider's defaults).""" 

624 read = _CALL_CONFIGS.get(kind) 

625 return read(self) if read is not None else None 

626 

627 def provider_for(self, execution: Execution, kind: CallKind) -> str: 

628 configured = self.call_config(kind) 

629 if configured is not None and configured.provider: 629 ↛ 630line 629 didn't jump to line 630 because the condition on line 629 was never true

630 return configured.provider 

631 provider = self.s.state.get_flag(f"provider:{execution.execution_id}") or "simulated" 

632 if provider == "session": 

633 # Embedded mode (#56): the session implements; read-only calls go to the project's 

634 # provider, so the author does not review itself. 

635 fallback = self.project.agent_provider 

636 return fallback if fallback != "session" else "simulated" 

637 return provider 

638 

639 def call_agent( 

640 self, 

641 execution: Execution, 

642 phase: PhaseExecution, 

643 kind: CallKind, 

644 payload: dict[str, Any], 

645 *, 

646 task: Task, 

647 instruction_values: dict[str, Any] | None = None, 

648 instructions_suffix: str = "", 

649 validate: Callable[[dict[str, Any]], object] | None = None, 

650 ) -> AgentCallOutcome: 

651 """Send a read-only request of ``kind`` and return its structured result. 

652 

653 The request, the provider's output and the routing decision are evidence; a call that 

654 changed the workspace is undone, gets a ``HIGH`` finding and is answered with 

655 ``ERROR``. Under ``runtime.contractRetry`` (#80) an answer that breaks its contract (a 

656 protocol error, a ``result`` that ``validate`` rejects with ``ValueError`` or, since 

657 #92, a call that changed the workspace) is sent once more, to the fallback provider 

658 when one is configured, and both attempts are recorded.""" 

659 provider_id = self.provider_for(execution, kind) 

660 first = self._call_once( 

661 execution, 

662 phase, 

663 kind, 

664 payload, 

665 task=task, 

666 provider_id=provider_id, 

667 instruction_values=instruction_values, 

668 instructions_suffix=instructions_suffix, 

669 ) 

670 retry = self.project.runtime.contract_retry 

671 problem = contract_problem(first, validate) 

672 if retry is None or not retry.enabled or problem is None: 

673 return first 

674 fallback = retry.fallback_provider or provider_id 

675 self._record_contract_retry(execution, phase, kind, first, problem, provider_id, fallback) 

676 second = self._call_once( 

677 execution, 

678 phase, 

679 kind, 

680 payload, 

681 task=task, 

682 provider_id=fallback, 

683 instruction_values=instruction_values, 

684 instructions_suffix=instructions_suffix, 

685 ) 

686 return AgentCallOutcome( 

687 status=second.status, 

688 summary=second.summary, 

689 result=second.result, 

690 invocation_id=second.invocation_id, 

691 evidence_refs=(*first.evidence_refs, *second.evidence_refs), 

692 protocol_error=second.protocol_error, 

693 ) 

694 

695 def _record_contract_retry( 

696 self, 

697 execution: Execution, 

698 phase: PhaseExecution, 

699 kind: CallKind, 

700 first: AgentCallOutcome, 

701 problem: str, 

702 provider_id: str, 

703 fallback: str, 

704 ) -> None: 

705 """The first attempt of a read-only call broke its contract: say why and where the 

706 second goes.""" 

707 record = { 

708 "callKind": kind, 

709 "attempt": 1, 

710 "provider": provider_id, 

711 "retryProvider": fallback, 

712 "problem": problem[:2000], 

713 "invocationId": first.invocation_id, 

714 "evidenceRefs": list(first.evidence_refs), 

715 } 

716 ref = self.record_json( 

717 execution, 

718 phase.phase_id, 

719 record, 

720 kind="agent-contract-retry", 

721 summary=f"The {kind} answer broke its contract; sent again to {fallback}", 

722 ) 

723 self.s.events.append( 

724 execution.execution_id, 

725 "agent.call.contract-retry", 

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

727 phase_execution_id=phase.phase_execution_id, 

728 ) 

729 

730 def _call_once( 

731 self, 

732 execution: Execution, 

733 phase: PhaseExecution, 

734 kind: CallKind, 

735 payload: dict[str, Any], 

736 *, 

737 task: Task, 

738 provider_id: str, 

739 instruction_values: dict[str, Any] | None, 

740 instructions_suffix: str, 

741 ) -> AgentCallOutcome: 

742 """One attempt of a read-only call on ``provider_id`` (see :meth:`call_agent`).""" 

743 engine = self.engine 

744 built = engine._build_provider(execution, phase, provider_id) 

745 if not isinstance(built, tuple): 745 ↛ 746line 745 didn't jump to line 746 because the condition on line 745 was never true

746 return AgentCallOutcome(built.status, built.summary, None, None, built.evidence_refs) 

747 provider, actor, _sandbox, sandbox_refs = built 

748 blocked = self.before_agent_call(execution, phase, kind) 

749 if blocked is not None: 

750 return AgentCallOutcome(blocked.status, blocked.summary, None, None, ()) 

751 grants = grants_from_rules( 

752 execution.execution_id, actor, self.s.resolved.effective_capabilities 

753 ) 

754 workspace = str(self.s.paths.workspace) 

755 request: dict[str, Any] = { 

756 "schemaVersion": REQUEST_SCHEMA_VERSION, 

757 "kind": kind, 

758 "readOnly": True, 

759 "instructions": render_instructions( 

760 kind, workspace=workspace, **(instruction_values or {}) 

761 ) 

762 + (f" {instructions_suffix}" if instructions_suffix else ""), 

763 "workspace": workspace, 

764 "task": task.model_dump(mode="json"), 

765 } 

766 request.update(payload) 

767 request.update(self.request_common(execution, phase, kind, task, provider_id, grants)) 

768 repository = self.repository_extra(read_only=True) 

769 if repository: 

770 # #5: the notice and the names of the instruction files, never their directives. 

771 request.update(repository) 

772 if "untrustedContent" in repository: 772 ↛ 774line 772 didn't jump to line 774 because the condition on line 772 was always true

773 request["instructions"] += " " + repository["untrustedContent"]["notice"] 

774 limits: CallLimits | None = None 

775 sent: SentInfo | None = None 

776 if self.agent_contract.enabled: 

777 # #97: the minimal request of this kind, with the request contract. 

778 limits = self.agent_contract.limits(execution, task, kind) 

779 try: 

780 sent = self.agent_contract.apply_read_only(execution, kind, request, limits) 

781 except ValueError as error: 

782 # A request that breaks its own contract is not sent (fail closed). 

783 message = f"agent.contract.invalid: {error}" 

784 return AgentCallOutcome(ResultStatus.BLOCKED, message, None, None, ()) 

785 request_ref = self.record_json( 

786 execution, 

787 phase.phase_id, 

788 request, 

789 kind=f"agent-{kind}-request", 

790 summary=f"Agent {kind} request to {provider_id}", 

791 ) 

792 runtime = self.project.runtime 

793 before = WorkspaceSnapshotter(self.s.paths.workspace).snapshot() 

794 context = SimulatedAgentContext( 

795 execution_id=execution.execution_id, 

796 workspace=self.s.paths.workspace, 

797 grants=grants, 

798 artifact_store=self.s.artifacts, 

799 process_runner=engine._runner(execution), 

800 patch_applier=PatchApplier(self.s.paths.workspace), 

801 provenance=engine._provenance(execution).model_copy(update={"actor": actor}), 

802 timeout_seconds=self._call_timeout(runtime.command_timeout_seconds, limits), 

803 max_output_bytes=runtime.max_output_bytes, 

804 cancellation=CancellationToken(lambda: engine.is_cancelled(execution.execution_id)), 

805 ) 

806 answer = self._call_with_retries(execution, phase, provider, kind, request, context) 

807 if answer is None: 807 ↛ 808line 807 didn't jump to line 808 because the condition on line 807 was never true

808 return AgentCallOutcome( 

809 ResultStatus.CANCELLED, "Cancellation requested", None, None, () 

810 ) 

811 self.after_agent_call(execution, phase, answer.execution) 

812 refs = (request_ref, *sandbox_refs) + ( 

813 (answer.execution.output_ref,) if answer.execution.output_ref else () 

814 ) 

815 outcome = self._read_only_outcome(execution, kind, answer, before, refs) 

816 if limits is None or sent is None: 

817 return outcome 

818 return self.agent_contract.settle( 

819 execution, 

820 phase, 

821 kind, 

822 outcome, 

823 answer, 

824 request=request, 

825 request_ref=request_ref, 

826 limits=limits, 

827 sent=sent, 

828 timeout_seconds=context.timeout_seconds, 

829 ) 

830 

831 def _call_timeout(self, command_timeout: int, limits: CallLimits | None) -> int: 

832 """The time a call may run: the command timeout, shortened to the time limit of the 

833 task's size under ``agentContract``.""" 

834 bounded = self.engine._bounded_timeout(command_timeout) 

835 return bounded if limits is None else self.agent_contract.timeout(bounded, limits) 

836 

837 def _read_only_outcome( 

838 self, 

839 execution: Execution, 

840 kind: CallKind, 

841 answer: AgentCallResult, 

842 before: WorkspaceSnapshot, 

843 refs: tuple[str, ...], 

844 ) -> AgentCallOutcome: 

845 """The outcome of a finished read-only call: its answer, or an error when it changed 

846 the workspace (undone, with a ``HIGH`` finding).""" 

847 diff = changes_since(self.s.paths.workspace, before) 

848 if diff.changes: 

849 restored, unrestorable = restore_changes( 

850 self.s.paths.workspace, snapshot_contents(before), diff 

851 ) 

852 shown = ", ".join(item.path for item in diff.changes[:10]) 

853 self.record_finding( 

854 execution, 

855 validator_id="harness.agent-calls", 

856 rule_id=READ_ONLY_RULE, 

857 category="agent-protocol", 

858 severity=FindingSeverity.HIGH, 

859 message=( 

860 f"The {kind} call is read-only but changed {len(diff.changes)} path(s): " 

861 f"{shown}; restored {len(restored)}, could not restore {len(unrestorable)}" 

862 ), 

863 path=diff.changes[0].path, 

864 evidence_refs=refs, 

865 recommendation="Use a provider that honours readOnly requests.", 

866 ) 

867 discarded = f"The {kind} call changed the workspace; its answer was discarded" 

868 return AgentCallOutcome( 

869 ResultStatus.ERROR, 

870 discarded, 

871 None, 

872 answer.execution.invocation.invocation_id, 

873 refs, 

874 workspace_violation=f"{discarded} ({shown})", 

875 ) 

876 return AgentCallOutcome( 

877 answer.execution.status, 

878 answer.execution.summary, 

879 answer.response if answer.execution.status is ResultStatus.PASSED else None, 

880 answer.execution.invocation.invocation_id, 

881 refs, 

882 protocol_error=protocol_error(answer.execution), 

883 ) 

884 

885 def _call_with_retries( 

886 self, 

887 execution: Execution, 

888 phase: PhaseExecution, 

889 provider: AgentProvider, 

890 kind: CallKind, 

891 request: dict[str, Any], 

892 context: SimulatedAgentContext, 

893 ) -> AgentCallResult | None: 

894 """The provider's answer, each one saved; a transient failure of a command provider is 

895 retried up to ``runtime.retryLimit`` times. ``None``: cancelled while waiting to retry.""" 

896 engine = self.engine 

897 runtime = self.project.runtime 

898 retries = 0 

899 while True: 

900 answer: AgentCallResult = provider.call(kind, request, context, phase_id=phase.phase_id) 

901 engine._save_agent_result(execution, phase, answer.execution) 

902 cause = ( 

903 engine._transient_cause(answer.execution) 

904 if isinstance(provider, CommandAgentProvider) and retries < runtime.retry_limit 

905 else None 

906 ) 

907 if cause is None: 907 ↛ 909line 907 didn't jump to line 909 because the condition on line 907 was always true

908 return answer 

909 retries += 1 

910 engine._record_provider_retry(execution, phase, answer.execution, cause, retries) 

911 if not engine._wait_for_retry(execution.execution_id, runtime.retry_delay_seconds): 

912 return None 

913 

914 def request_common( 

915 self, 

916 execution: Execution, 

917 phase: PhaseExecution, 

918 kind: CallKind, 

919 task: Task, 

920 provider_id: str, 

921 grants: list[CapabilityGrant], 

922 ) -> dict[str, Any]: 

923 """Keys every request of a configured run carries: routing, permissions and budget.""" 

924 extra: dict[str, Any] = {} 

925 routing = self.routing_for(execution, phase, kind, task, provider_id) 

926 if routing is not None: 

927 extra["routing"] = routing 

928 if self.project.governance_settings.phase_permissions: 

929 extra["permissions"] = self.permissions(execution, phase, kind, grants) 

930 remaining = self.remaining_budget(execution) 

931 if remaining is not None: 

932 extra["budget"] = remaining 

933 return extra 

934 

935 # ----- routing (#44) ------------------------------------------------------------------- 

936 def task_signals(self, execution: Execution, task: Task) -> TaskSignals: 

937 """Size signals known before the call: requirements, the files the task owns or 

938 names, their lines, risk flags and whether PLANNING decomposed the task.""" 

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

940 interface = task.metadata.get("interface") 

941 files = list(dict.fromkeys(owned)) 

942 loc = 0 

943 for path in files: 

944 target = self.s.paths.workspace / path 

945 try: 

946 if target.is_file(): 

947 loc += target.read_bytes().count(b"\n") 

948 except OSError: 

949 continue 

950 flags: list[str] = [] 

951 if interface: 951 ↛ 952line 951 didn't jump to line 952 because the condition on line 951 was never true

952 flags.append("interface") 

953 policy = self.project.agent_routing 

954 risk_paths = policy.risk_paths if policy and policy.risk_paths else () 

955 text = " ".join( 

956 [task.intent, *task.constraints, *(item.text for item in task.requirements)] 

957 ) 

958 # governance.riskProfile: the contextual detector; absent, the 1.x word list. 

959 if self.project.governance_settings.risk_profile is not None: 

960 worded = bool(security_terms(text, files)) 

961 else: 

962 worded = legacy_security_words(text) 

963 if worded or any( 

964 fnmatch.fnmatchcase(path, pattern) for path in files for pattern in risk_paths 

965 ): 

966 flags.append("security") 

967 return TaskSignals( 

968 requirements=len(task.requirements) or len(task.acceptance_criteria), 

969 files=len(files), 

970 loc=loc, 

971 risk_flags=tuple(flags), 

972 planned_large=bool(self.s.state.get_flag(f"decomposed:{execution.execution_id}")), 

973 ) 

974 

975 def escalations(self, execution: Execution) -> int: 

976 return int(self.s.state.get_flag(f"escalations:{execution.execution_id}") or 0) 

977 

978 def provider_command(self, provider_id: str) -> tuple[str, ...]: 

979 configured = self.project.agent_providers.get(provider_id) 

980 if configured is None: 

981 return () 

982 # A built-in adapter (kind claude-code, codex, ...) names its family by its kind. 

983 return (*(configured.command or ()), configured.kind) 

984 

985 def invoking_model(self, provider_id: str) -> str | None: 

986 """The invoking model, ceiling of ``agentRouting.mode: anchored`` (#85), of a call that 

987 ``provider_id`` answers: ``agentRouting.anchorModel`` when set, else the provider's 

988 ``model``, else the ``--model``/``-m`` value of its command or ``args``. The embedded 

989 ``session`` provider stands for the project's ``agentProvider``, which answers the 

990 read-only calls of a session run. ``None`` when nothing says it.""" 

991 return invoking_model(self.project, provider_id) 

992 

993 def routing_for( 

994 self, 

995 execution: Execution, 

996 phase: PhaseExecution, 

997 kind: CallKind, 

998 task: Task, 

999 provider_id: str, 

1000 ) -> dict[str, Any] | None: 

1001 """The model and effort of a call: the call kind's own setting, else the router's 

1002 decision under ``agentRouting``. The decision is evidence; ``None`` keeps the 

1003 provider's own model.""" 

1004 override = self.call_config(kind) 

1005 policy = self.project.agent_routing 

1006 has_override = override is not None and (override.model or override.effort) 

1007 if policy is None and not has_override: 

1008 return None 

1009 family = provider_family( 

1010 provider_id, self.provider_command(provider_id), policy.families if policy else None 

1011 ) 

1012 decision = select( 

1013 kind, 

1014 self.task_signals(execution, task), 

1015 RoutingHistory(escalations=self.escalations(execution)), 

1016 policy, 

1017 family=family, 

1018 override=override if has_override else None, 

1019 anchor=self.invoking_model(provider_id), 

1020 ) 

1021 record = {**decision.as_dict(), "provider": provider_id, "phase": phase.phase_id} 

1022 ref = self.record_json( 

1023 execution, 

1024 phase.phase_id, 

1025 record, 

1026 kind="agent-routing", 

1027 summary=( 

1028 f"Routing of the {kind} call: {decision.rule} -> " 

1029 f"{decision.model or 'provider default'}/{decision.effort or 'default'}" 

1030 ), 

1031 ) 

1032 self.s.events.append( 

1033 execution.execution_id, 

1034 "agent.routing.decided", 

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

1036 phase_execution_id=phase.phase_execution_id, 

1037 ) 

1038 if decision.warning is not None: 1038 ↛ 1040line 1038 didn't jump to line 1040 because the condition on line 1038 was never true

1039 # #59: a call kind without its own routing entry runs on the implement rung. 

1040 self.s.events.append( 

1041 execution.execution_id, 

1042 "agent.routing.fallback", 

1043 {"callKind": kind, "warning": decision.warning, "evidenceRef": ref}, 

1044 phase_execution_id=phase.phase_execution_id, 

1045 ) 

1046 if decision.model is None and decision.effort is None: 

1047 return None 

1048 value: dict[str, Any] = { 

1049 "model": decision.model, 

1050 "effort": decision.effort, 

1051 "rule": decision.rule, 

1052 "size": decision.size, 

1053 "flags": list(decision.flags), 

1054 } 

1055 if decision.rung is not None: 

1056 value["rung"] = decision.rung 

1057 return value 

1058 

1059 def permissions( 

1060 self, 

1061 execution: Execution, 

1062 phase: PhaseExecution, 

1063 kind: CallKind, 

1064 grants: list[CapabilityGrant], 

1065 ) -> dict[str, Any]: 

1066 """The permissions of a call kind derived from the agent's capability grants, recorded 

1067 as evidence (``governance.phasePermissions``).""" 

1068 from governed_harness.orchestration.gate_contract import permissions 

1069 

1070 value = permissions( 

1071 kind, 

1072 grants, 

1073 kind in READ_ONLY_KINDS, 

1074 self.engine._agent_network_allowed(), 

1075 ) 

1076 self.record_json( 

1077 execution, 

1078 phase.phase_id, 

1079 value, 

1080 kind="agent-permissions", 

1081 summary=f"Permissions of the {kind} call, derived from the capability grants", 

1082 ) 

1083 return value 

1084 

1085 def implementation_task(self, execution: Execution, task: Task) -> Task: 

1086 """The current sub-task under an approved decomposition (#39), else the task.""" 

1087 return self.decomposition.subtask_task(execution, task) 

1088 

1089 def implement_extras( 

1090 self, 

1091 execution: Execution, 

1092 phase: PhaseExecution, 

1093 task: Task, 

1094 provider_id: str, 

1095 grants: list[CapabilityGrant], 

1096 ) -> dict[str, Any] | None: 

1097 """The keys the agent-results settings add to the implement request; with any of 

1098 them the request also carries its kind and rendered instructions (schema 1.1).""" 

1099 extra = self.request_common(execution, phase, "implement", task, provider_id, grants) 

1100 notes: list[str] = [] 

1101 if self.gate.enabled: 

1102 # #84: the requirement ids and naming rule, and a check command the agent may run. 

1103 gate = self.gate.contract(execution, task, grants) 

1104 extra["gate"] = gate 

1105 notes.append(self.gate.instructions_note(gate)) 

1106 self.gate.write_check_state(execution, task) 

1107 extra.update(self.implement_context(execution, phase, task)) 

1108 extra.update(self.repository_extra(read_only=False)) 

1109 frozen = self.acceptance.request_extra(execution) 

1110 if frozen is not None: 

1111 extra["acceptanceTests"] = {**frozen, **self.disputes.request_extra(execution)} 

1112 if self.engineering.configured: 

1113 notes.insert(0, self._engineering_extra(execution, phase, task, extra)) 

1114 contract = self.agent_contract.enabled 

1115 if not extra and not contract: 

1116 return None 

1117 if contract: 

1118 notes.append(self.agent_contract.black_box_notice()) 

1119 workspace = str(self.s.paths.workspace) 

1120 suffix = " ".join(item for item in notes if item) 

1121 extra.update( 

1122 { 

1123 "schemaVersion": REQUEST_SCHEMA_VERSION, 

1124 "kind": "implement", 

1125 "workspace": workspace, 

1126 "instructions": render_instructions("implement", workspace=workspace) 

1127 + (f" {suffix}" if suffix else ""), 

1128 } 

1129 ) 

1130 if contract: 

1131 limits = self.agent_contract.limits(execution, task, "implement") 

1132 self.agent_contract.apply_implement(execution, task, extra, limits) 

1133 return extra 

1134 

1135 def _engineering_extra( 

1136 self, execution: Execution, phase: PhaseExecution, task: Task, extra: dict[str, Any] 

1137 ) -> str: 

1138 """Standards cards for the files this call works on, testing strategy and layers (#56), 

1139 selected deterministically and cached by digest: added to ``extra``; the instructions 

1140 they add are returned.""" 

1141 since = self.baseline_changes(execution) 

1142 changed = [item.path for item in since.changes] if since is not None else [] 

1143 manifest = extra.get("contextFiles") 

1144 listed = ( 

1145 [str(item.get("path")) for item in manifest.get("files", []) if item.get("path")] 

1146 if isinstance(manifest, dict) 

1147 else [] 

1148 ) 

1149 paths = self.engineering.candidate_paths(task, changed, listed) 

1150 engineering, suffix = self.engineering.implement_extra(execution, phase, paths) 

1151 extra.update(engineering) 

1152 return suffix 

1153 

1154 def repository_extra(self, *, read_only: bool) -> dict[str, Any]: 

1155 """The keys ``governance.applyRepositoryPolicies`` adds to a request (#5): the 

1156 repository's instruction files as quoted, untrusted context (only their names for a 

1157 read-only call) and the command policy.""" 

1158 from governed_harness.capabilities.repository import ( 

1159 repository_policies, 

1160 untrusted_context, 

1161 ) 

1162 

1163 policies = repository_policies(self.s.resolved) 

1164 extra: dict[str, Any] = {} 

1165 if policies.untrusted: 

1166 extra["untrustedContent"] = untrusted_context( 

1167 self.s.paths.workspace, policies.instruction_files, include_content=not read_only 

1168 ) 

1169 if policies.deny_destructive: 

1170 extra["commandPolicy"] = {"destructive": "deny"} 

1171 return extra 

1172 

1173 def implement_context( 

1174 self, execution: Execution, phase: PhaseExecution, task: Task 

1175 ) -> dict[str, Any]: 

1176 """The context manifest (#41) and the active lessons (#43) of an implement call.""" 

1177 from governed_harness.agents.context_manifest import build_manifest 

1178 from governed_harness.configuration.agent_results import ( 

1179 DEFAULT_CONTEXT_MAX_BYTES, 

1180 DEFAULT_CONTEXT_MAX_FILES, 

1181 ) 

1182 from governed_harness.orchestration.verification_checks import declared_interfaces 

1183 

1184 extra: dict[str, Any] = {} 

1185 context = self.project.context 

1186 since = self.baseline_changes(execution) 

1187 changed = [item.path for item in since.changes] if since is not None else [] 

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

1189 lessons = self.lessons.for_request(execution, phase, task, [*owned, *changed]) 

1190 if lessons: 

1191 extra["lessons"] = lessons 

1192 if context is not None and context.enabled: 

1193 interfaces = [path for pair in declared_interfaces(task) for path in pair] 

1194 lesson_paths = [path for item in lessons for path in item.get("paths", [])] 

1195 manifest = build_manifest( 

1196 self.s.paths.workspace, 

1197 task, 

1198 changed_paths=changed, 

1199 interface_paths=interfaces, 

1200 lesson_paths=lesson_paths, 

1201 located_paths=self.engine.ladder.located_paths(execution), 

1202 max_files=context.max_files or DEFAULT_CONTEXT_MAX_FILES, 

1203 max_bytes=context.max_bytes or DEFAULT_CONTEXT_MAX_BYTES, 

1204 ) 

1205 if lessons: 1205 ↛ 1206line 1205 didn't jump to line 1206 because the condition on line 1205 was never true

1206 manifest["lessons"] = [item["memoryId"] for item in lessons] 

1207 ref = self.record_json( 

1208 execution, 

1209 phase.phase_id, 

1210 manifest, 

1211 kind="context-files-manifest", 

1212 summary=( 

1213 f"Context manifest: {len(manifest['files'])} file(s), " 

1214 f"{manifest['totalBytes']} bytes, {manifest['omitted']} candidate(s) left out" 

1215 ), 

1216 ) 

1217 self.s.events.append( 

1218 execution.execution_id, 

1219 "context.manifest.built", 

1220 { 

1221 "files": len(manifest["files"]), 

1222 "totalBytes": manifest["totalBytes"], 

1223 "digest": manifest["digest"], 

1224 "evidenceRef": ref, 

1225 }, 

1226 phase_execution_id=phase.phase_execution_id, 

1227 ) 

1228 extra["contextFiles"] = manifest 

1229 return extra 

1230 

1231 def after_run(self, execution: Execution) -> Execution: 

1232 """What happens when a ``run continue`` ends: stop the line for an unapproved stop, 

1233 lessons from the corrections of a closed run.""" 

1234 execution = self.stop_line.after_continue(execution) 

1235 if execution.status is ResultStatus.PASSED and not self.s.state.get_flag( 

1236 f"lessons:{execution.execution_id}" 

1237 ): 

1238 self.s.state.set_flag(f"lessons:{execution.execution_id}", "1") 

1239 self.lessons.propose(execution) 

1240 return execution 

1241 

1242 # ----- second reviewer corrections (#38) ----------------------------------------------- 

1243 def _corrections_used(self, execution: Execution, trigger: str) -> int: 

1244 return sum( 

1245 1 

1246 for event in self.s.events.list(execution.execution_id) 

1247 if event.event_type == "correction.authorized" 

1248 and event.payload.get("trigger") == trigger 

1249 ) 

1250 

1251 def review_correction_available(self, execution: Execution) -> bool: 

1252 return self.engine._external_provider(execution.execution_id) and ( 

1253 self._corrections_used(execution, "REVIEW_FINDINGS") 

1254 < self.project.runtime.correction_limit 

1255 ) 

1256 

1257 def after_failed_review(self, execution: Execution, summary: str) -> bool: 

1258 """Send blocking findings of the agent review back to IMPLEMENTATION (with feedback 

1259 under ``runtime.providerFeedback``) while the correction budget lasts.""" 

1260 from governed_harness.domain.models import FeedbackGate 

1261 from governed_harness.orchestration.agent_review import AGENT_REVIEW_ID 

1262 

1263 engine = self.engine 

1264 execution = engine.get_execution(execution.execution_id) 

1265 if not execution.change_set_digest or not self.review_correction_available(execution): 1265 ↛ 1266line 1265 didn't jump to line 1266 because the condition on line 1265 was never true

1266 return False 

1267 used = self._corrections_used(execution, "REVIEW_FINDINGS") 

1268 limit = self.project.runtime.correction_limit 

1269 validations = engine._latest_validations( 

1270 execution.execution_id, execution.change_set_digest 

1271 ) 

1272 review = [item for item in validations if item.validator_id == AGENT_REVIEW_ID] 

1273 findings = [ 

1274 self.s.state.get("finding", finding_id, Finding) 

1275 for item in review 

1276 for finding_id in item.finding_ids 

1277 ] 

1278 if self.panel.configured: 

1279 # #57: under scoped auto-fix only the errors on lines the agent wrote go back. 

1280 findings = self.panel.scoped_findings(execution, findings) 

1281 feedback_ref: str | None = None 

1282 if engine._feedback_applies(execution.execution_id): 1282 ↛ 1296line 1282 didn't jump to line 1296 because the condition on line 1282 was always true

1283 feedback_ref = engine._record_feedback( 

1284 execution, 

1285 PhaseId.INDEPENDENT_REVIEW, 

1286 trigger="REVIEW_FINDINGS", 

1287 change_set_digest=execution.change_set_digest, 

1288 gate=FeedbackGate( 

1289 gate_id="independent_review", 

1290 status=ResultStatus.FAILED, 

1291 reason_codes=(f"{AGENT_REVIEW_ID}_FINDINGS",), 

1292 ), 

1293 validations=[], 

1294 findings=findings, 

1295 ) 

1296 transition = engine.state_machine.authorize_review_correction(PhaseId.INDEPENDENT_REVIEW) 

1297 engine._save_execution( 

1298 execution.model_copy( 

1299 update={ 

1300 "status": ResultStatus.PENDING, 

1301 "current_phase": transition.target, 

1302 "gate_evaluation_id": None, 

1303 "human_decision_id": None, 

1304 "terminal_reason": None, 

1305 "updated_at": utc_now(), 

1306 } 

1307 ) 

1308 ) 

1309 self.s.events.append( 

1310 execution.execution_id, 

1311 "correction.authorized", 

1312 { 

1313 "trigger": "REVIEW_FINDINGS", 

1314 "cycle": used + 1, 

1315 "maxCycles": limit, 

1316 "summary": summary, 

1317 "findings": [item.finding_id for item in findings], 

1318 "changeSetDigest": execution.change_set_digest, 

1319 "invalidatedPhases": [phase.value for phase in transition.invalidated], 

1320 "feedbackRef": feedback_ref, 

1321 }, 

1322 ) 

1323 self.escalate(execution, "REVIEW_FINDINGS") 

1324 return True 

1325 

1326 # ----- escalation (#44) ----------------------------------------------------------------- 

1327 def escalate(self, execution: Execution, trigger: str) -> None: 

1328 """A quality failure moves the next implement call one rung up the ladder (effort 

1329 before model) while ``agentRouting.maxEscalations`` allows; environment failures are 

1330 retried at the same rung and never get here.""" 

1331 from governed_harness.agents.routing import can_escalate 

1332 

1333 policy = self.project.agent_routing 

1334 if policy is None or policy.mode not in {"tiered", "anchored"}: 

1335 return 

1336 history = RoutingHistory(escalations=self.escalations(execution)) 

1337 if not can_escalate(history, policy): 

1338 self.s.events.append( 

1339 execution.execution_id, 

1340 "agent.routing.escalation.capped", 

1341 {"trigger": trigger, "escalations": history.escalations}, 

1342 ) 

1343 return 

1344 self.s.state.set_flag(f"escalations:{execution.execution_id}", str(history.escalations + 1)) 

1345 self.s.events.append( 

1346 execution.execution_id, 

1347 "agent.routing.escalated", 

1348 {"trigger": trigger, "escalations": history.escalations + 1}, 

1349 ) 

1350 

1351 # ----- decomposition hooks (#39) -------------------------------------------------------- 

1352 def after_passed_verification(self, execution: Execution) -> bool: 

1353 return self.decomposition.after_passed_verification(execution) 

1354 

1355 def replan_after_failure(self, execution: Execution) -> bool: 

1356 return self.decomposition.replan_after_failure(execution) 

1357 

1358 def implement_model(self, execution: Execution, task: Task) -> str | None: 

1359 """The model an implement call would use (no record): the router's choice under 

1360 ``agentRouting: tiered`` (or ``anchored``), else the provider's configured model.""" 

1361 provider_id = self.s.state.get_flag(f"provider:{execution.execution_id}") or "simulated" 

1362 configured = self.project.agent_providers.get(provider_id) 

1363 policy = self.project.agent_routing 

1364 if policy is not None: 1364 ↛ 1365line 1364 didn't jump to line 1365 because the condition on line 1364 was never true

1365 family = provider_family( 

1366 provider_id, self.provider_command(provider_id), policy.families 

1367 ) 

1368 decision = select( 

1369 "implement", 

1370 self.task_signals(execution, task), 

1371 RoutingHistory(escalations=self.escalations(execution)), 

1372 policy, 

1373 family=family, 

1374 anchor=self.invoking_model(provider_id), 

1375 ) 

1376 if decision.model: 

1377 return decision.model 

1378 return configured.model if configured else None 

1379 

1380 

1381# ----- the contract of a read-only answer (#80) ---------------------------------------------- 

1382def protocol_error(result: AgentExecutionResult) -> str | None: 

1383 """Why an answer broke the provider protocol (no JSON, no ``result`` object), or ``None``.""" 

1384 error = result.invocation.error 

1385 if result.status is not ResultStatus.ERROR or error is None: 

1386 return None 

1387 return error.message if error.kind is ErrorKind.PROTOCOL_ERROR else None 

1388 

1389 

1390def contract_problem( 

1391 outcome: AgentCallOutcome, validate: Callable[[dict[str, Any]], object] | None 

1392) -> str | None: 

1393 """Why a read-only answer breaks its contract: a protocol error, a call that changed the 

1394 workspace (#92: its answer is not trusted), or a ``result`` that the phase's ``validate`` 

1395 rejects (``ValueError``); ``None`` for an answer that keeps it, and for any other failure 

1396 (a provider that did not answer).""" 

1397 if outcome.protocol_error is not None: 

1398 return outcome.protocol_error 

1399 if outcome.workspace_violation is not None: 

1400 return outcome.workspace_violation 

1401 if validate is None or outcome.status is not ResultStatus.PASSED or outcome.result is None: 

1402 return None 

1403 try: 

1404 validate(outcome.result) 

1405 except ValueError as error: 

1406 return str(error) 

1407 return None 

1408 

1409 

1410# ----- the configuration of each read-only call kind ----------------------------------------- 

1411def _clarify_config(results: AgentResults) -> AgentCallConfig | None: 

1412 intake = results.project.intake 

1413 return intake.clarify_agent if intake else None 

1414 

1415 

1416def _review_config(results: AgentResults) -> AgentCallConfig | None: 

1417 review = results.project.review 

1418 return review.reviewer if review else None 

1419 

1420 

1421def _plan_config(results: AgentResults) -> AgentCallConfig | None: 

1422 planning = results.project.planning 

1423 return planning.planner if planning else None 

1424 

1425 

1426def _acceptance_config(results: AgentResults) -> AgentCallConfig | None: 

1427 config = results.acceptance.config 

1428 return config.author if config else None 

1429 

1430 

1431def _locate_config(results: AgentResults) -> AgentCallConfig | None: 

1432 context = results.project.context 

1433 return context.locate.agent if context and context.locate else None 

1434 

1435 

1436def _architecture_config(results: AgentResults) -> AgentCallConfig | None: 

1437 architecture = results.project.architecture 

1438 return architecture.agent if architecture else None 

1439 

1440 

1441_CALL_CONFIGS: dict[str, Callable[[AgentResults], AgentCallConfig | None]] = { 

1442 "clarify": _clarify_config, 

1443 "review": _review_config, 

1444 "plan": _plan_config, 

1445 "acceptance": _acceptance_config, 

1446 "locate": _locate_config, 

1447 "architecture": _architecture_config, 

1448}