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
« 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.
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."""
7from __future__ import annotations
9import fnmatch
10import json
11from collections.abc import Callable
12from typing import TYPE_CHECKING, Any
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
81if TYPE_CHECKING:
82 from governed_harness.orchestration.engine_types import EngineServices
83 from governed_harness.orchestration.hosts import EngineHost
85BUDGET_EXCEEDED_RULE = "budget.exceeded"
86BUDGET_WARNING_RULE = "budget.warning"
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
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
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
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
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
132 self.agent_contract = AgentContractFlow(self)
133 self._baselines: dict[str, StoredSnapshot | None] = {}
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)
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]
153 def baseline_snapshot(self, execution: Execution) -> WorkspaceSnapshot | None:
154 stored = self.baseline_stored(execution)
155 return stored.snapshot if stored else None
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 )
168 def baseline_text(self, execution: Execution) -> Callable[[str], str | None]:
169 contents = self.baseline_contents(execution)
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
177 return text
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())
187 # ----- configuration -------------------------------------------------------------------
188 @property
189 def s(self) -> EngineServices:
190 return self.engine.s
192 @property
193 def project(self) -> ProjectConfiguration:
194 return self.s.resolved.project
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 )
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
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 []
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
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 )
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 )
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 []
322 @property
323 def secrets_in_context(self) -> bool:
324 verification = self.project.verification
325 return bool(verification and verification.secrets == "context")
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
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
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
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
448 def set_flag_json(self, key: str, value: Any) -> None:
449 self.s.state.set_flag(key, json.dumps(value, sort_keys=True))
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)
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)
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)
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 {}
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))
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}
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")
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 )
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 )
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 )
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))
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
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
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.
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 )
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 )
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 )
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)
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 )
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
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
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 )
975 def escalations(self, execution: Execution) -> int:
976 return int(self.s.state.get_flag(f"escalations:{execution.execution_id}") or 0)
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)
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)
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
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
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
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)
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
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
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 )
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
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
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
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
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 )
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 )
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
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
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
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 )
1351 # ----- decomposition hooks (#39) --------------------------------------------------------
1352 def after_passed_verification(self, execution: Execution) -> bool:
1353 return self.decomposition.after_passed_verification(execution)
1355 def replan_after_failure(self, execution: Execution) -> bool:
1356 return self.decomposition.replan_after_failure(execution)
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
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
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
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
1416def _review_config(results: AgentResults) -> AgentCallConfig | None:
1417 review = results.project.review
1418 return review.reviewer if review else None
1421def _plan_config(results: AgentResults) -> AgentCallConfig | None:
1422 planning = results.project.planning
1423 return planning.planner if planning else None
1426def _acceptance_config(results: AgentResults) -> AgentCallConfig | None:
1427 config = results.acceptance.config
1428 return config.author if config else None
1431def _locate_config(results: AgentResults) -> AgentCallConfig | None:
1432 context = results.project.context
1433 return context.locate.agent if context and context.locate else None
1436def _architecture_config(results: AgentResults) -> AgentCallConfig | None:
1437 architecture = results.project.architecture
1438 return architecture.agent if architecture else None
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}