Coverage for src/governed_harness/review/invoke.py: 85%
123 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"""How the panel reaches the providers: parallel, read-only, isolated (#57).
3``ProviderInvoker`` answers a batch of reviewer calls. The provider processes run in parallel
4(up to ``review.panel.parallel``); everything the harness records runs on the calling thread,
5before and after the batch, so the record keeps one writer. Isolation of a reviewer:
7* **read-only**: the request says so, the agent sandbox (when enforced) keeps the workspace
8 read-only for the reviewer's process, and the workspace is compared before and after the batch:
9 a batch that changed it is undone and every answer of it is discarded;
10* **tools**: the request carries the reviewer's tool allowlist (``isolation.tools``); the
11 built-in adapters pass it to the CLI (see ``agents.native``);
12* **MCP**: only the servers of ``review.panel.mcpServers`` that the reviewer names, in a strict
13 configuration; nothing else the user configured;
14* **no inherited configuration**: the provider process gets only the environment the provider
15 declares, and the adapters ask their CLI not to read the user's settings."""
17from __future__ import annotations
19import contextvars
20from collections.abc import Callable, Sequence
21from concurrent.futures import ThreadPoolExecutor
22from dataclasses import dataclass
23from pathlib import Path
24from typing import Any, Protocol
26from governed_harness.agents import AgentCallResult, SimulatedAgentContext
27from governed_harness.domain.enums import PhaseId, ResultStatus
28from governed_harness.domain.models import Actor, CapabilityGrant, Provenance
29from governed_harness.evidence.artifact_store import LocalArtifactStore
30from governed_harness.orchestration.workspace_ops import (
31 changes_since,
32 restore_changes,
33 snapshot_contents,
34)
35from governed_harness.review.panel import ReviewerAnswer, ReviewerCall
36from governed_harness.runtime import CancellationToken, PatchApplier, WorkspaceSnapshotter
37from governed_harness.runtime.process_runner import SafeProcessRunner
38from governed_harness.runtime.workspace import WorkspaceDiff, WorkspaceSnapshot
41class CallingProvider(Protocol):
42 def call(
43 self, kind: Any, request: dict[str, Any], context: Any, *, phase_id: PhaseId
44 ) -> AgentCallResult:
45 """Send a read-only request of ``kind`` and return the provider's answer."""
48@dataclass(frozen=True)
49class BuiltProvider:
50 provider: CallingProvider
51 actor: Actor
52 refs: tuple[str, ...] = ()
55def usage_tokens(result: AgentCallResult) -> int | None:
56 usage = result.execution.usage
57 if usage is None:
58 return None
59 values = [usage.input_tokens, usage.output_tokens, usage.reasoning_tokens]
60 known = [value for value in values if value is not None]
61 return sum(known) if known else None
64def _never_cancelled() -> bool:
65 return False
68@dataclass(frozen=True)
69class InvokerHooks:
70 """What the caller runs around a batch: ``cancelled`` is polled by the provider processes,
71 ``before`` may block the whole batch with a reason, ``record_request`` records each request
72 and returns its reference, ``after`` sees each answer and ``on_violation`` hears of a batch
73 that changed the workspace (the diff, restored and unrestorable counts). ``judge`` (since
74 #149, the agent contract) sees each answer with its recorded request reference and returns
75 the reason to discard it (a limit reached, a result outside the contract), else ``None``."""
77 cancelled: Callable[[], bool] = _never_cancelled
78 before: Callable[[Sequence[ReviewerCall]], str | None] | None = None
79 record_request: Callable[[ReviewerCall], str | None] | None = None
80 after: Callable[[ReviewerCall, AgentCallResult], None] | None = None
81 on_violation: Callable[[WorkspaceDiff, int, int], None] | None = None
82 judge: Callable[[ReviewerCall, AgentCallResult, str | None], str | None] | None = None
85class ProviderInvoker:
86 def __init__(
87 self,
88 *,
89 workspace: Path,
90 artifacts: LocalArtifactStore,
91 runner: SafeProcessRunner,
92 provenance: Provenance,
93 build: Callable[[str], BuiltProvider | str],
94 grants_for: Callable[[Actor], list[CapabilityGrant]],
95 execution_id: str,
96 phase_id: PhaseId,
97 default_timeout: int,
98 max_output_bytes: int,
99 hooks: InvokerHooks | None = None,
100 guard_workspace: bool = True,
101 mcp_servers: dict[str, Any] | None = None,
102 ) -> None:
103 hooks = hooks or InvokerHooks()
104 self.workspace = workspace
105 self.artifacts = artifacts
106 self.runner = runner
107 self.provenance = provenance
108 self.build = build
109 self.grants_for = grants_for
110 self.execution_id = execution_id
111 self.phase_id = phase_id
112 self.default_timeout = default_timeout
113 self.max_output_bytes = max_output_bytes
114 self.cancelled = hooks.cancelled
115 self.before = hooks.before
116 self.record_request = hooks.record_request
117 self.after = hooks.after
118 self.on_violation = hooks.on_violation
119 self.judge = hooks.judge
120 self.guard_workspace = guard_workspace
121 self.mcp_servers = mcp_servers or {}
122 self._built: dict[str, BuiltProvider | str] = {}
124 def _provider(self, provider_id: str) -> BuiltProvider | str:
125 if provider_id not in self._built:
126 self._built[provider_id] = self.build(provider_id)
127 return self._built[provider_id]
129 def invoke(self, calls: Sequence[ReviewerCall], workers: int) -> list[ReviewerAnswer]:
130 if not calls: 130 ↛ 131line 130 didn't jump to line 131 because the condition on line 130 was never true
131 return []
132 blocked = self.before(calls) if self.before is not None else None
133 if blocked is not None: 133 ↛ 134line 133 didn't jump to line 134 because the condition on line 133 was never true
134 return [ReviewerAnswer("ERROR", None, blocked, call.provider) for call in calls]
135 request_refs = [
136 self.record_request(call) if self.record_request is not None else None for call in calls
137 ]
138 built = [self._provider(call.provider) for call in calls]
139 # The grants are made here, on the calling thread, where the policy of the running
140 # phase applies (governance.phaseCapabilities, #4); the workers only use them.
141 grants = [
142 self.grants_for(target.actor) if isinstance(target, BuiltProvider) else []
143 for target in built
144 ]
145 snapshot = WorkspaceSnapshotter(self.workspace).snapshot() if self.guard_workspace else None
147 def run(index: int) -> AgentCallResult | str:
148 return self._call(calls[index], built[index], grants[index])
150 with ThreadPoolExecutor(max_workers=max(1, min(workers, len(calls)))) as pool:
151 # Each worker runs in a copy of this context: the policies of the running phase
152 # (capabilities, destructive commands) reach the provider processes it starts.
153 parent = contextvars.copy_context()
154 results = list(pool.map(lambda index: parent.copy().run(run, index), range(len(calls))))
155 answers = [
156 self._answer(call, result, request_ref, target)
157 for call, result, request_ref, target in zip(
158 calls, results, request_refs, built, strict=True
159 )
160 ]
161 if snapshot is not None: 161 ↛ 163line 161 didn't jump to line 163 because the condition on line 161 was always true
162 answers = self._guarded(snapshot, answers)
163 return answers
165 def _call(
166 self, call: ReviewerCall, target: BuiltProvider | str, grants: list[CapabilityGrant]
167 ) -> AgentCallResult | str:
168 """One reviewer call on a worker; a provider that cannot start or raises is the reason
169 its answer never came."""
170 if isinstance(target, str): 170 ↛ 171line 170 didn't jump to line 171 because the condition on line 170 was never true
171 return target
172 timeout = self.default_timeout
173 if call.timeout_seconds: 173 ↛ 175line 173 didn't jump to line 175 because the condition on line 173 was always true
174 timeout = min(call.timeout_seconds, self.default_timeout)
175 context = SimulatedAgentContext(
176 execution_id=self.execution_id,
177 workspace=self.workspace,
178 grants=grants,
179 artifact_store=self.artifacts,
180 process_runner=self.runner,
181 patch_applier=PatchApplier(self.workspace),
182 provenance=self.provenance.model_copy(update={"actor": target.actor}),
183 timeout_seconds=timeout,
184 max_output_bytes=self.max_output_bytes,
185 cancellation=CancellationToken(self.cancelled),
186 )
187 try:
188 return target.provider.call(
189 "review", self._with_mcp(call.request), context, phase_id=self.phase_id
190 )
191 except Exception as error: # a provider that raises is an answer that never came
192 return f"the provider raised {type(error).__name__}: {error}"
194 def _with_mcp(self, request: dict[str, Any]) -> dict[str, Any]:
195 """The definitions of the allowed MCP servers reach the provider process only; the
196 recorded request keeps their names."""
197 isolation = request.get("isolation")
198 if not isinstance(isolation, dict): 198 ↛ 199line 198 didn't jump to line 199 because the condition on line 198 was never true
199 return request
200 names = [str(item) for item in isolation.get("mcpServers") or []]
201 config = {name: self.mcp_servers[name] for name in names if name in self.mcp_servers}
202 return {**request, "isolation": {**isolation, "mcpConfig": config}}
204 def _answer(
205 self,
206 call: ReviewerCall,
207 result: AgentCallResult | str,
208 request_ref: str | None,
209 target: BuiltProvider | str,
210 ) -> ReviewerAnswer:
211 if isinstance(result, str): 211 ↛ 212line 211 didn't jump to line 212 because the condition on line 211 was never true
212 return ReviewerAnswer("ERROR", None, result, call.provider)
213 if self.after is not None:
214 self.after(call, result)
215 built_refs = target.refs if isinstance(target, BuiltProvider) else ()
216 refs = tuple(
217 item for item in (request_ref, *built_refs, result.execution.output_ref) if item
218 )
219 answered = result.execution.status is ResultStatus.PASSED and isinstance(
220 result.response, dict
221 )
222 summary = result.execution.summary
223 rejected = self.judge(call, result, request_ref) if self.judge is not None else None
224 if rejected is not None:
225 # The agent contract discarded the answer: no valid answer, as a protocol error.
226 answered, summary = False, rejected
227 return ReviewerAnswer(
228 "ANSWERED" if answered else "ERROR",
229 result.response if answered else None,
230 summary,
231 call.provider,
232 model=result.execution.invocation.model,
233 tokens=usage_tokens(result),
234 invocation_id=result.execution.invocation.invocation_id,
235 evidence_refs=refs,
236 )
238 def _guarded(
239 self, snapshot: WorkspaceSnapshot, answers: list[ReviewerAnswer]
240 ) -> list[ReviewerAnswer]:
241 """When a read-only call changed the workspace: restore it, report it and discard the
242 batch's answers."""
243 diff = changes_since(self.workspace, snapshot)
244 if not diff.changes: 244 ↛ 246line 244 didn't jump to line 246 because the condition on line 244 was always true
245 return answers
246 restored, unrestorable = restore_changes(self.workspace, snapshot_contents(snapshot), diff)
247 if self.on_violation is not None:
248 self.on_violation(diff, len(restored), len(unrestorable))
249 return [
250 ReviewerAnswer(
251 "ERROR",
252 None,
253 f"a read-only review call changed {len(diff.changes)} path(s); the "
254 "batch's answers were discarded",
255 item.provider,
256 model=item.model,
257 tokens=item.tokens,
258 invocation_id=item.invocation_id,
259 evidence_refs=item.evidence_refs,
260 )
261 for item in answers
262 ]
265__all__ = ["BuiltProvider", "CallingProvider", "InvokerHooks", "ProviderInvoker", "usage_tokens"]