@buildanagent/harness 0.0.0-bootstrap.0 → 0.1.0-alpha.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (364) hide show
  1. package/LICENSE +54 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +717 -0
  5. package/dist/ablation.d.ts +2 -0
  6. package/dist/ablation.js +3 -0
  7. package/dist/ablation.js.map +1 -0
  8. package/dist/completion/check.d.ts +64 -0
  9. package/dist/completion/check.js +152 -0
  10. package/dist/completion/check.js.map +1 -0
  11. package/dist/completion/checks.d.ts +45 -0
  12. package/dist/completion/checks.js +173 -0
  13. package/dist/completion/checks.js.map +1 -0
  14. package/dist/completion/flags.d.ts +25 -0
  15. package/dist/completion/flags.js +87 -0
  16. package/dist/completion/flags.js.map +1 -0
  17. package/dist/completion/index.d.ts +8 -0
  18. package/dist/completion/index.js +9 -0
  19. package/dist/completion/index.js.map +1 -0
  20. package/dist/completion/snapshot.d.ts +33 -0
  21. package/dist/completion/snapshot.js +83 -0
  22. package/dist/completion/snapshot.js.map +1 -0
  23. package/dist/context/cap.d.ts +32 -0
  24. package/dist/context/cap.js +50 -0
  25. package/dist/context/cap.js.map +1 -0
  26. package/dist/context/estimate.d.ts +18 -0
  27. package/dist/context/estimate.js +20 -0
  28. package/dist/context/estimate.js.map +1 -0
  29. package/dist/context/file-spill.d.ts +5 -0
  30. package/dist/context/file-spill.js +25 -0
  31. package/dist/context/file-spill.js.map +1 -0
  32. package/dist/context/index.d.ts +10 -0
  33. package/dist/context/index.js +10 -0
  34. package/dist/context/index.js.map +1 -0
  35. package/dist/context/mask.d.ts +27 -0
  36. package/dist/context/mask.js +71 -0
  37. package/dist/context/mask.js.map +1 -0
  38. package/dist/context/mid-turn.d.ts +40 -0
  39. package/dist/context/mid-turn.js +82 -0
  40. package/dist/context/mid-turn.js.map +1 -0
  41. package/dist/context/policy.d.ts +9 -0
  42. package/dist/context/policy.js +140 -0
  43. package/dist/context/policy.js.map +1 -0
  44. package/dist/context/spill-ledger.d.ts +25 -0
  45. package/dist/context/spill-ledger.js +54 -0
  46. package/dist/context/spill-ledger.js.map +1 -0
  47. package/dist/context/spill.d.ts +6 -0
  48. package/dist/context/spill.js +14 -0
  49. package/dist/context/spill.js.map +1 -0
  50. package/dist/context/summarize.d.ts +53 -0
  51. package/dist/context/summarize.js +204 -0
  52. package/dist/context/summarize.js.map +1 -0
  53. package/dist/context/summary-template.d.ts +29 -0
  54. package/dist/context/summary-template.js +69 -0
  55. package/dist/context/summary-template.js.map +1 -0
  56. package/dist/context/types.d.ts +150 -0
  57. package/dist/context/types.js +2 -0
  58. package/dist/context/types.js.map +1 -0
  59. package/dist/context/write-cap.d.ts +19 -0
  60. package/dist/context/write-cap.js +41 -0
  61. package/dist/context/write-cap.js.map +1 -0
  62. package/dist/create-harness.d.ts +7 -0
  63. package/dist/create-harness.js +21 -0
  64. package/dist/create-harness.js.map +1 -0
  65. package/dist/credentials/addresses.d.ts +14 -0
  66. package/dist/credentials/addresses.js +144 -0
  67. package/dist/credentials/addresses.js.map +1 -0
  68. package/dist/credentials/allowlist.d.ts +34 -0
  69. package/dist/credentials/allowlist.js +77 -0
  70. package/dist/credentials/allowlist.js.map +1 -0
  71. package/dist/credentials/egress-proxy.d.ts +70 -0
  72. package/dist/credentials/egress-proxy.js +482 -0
  73. package/dist/credentials/egress-proxy.js.map +1 -0
  74. package/dist/credentials/index.d.ts +9 -0
  75. package/dist/credentials/index.js +10 -0
  76. package/dist/credentials/index.js.map +1 -0
  77. package/dist/credentials/scrub.d.ts +16 -0
  78. package/dist/credentials/scrub.js +93 -0
  79. package/dist/credentials/scrub.js.map +1 -0
  80. package/dist/errors.d.ts +56 -0
  81. package/dist/errors.js +63 -0
  82. package/dist/errors.js.map +1 -0
  83. package/dist/extensions/compose.d.ts +27 -0
  84. package/dist/extensions/compose.js +83 -0
  85. package/dist/extensions/compose.js.map +1 -0
  86. package/dist/extensions/context-files-node.d.ts +28 -0
  87. package/dist/extensions/context-files-node.js +74 -0
  88. package/dist/extensions/context-files-node.js.map +1 -0
  89. package/dist/extensions/context-files.d.ts +68 -0
  90. package/dist/extensions/context-files.js +214 -0
  91. package/dist/extensions/context-files.js.map +1 -0
  92. package/dist/extensions/digest.d.ts +6 -0
  93. package/dist/extensions/digest.js +68 -0
  94. package/dist/extensions/digest.js.map +1 -0
  95. package/dist/extensions/index.d.ts +10 -0
  96. package/dist/extensions/index.js +10 -0
  97. package/dist/extensions/index.js.map +1 -0
  98. package/dist/extensions/load.d.ts +42 -0
  99. package/dist/extensions/load.js +211 -0
  100. package/dist/extensions/load.js.map +1 -0
  101. package/dist/extensions/lock.d.ts +8 -0
  102. package/dist/extensions/lock.js +95 -0
  103. package/dist/extensions/lock.js.map +1 -0
  104. package/dist/extensions/node.d.ts +10 -0
  105. package/dist/extensions/node.js +11 -0
  106. package/dist/extensions/node.js.map +1 -0
  107. package/dist/extensions/project-dirs.d.ts +24 -0
  108. package/dist/extensions/project-dirs.js +97 -0
  109. package/dist/extensions/project-dirs.js.map +1 -0
  110. package/dist/extensions/skills-node.d.ts +34 -0
  111. package/dist/extensions/skills-node.js +123 -0
  112. package/dist/extensions/skills-node.js.map +1 -0
  113. package/dist/extensions/skills.d.ts +51 -0
  114. package/dist/extensions/skills.js +175 -0
  115. package/dist/extensions/skills.js.map +1 -0
  116. package/dist/extensions/trust-file.d.ts +3 -0
  117. package/dist/extensions/trust-file.js +62 -0
  118. package/dist/extensions/trust-file.js.map +1 -0
  119. package/dist/extensions/trust-store-node.d.ts +10 -0
  120. package/dist/extensions/trust-store-node.js +33 -0
  121. package/dist/extensions/trust-store-node.js.map +1 -0
  122. package/dist/extensions/types.d.ts +42 -0
  123. package/dist/extensions/types.js +2 -0
  124. package/dist/extensions/types.js.map +1 -0
  125. package/dist/harness.d.ts +156 -0
  126. package/dist/harness.js +2 -0
  127. package/dist/harness.js.map +1 -0
  128. package/dist/index.d.ts +4 -0
  129. package/dist/index.js +5 -0
  130. package/dist/index.js.map +1 -0
  131. package/dist/mcp/connection.d.ts +22 -0
  132. package/dist/mcp/connection.js +267 -0
  133. package/dist/mcp/connection.js.map +1 -0
  134. package/dist/mcp/content.d.ts +27 -0
  135. package/dist/mcp/content.js +177 -0
  136. package/dist/mcp/content.js.map +1 -0
  137. package/dist/mcp/errors.d.ts +19 -0
  138. package/dist/mcp/errors.js +21 -0
  139. package/dist/mcp/errors.js.map +1 -0
  140. package/dist/mcp/index.d.ts +10 -0
  141. package/dist/mcp/index.js +10 -0
  142. package/dist/mcp/index.js.map +1 -0
  143. package/dist/mcp/manager.d.ts +7 -0
  144. package/dist/mcp/manager.js +173 -0
  145. package/dist/mcp/manager.js.map +1 -0
  146. package/dist/mcp/record.d.ts +7 -0
  147. package/dist/mcp/record.js +20 -0
  148. package/dist/mcp/record.js.map +1 -0
  149. package/dist/mcp/stdio.d.ts +39 -0
  150. package/dist/mcp/stdio.js +382 -0
  151. package/dist/mcp/stdio.js.map +1 -0
  152. package/dist/mcp/types.d.ts +172 -0
  153. package/dist/mcp/types.js +2 -0
  154. package/dist/mcp/types.js.map +1 -0
  155. package/dist/memory/index.d.ts +2 -0
  156. package/dist/memory/index.js +3 -0
  157. package/dist/memory/index.js.map +1 -0
  158. package/dist/permissions/default-rules.d.ts +7 -0
  159. package/dist/permissions/default-rules.js +42 -0
  160. package/dist/permissions/default-rules.js.map +1 -0
  161. package/dist/permissions/errors.d.ts +11 -0
  162. package/dist/permissions/errors.js +14 -0
  163. package/dist/permissions/errors.js.map +1 -0
  164. package/dist/permissions/index.d.ts +9 -0
  165. package/dist/permissions/index.js +9 -0
  166. package/dist/permissions/index.js.map +1 -0
  167. package/dist/permissions/match.d.ts +33 -0
  168. package/dist/permissions/match.js +287 -0
  169. package/dist/permissions/match.js.map +1 -0
  170. package/dist/permissions/pipeline.d.ts +9 -0
  171. package/dist/permissions/pipeline.js +235 -0
  172. package/dist/permissions/pipeline.js.map +1 -0
  173. package/dist/permissions/rules.d.ts +22 -0
  174. package/dist/permissions/rules.js +74 -0
  175. package/dist/permissions/rules.js.map +1 -0
  176. package/dist/permissions/shadow.d.ts +5 -0
  177. package/dist/permissions/shadow.js +22 -0
  178. package/dist/permissions/shadow.js.map +1 -0
  179. package/dist/permissions/types.d.ts +104 -0
  180. package/dist/permissions/types.js +2 -0
  181. package/dist/permissions/types.js.map +1 -0
  182. package/dist/sandbox/base.d.ts +35 -0
  183. package/dist/sandbox/base.js +60 -0
  184. package/dist/sandbox/base.js.map +1 -0
  185. package/dist/sandbox/docker/index.d.ts +35 -0
  186. package/dist/sandbox/docker/index.js +448 -0
  187. package/dist/sandbox/docker/index.js.map +1 -0
  188. package/dist/sandbox/errors.d.ts +16 -0
  189. package/dist/sandbox/errors.js +22 -0
  190. package/dist/sandbox/errors.js.map +1 -0
  191. package/dist/sandbox/host-files.d.ts +63 -0
  192. package/dist/sandbox/host-files.js +248 -0
  193. package/dist/sandbox/host-files.js.map +1 -0
  194. package/dist/sandbox/index.d.ts +8 -0
  195. package/dist/sandbox/index.js +8 -0
  196. package/dist/sandbox/index.js.map +1 -0
  197. package/dist/sandbox/none.d.ts +17 -0
  198. package/dist/sandbox/none.js +108 -0
  199. package/dist/sandbox/none.js.map +1 -0
  200. package/dist/sandbox/process.d.ts +61 -0
  201. package/dist/sandbox/process.js +253 -0
  202. package/dist/sandbox/process.js.map +1 -0
  203. package/dist/sandbox/spawn-env.d.ts +20 -0
  204. package/dist/sandbox/spawn-env.js +128 -0
  205. package/dist/sandbox/spawn-env.js.map +1 -0
  206. package/dist/sandbox/srt/index.d.ts +35 -0
  207. package/dist/sandbox/srt/index.js +264 -0
  208. package/dist/sandbox/srt/index.js.map +1 -0
  209. package/dist/sandbox/srt/settings.d.ts +48 -0
  210. package/dist/sandbox/srt/settings.js +31 -0
  211. package/dist/sandbox/srt/settings.js.map +1 -0
  212. package/dist/sandbox/types.d.ts +88 -0
  213. package/dist/sandbox/types.js +6 -0
  214. package/dist/sandbox/types.js.map +1 -0
  215. package/dist/server/answers.d.ts +16 -0
  216. package/dist/server/answers.js +43 -0
  217. package/dist/server/answers.js.map +1 -0
  218. package/dist/server/connection.d.ts +99 -0
  219. package/dist/server/connection.js +309 -0
  220. package/dist/server/connection.js.map +1 -0
  221. package/dist/server/dispatcher.d.ts +86 -0
  222. package/dist/server/dispatcher.js +800 -0
  223. package/dist/server/dispatcher.js.map +1 -0
  224. package/dist/server/index.d.ts +13 -0
  225. package/dist/server/index.js +12 -0
  226. package/dist/server/index.js.map +1 -0
  227. package/dist/server/local-transport.d.ts +44 -0
  228. package/dist/server/local-transport.js +103 -0
  229. package/dist/server/local-transport.js.map +1 -0
  230. package/dist/server/outbox.d.ts +31 -0
  231. package/dist/server/outbox.js +130 -0
  232. package/dist/server/outbox.js.map +1 -0
  233. package/dist/server/params.d.ts +25 -0
  234. package/dist/server/params.js +112 -0
  235. package/dist/server/params.js.map +1 -0
  236. package/dist/server/protocol.schema.json +2448 -0
  237. package/dist/server/rpc-session.d.ts +43 -0
  238. package/dist/server/rpc-session.js +167 -0
  239. package/dist/server/rpc-session.js.map +1 -0
  240. package/dist/server/stdio-streams.d.ts +67 -0
  241. package/dist/server/stdio-streams.js +218 -0
  242. package/dist/server/stdio-streams.js.map +1 -0
  243. package/dist/server/stdio.d.ts +59 -0
  244. package/dist/server/stdio.js +189 -0
  245. package/dist/server/stdio.js.map +1 -0
  246. package/dist/server/websocket.d.ts +106 -0
  247. package/dist/server/websocket.js +327 -0
  248. package/dist/server/websocket.js.map +1 -0
  249. package/dist/session/approvals.d.ts +81 -0
  250. package/dist/session/approvals.js +217 -0
  251. package/dist/session/approvals.js.map +1 -0
  252. package/dist/session/code-call-log.d.ts +42 -0
  253. package/dist/session/code-call-log.js +63 -0
  254. package/dist/session/code-call-log.js.map +1 -0
  255. package/dist/session/code-call-result.d.ts +19 -0
  256. package/dist/session/code-call-result.js +95 -0
  257. package/dist/session/code-call-result.js.map +1 -0
  258. package/dist/session/code-call.d.ts +49 -0
  259. package/dist/session/code-call.js +345 -0
  260. package/dist/session/code-call.js.map +1 -0
  261. package/dist/session/effect-scope.d.ts +11 -0
  262. package/dist/session/effect-scope.js +10 -0
  263. package/dist/session/effect-scope.js.map +1 -0
  264. package/dist/session/errors.d.ts +19 -0
  265. package/dist/session/errors.js +27 -0
  266. package/dist/session/errors.js.map +1 -0
  267. package/dist/session/file-index.d.ts +8 -0
  268. package/dist/session/file-index.js +70 -0
  269. package/dist/session/file-index.js.map +1 -0
  270. package/dist/session/file-key-store.d.ts +16 -0
  271. package/dist/session/file-key-store.js +169 -0
  272. package/dist/session/file-key-store.js.map +1 -0
  273. package/dist/session/file-lock.d.ts +52 -0
  274. package/dist/session/file-lock.js +324 -0
  275. package/dist/session/file-lock.js.map +1 -0
  276. package/dist/session/index.d.ts +22 -0
  277. package/dist/session/index.js +20 -0
  278. package/dist/session/index.js.map +1 -0
  279. package/dist/session/jsonl-store.d.ts +37 -0
  280. package/dist/session/jsonl-store.js +386 -0
  281. package/dist/session/jsonl-store.js.map +1 -0
  282. package/dist/session/jsonl.d.ts +9 -0
  283. package/dist/session/jsonl.js +10 -0
  284. package/dist/session/jsonl.js.map +1 -0
  285. package/dist/session/lock.d.ts +19 -0
  286. package/dist/session/lock.js +2 -0
  287. package/dist/session/lock.js.map +1 -0
  288. package/dist/session/memory-store.d.ts +12 -0
  289. package/dist/session/memory-store.js +60 -0
  290. package/dist/session/memory-store.js.map +1 -0
  291. package/dist/session/migrate.d.ts +41 -0
  292. package/dist/session/migrate.js +86 -0
  293. package/dist/session/migrate.js.map +1 -0
  294. package/dist/session/pointer.d.ts +15 -0
  295. package/dist/session/pointer.js +22 -0
  296. package/dist/session/pointer.js.map +1 -0
  297. package/dist/session/rebuild.d.ts +53 -0
  298. package/dist/session/rebuild.js +230 -0
  299. package/dist/session/rebuild.js.map +1 -0
  300. package/dist/session/resume.d.ts +26 -0
  301. package/dist/session/resume.js +128 -0
  302. package/dist/session/resume.js.map +1 -0
  303. package/dist/session/retention.d.ts +97 -0
  304. package/dist/session/retention.js +702 -0
  305. package/dist/session/retention.js.map +1 -0
  306. package/dist/session/runner.d.ts +156 -0
  307. package/dist/session/runner.js +656 -0
  308. package/dist/session/runner.js.map +1 -0
  309. package/dist/session/scheduler.d.ts +47 -0
  310. package/dist/session/scheduler.js +85 -0
  311. package/dist/session/scheduler.js.map +1 -0
  312. package/dist/session/secret-key-store.d.ts +47 -0
  313. package/dist/session/secret-key-store.js +79 -0
  314. package/dist/session/secret-key-store.js.map +1 -0
  315. package/dist/session/session.d.ts +106 -0
  316. package/dist/session/session.js +353 -0
  317. package/dist/session/session.js.map +1 -0
  318. package/dist/session/sticky.d.ts +48 -0
  319. package/dist/session/sticky.js +232 -0
  320. package/dist/session/sticky.js.map +1 -0
  321. package/dist/session/store.d.ts +108 -0
  322. package/dist/session/store.js +163 -0
  323. package/dist/session/store.js.map +1 -0
  324. package/dist/telemetry/index.d.ts +2 -0
  325. package/dist/telemetry/index.js +3 -0
  326. package/dist/telemetry/index.js.map +1 -0
  327. package/dist/testing/fake-sandbox.d.ts +34 -0
  328. package/dist/testing/fake-sandbox.js +221 -0
  329. package/dist/testing/fake-sandbox.js.map +1 -0
  330. package/dist/testing/index.d.ts +10 -0
  331. package/dist/testing/index.js +11 -0
  332. package/dist/testing/index.js.map +1 -0
  333. package/dist/testing/key-store-conformance.d.ts +22 -0
  334. package/dist/testing/key-store-conformance.js +97 -0
  335. package/dist/testing/key-store-conformance.js.map +1 -0
  336. package/dist/testing/run-cases.d.ts +21 -0
  337. package/dist/testing/run-cases.js +20 -0
  338. package/dist/testing/run-cases.js.map +1 -0
  339. package/dist/testing/sandbox-conformance.d.ts +64 -0
  340. package/dist/testing/sandbox-conformance.js +361 -0
  341. package/dist/testing/sandbox-conformance.js.map +1 -0
  342. package/dist/testing/scheduler-conformance.d.ts +32 -0
  343. package/dist/testing/scheduler-conformance.js +72 -0
  344. package/dist/testing/scheduler-conformance.js.map +1 -0
  345. package/dist/testing/store-conformance.d.ts +21 -0
  346. package/dist/testing/store-conformance.js +320 -0
  347. package/dist/testing/store-conformance.js.map +1 -0
  348. package/dist/tools/errors.d.ts +13 -0
  349. package/dist/tools/errors.js +17 -0
  350. package/dist/tools/errors.js.map +1 -0
  351. package/dist/tools/index.d.ts +8 -0
  352. package/dist/tools/index.js +8 -0
  353. package/dist/tools/index.js.map +1 -0
  354. package/dist/tools/registry.d.ts +3 -0
  355. package/dist/tools/registry.js +234 -0
  356. package/dist/tools/registry.js.map +1 -0
  357. package/dist/tools/tool-search.d.ts +30 -0
  358. package/dist/tools/tool-search.js +118 -0
  359. package/dist/tools/tool-search.js.map +1 -0
  360. package/dist/tools/types.d.ts +106 -0
  361. package/dist/tools/types.js +2 -0
  362. package/dist/tools/types.js.map +1 -0
  363. package/llms.txt +435 -0
  364. package/package.json +119 -5
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Checks a command against the protocol schema before the dispatcher runs it. `protocol.schema.json` is a copy of the
3
+ * protocol package's generated schema, which ships no JSON of its own; a test fails while the two differ. The schema is
4
+ * one `anyOf` over every message, whose groups hold one branch per message kind. A command's branch is the one that
5
+ * requires an `id` and whose `method` is a `const` or an `enum` naming client methods: each command method must have
6
+ * exactly one, or building the index throws. Only the branch's `params` schema is checked, compiled with the schema's
7
+ * shared `$defs` the first time a command of its method arrives, and kept: `decode()` has already checked the envelope.
8
+ */
9
+ import { CLIENT_METHODS } from "@buildanagent/protocol";
10
+ import { compile } from "@earendil-works/pi-schema";
11
+ import schema from "./protocol.schema.json" with { type: "json" };
12
+ /**
13
+ * The keywords whose error path ends in a key the client chose, not one the schema declares. Their answer names the
14
+ * object that holds the key instead.
15
+ */
16
+ const KEY_KEYWORDS = new Set(["additionalProperties", "propertyNames", "unevaluatedProperties"]);
17
+ const clientMethods = new Set(CLIENT_METHODS);
18
+ const root = schema;
19
+ let branches;
20
+ let declared;
21
+ const validators = new Map();
22
+ const methodsOf = (branch) => {
23
+ const method = branch.properties?.method;
24
+ if (method === undefined)
25
+ return [];
26
+ if (method.const !== undefined)
27
+ return [method.const];
28
+ return method.enum ?? [];
29
+ };
30
+ /** Maps each command method to its branch, reading the top-level `anyOf` and the groups one level down. */
31
+ function indexBranches() {
32
+ const index = new Map();
33
+ for (const branch of root.anyOf.flatMap((group) => group.anyOf ?? [group])) {
34
+ if (!branch.required?.includes("id"))
35
+ continue;
36
+ for (const method of methodsOf(branch)) {
37
+ if (typeof method !== "string" || !clientMethods.has(method))
38
+ continue;
39
+ if (index.has(method))
40
+ throw new Error(`the protocol schema has two branches for the command ${method}`);
41
+ index.set(method, branch);
42
+ }
43
+ }
44
+ return index;
45
+ }
46
+ function validatorFor(method) {
47
+ const cached = validators.get(method);
48
+ if (cached !== undefined)
49
+ return cached;
50
+ branches ??= indexBranches();
51
+ const branch = branches.get(method);
52
+ if (branch === undefined)
53
+ return undefined;
54
+ // A branch without a params schema takes any params, as an empty schema does.
55
+ const validator = compile({ ...branch.properties?.params, $defs: root.$defs }, { draft: "2020-12" });
56
+ validators.set(method, validator);
57
+ return validator;
58
+ }
59
+ /** The command methods the protocol schema has a branch for, so a test can check that none is missing. */
60
+ export function checkedMethods() {
61
+ branches ??= indexBranches();
62
+ return [...branches.keys()];
63
+ }
64
+ /** Every property name the schema declares anywhere, the only words an error path may carry. */
65
+ function declaredNames() {
66
+ const names = new Set();
67
+ // The replacer visits every member of the schema, however deep, which is all the walk needs.
68
+ JSON.stringify(schema, (key, value) => {
69
+ if (key === "properties" && typeof value === "object" && value !== null && !Array.isArray(value)) {
70
+ for (const name of Object.keys(value))
71
+ names.add(name);
72
+ }
73
+ return value;
74
+ });
75
+ return names;
76
+ }
77
+ /**
78
+ * The part of an error's path that names only what the schema declares: array indices and declared property names. A
79
+ * key the client chose, and everything below it, is left out, so the answer never echoes it.
80
+ */
81
+ function safePath(path, keyword) {
82
+ declared ??= declaredNames();
83
+ const segments = path.split("/").slice(1);
84
+ if (KEY_KEYWORDS.has(keyword))
85
+ segments.pop();
86
+ const kept = [];
87
+ for (const segment of segments) {
88
+ if (!/^(0|[1-9][0-9]{0,8})$/.test(segment) && !declared.has(segment))
89
+ break;
90
+ kept.push(segment);
91
+ }
92
+ return ["/params", ...kept].join("/");
93
+ }
94
+ /**
95
+ * Why a command's params break its schema branch, or `undefined` when they fit or its method has no branch, which the
96
+ * dispatcher answers with `MethodNotFound`. JSON-RPC lets a command leave out `params`, which is checked as `{}`, so a
97
+ * method whose params are all optional takes it and one with a required field refuses it. The reason names the first
98
+ * error's keyword and the path to it, cut at the first key the schema does not declare, never a key or a value the
99
+ * client sent.
100
+ */
101
+ export function paramsProblem(command) {
102
+ const { method } = command;
103
+ const validator = validatorFor(method);
104
+ const params = command.params === undefined ? {} : command.params;
105
+ if (validator === undefined || validator.check(params))
106
+ return undefined;
107
+ const [first] = validator.errors(params);
108
+ if (first === undefined)
109
+ return `the params of ${method} do not match the protocol schema`;
110
+ return `the params of ${method} do not match the protocol schema: ${safePath(first.path, first.keyword)} fails ${first.keyword}`;
111
+ }
112
+ //# sourceMappingURL=params.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"params.js","sourceRoot":"","sources":["../../src/server/params.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAsB,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAmC,MAAM,2BAA2B,CAAC;AACrF,OAAO,MAAM,MAAM,wBAAwB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAclE;;;GAGG;AACH,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,sBAAsB,EAAE,eAAe,EAAE,uBAAuB,CAAC,CAAC,CAAC;AAEtH,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;AACnE,MAAM,IAAI,GAAG,MAAmG,CAAC;AAEjH,IAAI,QAAiD,CAAC;AACtD,IAAI,QAAyC,CAAC;AAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAA8B,CAAC;AAEzD,MAAM,SAAS,GAAG,CAAC,MAAc,EAAsB,EAAE;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;AAC3B,CAAC,CAAC;AAEF,2GAA2G;AAC3G,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/C,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YACvE,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,MAAM,EAAE,CAAC,CAAC;YACzG,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,QAAQ,KAAK,aAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,8EAA8E;IAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACnH,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,cAAc;IAC5B,QAAQ,KAAK,aAAa,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,gGAAgG;AAChG,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,6FAA6F;IAC7F,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAc,EAAE,EAAE;QAC7C,IAAI,GAAG,KAAK,YAAY,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjG,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAe;IAC7C,QAAQ,KAAK,aAAa,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1C,IAAI,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,MAAM;QAC5E,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAG7B;IACC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAClE,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,MAAM,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,iBAAiB,MAAM,mCAAmC,CAAC;IAC3F,OAAO,iBAAiB,MAAM,sCAAsC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC;AACnI,CAAC","sourcesContent":["/**\n * Checks a command against the protocol schema before the dispatcher runs it. `protocol.schema.json` is a copy of the\n * protocol package's generated schema, which ships no JSON of its own; a test fails while the two differ. The schema is\n * one `anyOf` over every message, whose groups hold one branch per message kind. A command's branch is the one that\n * requires an `id` and whose `method` is a `const` or an `enum` naming client methods: each command method must have\n * exactly one, or building the index throws. Only the branch's `params` schema is checked, compiled with the schema's\n * shared `$defs` the first time a command of its method arrives, and kept: `decode()` has already checked the envelope.\n */\nimport { CLIENT_METHODS, type ClientCommand } from \"@buildanagent/protocol\";\nimport { compile, type JsonSchema, type Validator } from \"@earendil-works/pi-schema\";\nimport schema from \"./protocol.schema.json\" with { type: \"json\" };\n\n/** A command method, as the client sends it with an `id`. */\ntype CommandMethod = ClientCommand[\"method\"];\n\ninterface Branch {\n readonly required?: readonly string[];\n readonly properties?: {\n readonly method?: { readonly const?: unknown; readonly enum?: readonly unknown[] };\n readonly params?: Record<string, unknown>;\n };\n readonly anyOf?: readonly Branch[];\n}\n\n/**\n * The keywords whose error path ends in a key the client chose, not one the schema declares. Their answer names the\n * object that holds the key instead.\n */\nconst KEY_KEYWORDS: ReadonlySet<string> = new Set([\"additionalProperties\", \"propertyNames\", \"unevaluatedProperties\"]);\n\nconst clientMethods: ReadonlySet<string> = new Set(CLIENT_METHODS);\nconst root = schema as unknown as { readonly anyOf: readonly Branch[]; readonly $defs: Record<string, unknown> };\n\nlet branches: ReadonlyMap<string, Branch> | undefined;\nlet declared: ReadonlySet<string> | undefined;\nconst validators = new Map<string, Validator<unknown>>();\n\nconst methodsOf = (branch: Branch): readonly unknown[] => {\n const method = branch.properties?.method;\n if (method === undefined) return [];\n if (method.const !== undefined) return [method.const];\n return method.enum ?? [];\n};\n\n/** Maps each command method to its branch, reading the top-level `anyOf` and the groups one level down. */\nfunction indexBranches(): ReadonlyMap<string, Branch> {\n const index = new Map<string, Branch>();\n for (const branch of root.anyOf.flatMap((group) => group.anyOf ?? [group])) {\n if (!branch.required?.includes(\"id\")) continue;\n for (const method of methodsOf(branch)) {\n if (typeof method !== \"string\" || !clientMethods.has(method)) continue;\n if (index.has(method)) throw new Error(`the protocol schema has two branches for the command ${method}`);\n index.set(method, branch);\n }\n }\n return index;\n}\n\nfunction validatorFor(method: string): Validator<unknown> | undefined {\n const cached = validators.get(method);\n if (cached !== undefined) return cached;\n branches ??= indexBranches();\n const branch = branches.get(method);\n if (branch === undefined) return undefined;\n // A branch without a params schema takes any params, as an empty schema does.\n const validator = compile({ ...branch.properties?.params, $defs: root.$defs } as JsonSchema, { draft: \"2020-12\" });\n validators.set(method, validator);\n return validator;\n}\n\n/** The command methods the protocol schema has a branch for, so a test can check that none is missing. */\nexport function checkedMethods(): readonly string[] {\n branches ??= indexBranches();\n return [...branches.keys()];\n}\n\n/** Every property name the schema declares anywhere, the only words an error path may carry. */\nfunction declaredNames(): ReadonlySet<string> {\n const names = new Set<string>();\n // The replacer visits every member of the schema, however deep, which is all the walk needs.\n JSON.stringify(schema, (key, value: unknown) => {\n if (key === \"properties\" && typeof value === \"object\" && value !== null && !Array.isArray(value)) {\n for (const name of Object.keys(value)) names.add(name);\n }\n return value;\n });\n return names;\n}\n\n/**\n * The part of an error's path that names only what the schema declares: array indices and declared property names. A\n * key the client chose, and everything below it, is left out, so the answer never echoes it.\n */\nfunction safePath(path: string, keyword: string): string {\n declared ??= declaredNames();\n const segments = path.split(\"/\").slice(1);\n if (KEY_KEYWORDS.has(keyword)) segments.pop();\n const kept: string[] = [];\n for (const segment of segments) {\n if (!/^(0|[1-9][0-9]{0,8})$/.test(segment) && !declared.has(segment)) break;\n kept.push(segment);\n }\n return [\"/params\", ...kept].join(\"/\");\n}\n\n/**\n * Why a command's params break its schema branch, or `undefined` when they fit or its method has no branch, which the\n * dispatcher answers with `MethodNotFound`. JSON-RPC lets a command leave out `params`, which is checked as `{}`, so a\n * method whose params are all optional takes it and one with a required field refuses it. The reason names the first\n * error's keyword and the path to it, cut at the first key the schema does not declare, never a key or a value the\n * client sent.\n */\nexport function paramsProblem(command: {\n readonly method: CommandMethod | string;\n readonly params?: unknown;\n}): string | undefined {\n const { method } = command;\n const validator = validatorFor(method);\n const params = command.params === undefined ? {} : command.params;\n if (validator === undefined || validator.check(params)) return undefined;\n const [first] = validator.errors(params);\n if (first === undefined) return `the params of ${method} do not match the protocol schema`;\n return `the params of ${method} do not match the protocol schema: ${safePath(first.path, first.keyword)} fails ${first.keyword}`;\n}\n"]}