Coverage for src/governed_harness/agents/script_contracts.py: 100%

63 statements  

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

1"""Scripts as black boxes (wave 11, #97): the contract of every command an agent may call. 

2 

3A script that the harness lets an agent call has a contract: how to invoke it, the inputs it 

4takes, the outputs it produces and the errors it can return. The agent is told to use only that 

5contract: it does not read the script's source, it does not spend tokens working out how it 

6works, and it uses the answer it gets. The registry covers the commands of the harness an agent 

7runs (``harness check``), the validator commands of the gate and the tools of the embedded MCP 

8server. Pure: it reads nothing and runs nothing.""" 

9 

10from __future__ import annotations 

11 

12from collections.abc import Iterable, Mapping, Sequence 

13from typing import Any, Final, Literal 

14 

15from pydantic import BaseModel, ConfigDict, Field 

16from pydantic.alias_generators import to_camel 

17 

18SCRIPT_CONTRACT_VERSION: Final = "1.0" 

19ScriptKind = Literal["harness-command", "validator", "mcp-tool"] 

20ValueType = Literal["string", "integer", "boolean", "path", "array", "object"] 

21 

22BLACK_BOX_NOTICE: Final = ( 

23 "Scripts and commands are black boxes: use only the contract listed in " 

24 "scriptContracts (invocation, inputs, outputs, errors). Do not read their source " 

25 "code, do not work out how they work inside, run them and use only the answer they give." 

26) 

27"""The sentence added to the instructions of an implement call under ``agentContract``.""" 

28 

29 

30class _Contract(BaseModel): 

31 model_config = ConfigDict( 

32 extra="forbid", populate_by_name=True, frozen=True, alias_generator=to_camel 

33 ) 

34 

35 

36class ScriptInput(_Contract): 

37 name: str = Field(min_length=1) 

38 value_type: ValueType 

39 required: bool 

40 description: str 

41 

42 

43class ScriptOutput(_Contract): 

44 name: str = Field(min_length=1) 

45 channel: Literal["stdout", "exit-code", "file", "result"] 

46 format: str 

47 description: str 

48 

49 

50class ScriptError(_Contract): 

51 code: str = Field(min_length=1) 

52 """An exit code or an error name.""" 

53 meaning: str 

54 agent_action: str 

55 

56 

57class ScriptContract(_Contract): 

58 """The contract of one script (schema ``script-contract.schema.json``).""" 

59 

60 contract_version: Literal["1.0"] = SCRIPT_CONTRACT_VERSION 

61 script_id: str = Field(min_length=1) 

62 kind: ScriptKind 

63 summary: str 

64 invocation: tuple[str, ...] = Field(min_length=1) 

65 """The argv (or, for an MCP tool, its name); ``<name>`` marks an input to fill in.""" 

66 inputs: tuple[ScriptInput, ...] = () 

67 outputs: tuple[ScriptOutput, ...] = Field(min_length=1) 

68 errors: tuple[ScriptError, ...] = Field(min_length=1) 

69 source_is_opaque: Literal[True] = True 

70 """The agent does not read the source of the script.""" 

71 

72 

73_CHECK_FAILED = "6" 

74_STDOUT_JSON = "json" 

75_CHECK = ScriptContract( 

76 script_id="harness.check", 

77 kind="harness-command", 

78 summary="Run the validators of the gate and the enabled diff checks on the workspace; " 

79 "nothing is recorded.", 

80 invocation=("harness", "check", "--path", "<workspace>", "--run", "<run id>"), 

81 inputs=( 

82 ScriptInput( 

83 name="--path", 

84 value_type="path", 

85 required=False, 

86 description="Project directory (default: the current directory).", 

87 ), 

88 ScriptInput( 

89 name="--run", 

90 value_type="string", 

91 required=False, 

92 description="Run whose task and baseline the diff checks use.", 

93 ), 

94 ), 

95 outputs=( 

96 ScriptOutput( 

97 name="report", 

98 channel="stdout", 

99 format=_STDOUT_JSON, 

100 description="status, validators[] (id, mandatory, status, summary, problems), " 

101 "checks[] (id, policy, issues) and blockingIssues.", 

102 ), 

103 ScriptOutput( 

104 name="status", 

105 channel="exit-code", 

106 format="integer", 

107 description="0 when every mandatory validator passes and no enforced check " 

108 "reports a blocking problem.", 

109 ), 

110 ), 

111 errors=( 

112 ScriptError( 

113 code=_CHECK_FAILED, 

114 meaning="A mandatory validator failed or an enforced check found a blocking problem.", 

115 agent_action="Fix what report.validators[].problems and report.checks[].issues " 

116 "list, then run it again.", 

117 ), 

118 ScriptError( 

119 code="2", 

120 meaning="No valid project configuration in the directory.", 

121 agent_action="Stop and report it: the configuration is a person's to fix.", 

122 ), 

123 ScriptError( 

124 code="3", 

125 meaning="The run named by --run has no check state.", 

126 agent_action="Run it without --run.", 

127 ), 

128 ), 

129) 

