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

1"""How the panel reaches the providers: parallel, read-only, isolated (#57). 

2 

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: 

6 

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.""" 

16 

17from __future__ import annotations 

18 

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 

25 

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 

39 

40 

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.""" 

46 

47 

48@dataclass(frozen=True) 

49class BuiltProvider: 

50 provider: CallingProvider 

51 actor: Actor 

52 refs: tuple[str, ...] = () 

53 

54 

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 

62 

63 

64def _never_cancelled() -> bool: 

65 return False 

66 

67 

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``.""" 

76 

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 

83 

84 

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] = {} 

123 

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] 

128 

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 

146 

147 def run(index: int) -> AgentCallResult | str: 

148 return self._call(calls[index], built[index], grants[index]) 

149 

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 

164 

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}" 

193 

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}} 

203 

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 ) 

237 

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 ] 

263 

264 

265__all__ = ["BuiltProvider", "CallingProvider", "InvokerHooks", "ProviderInvoker", "usage_tokens"]