130 

131_EXIT_ZERO = "0" 

132 

133 

134def _validator_contract(definition: Any) -> ScriptContract: 

135 command = tuple(definition.command or ()) 

136 label = "mandatory" if definition.mandatory else "advisory" 

137 return ScriptContract( 

138 script_id=f"validator.{definition.validator_id}", 

139 kind="validator", 

140 summary=f"The {label} validator {definition.validator_id} of the gate.", 

141 invocation=command or ("<no command>",), 

142 inputs=( 

143 ScriptInput( 

144 name="cwd", 

145 value_type="path", 

146 required=True, 

147 description="The workspace root; the command takes no other input.", 

148 ), 

149 ), 

150 outputs=( 

151 ScriptOutput( 

152 name="status", 

153 channel="exit-code", 

154 format="integer", 

155 description=f"{_EXIT_ZERO} when the validator passes.", 

156 ), 

157 ScriptOutput( 

158 name="output", 

159 channel="stdout", 

160 format="text", 

161 description="What the tool printed; located problems are parsed from it.", 

162 ), 

163 ), 

164 errors=( 

165 ScriptError( 

166 code="non-zero", 

167 meaning="The validator found a problem or could not run.", 

168 agent_action="Read the problems in its output and fix the cause; do not edit " 

169 "the validator or weaken its configuration.", 

170 ), 

171 ), 

172 ) 

173 

174 

175def _tool_contract(tool: Mapping[str, Any]) -> ScriptContract: 

176 schema = tool.get("inputSchema") or {} 

177 properties: Mapping[str, Any] = schema.get("properties") or {} 

178 required = set(schema.get("required") or ()) 

179 inputs = tuple( 

180 ScriptInput( 

181 name=str(name), 

182 value_type=_value_type(spec), 

183 required=name in required, 

184 description=str(spec.get("description") or spec.get("type") or ""), 

185 ) 

186 for name, spec in properties.items() 

187 ) 

188 return ScriptContract( 

189 script_id=f"mcp.{tool['name']}", 

190 kind="mcp-tool", 

191 summary=str(tool.get("description", "")), 

192 invocation=(str(tool["name"]),), 

193 inputs=inputs, 

194 outputs=( 

195 ScriptOutput( 

196 name="content", 

197 channel="result", 

198 format=_STDOUT_JSON, 

199 description="The text content of the MCP tool result.", 

200 ), 

201 ), 

202 errors=( 

203 ScriptError( 

204 code="isError", 

205 meaning="The tool result carries isError true with the reason as text.", 

206 agent_action="Read the reason and change the arguments; do not retry unchanged.", 

207 ), 

208 ), 

209 ) 

210 

211 

212_VALUE_TYPES: Final[dict[str, ValueType]] = { 

213 "string": "string", 

214 "integer": "integer", 

215 "boolean": "boolean", 

216 "array": "array", 

217 "object": "object", 

218} 

219 

220 

221def _value_type(spec: Mapping[str, Any]) -> ValueType: 

222 return _VALUE_TYPES.get(str(spec.get("type")), "string") 

223 

224 

225def registry( 

226 validators: Iterable[Any] = (), tools: Sequence[Mapping[str, Any]] = () 

227) -> dict[str, ScriptContract]: 

228 """Every contract an agent may use: ``harness check``, the gate's validator commands and 

229 the tools of the embedded MCP server, by script id.""" 

230 contracts = [_CHECK] 

231 contracts.extend(_validator_contract(item) for item in validators if item.command) 

232 contracts.extend(_tool_contract(item) for item in tools) 

233 return {item.script_id: item for item in contracts} 

234 

235 

236def brief(contract: ScriptContract) -> dict[str, Any]: 

237 """The contract as a request carries it: enough to call the script and read its answer.""" 

238 return { 

239 "id": contract.script_id, 

240 "invocation": list(contract.invocation), 

241 "inputs": [item.name for item in contract.inputs if item.required], 

242 "errors": {item.code: item.agent_action for item in contract.errors}, 

243 }