@buildanagent/harness 0.0.0-stage → 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 +716 -2
  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 +118 -3
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Finding the skills a project holds. They are the folders under `.agents/skills` that hold a `SKILL.md`, in the
3
+ * working directory and in every folder above it up to the repository root. Node-only.
4
+ */
5
+ import { readdir } from "node:fs/promises";
6
+ import { join, sep } from "node:path";
7
+ import { sha256 } from "./compose.js";
8
+ import { attribute } from "./context-files.js";
9
+ import { projectTrusted } from "./load.js";
10
+ import { projectDirs, readProjectFile } from "./project-dirs.js";
11
+ import { parseSkill } from "./skills.js";
12
+ const MAX_DEPTH = 4;
13
+ /** The longest `SKILL.md` listed, our own limit. A longer one is skipped with a notice, so a record's hash covers the whole file. */
14
+ const SKILL_FILE_MAX_BYTES = 256 * 1024;
15
+ /**
16
+ * Why a folder's name is not walked, or `undefined` when it may be. A control character would put a line of the
17
+ * project's choosing into the system prompt, which lists each skill's path. On POSIX a `\` is an ordinary character in
18
+ * a name, but a model or a tool that reads the path as Windows does takes it for a separator, so a folder named
19
+ * `a\..\..\etc` would give a skill a path that seems to name a file outside its folder.
20
+ */
21
+ function badName(name) {
22
+ if (/\p{Cc}/u.test(name))
23
+ return "it holds a control character";
24
+ if (sep === "/" && name.includes("\\"))
25
+ return "it holds a \\, which a path on Windows reads as a separator";
26
+ return undefined;
27
+ }
28
+ /**
29
+ * The `SKILL.md` files under `dir`, found by walking down at most `MAX_DEPTH` levels, with a notice in `notices` for
30
+ * each folder whose name is not walked. Links are not followed.
31
+ */
32
+ async function skillFiles(dir, notices, depth = 0) {
33
+ let entries;
34
+ try {
35
+ entries = await readdir(dir, { withFileTypes: true });
36
+ }
37
+ catch {
38
+ return [];
39
+ }
40
+ entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
41
+ const found = [];
42
+ if (entries.some((entry) => entry.name === "SKILL.md" && (entry.isFile() || entry.isSymbolicLink())))
43
+ found.push(join(dir, "SKILL.md"));
44
+ // A skill's own folder holds its references and scripts, and none of them is another skill.
45
+ if (found.length > 0 || depth >= MAX_DEPTH)
46
+ return found;
47
+ for (const entry of entries) {
48
+ if (!entry.isDirectory() || entry.name === "node_modules")
49
+ continue;
50
+ const reason = badName(entry.name);
51
+ if (reason === undefined)
52
+ found.push(...(await skillFiles(join(dir, entry.name), notices, depth + 1)));
53
+ else
54
+ notices.push(`${attribute(join(dir, entry.name))} is skipped: ${reason}`);
55
+ }
56
+ return found;
57
+ }
58
+ /** Why the project's skills are not listed, or `undefined` when they may be. */
59
+ async function skipReason(root, options) {
60
+ if (options.headless === true && options.loadInHeadless !== true) {
61
+ return `the project skills of ${root} are skipped: this run is headless`;
62
+ }
63
+ if (!(await projectTrusted(options.trust, root))) {
64
+ return `the project skills of ${root} are skipped: the project is not trusted`;
65
+ }
66
+ return undefined;
67
+ }
68
+ /** One `SKILL.md` read and checked: the skill with its record, a notice saying why it is skipped, or nothing when it is gone. */
69
+ async function loadSkill(root, file, taken) {
70
+ const read = await readProjectFile(root, file, SKILL_FILE_MAX_BYTES);
71
+ if (read === undefined)
72
+ return {};
73
+ if ("notice" in read)
74
+ return read;
75
+ // The record's hash must cover the whole file, and a cut file's hash would not.
76
+ if (read.truncated)
77
+ return { notice: `${file} is longer than ${SKILL_FILE_MAX_BYTES} bytes, so it is not listed` };
78
+ // The path the model reads is the one found, not a link's target.
79
+ const parsed = parseSkill(read.text, file);
80
+ if ("problem" in parsed)
81
+ return { notice: `${parsed.problem}, so it is not listed` };
82
+ if (taken.has(parsed.skill.name)) {
83
+ return { notice: `${file} is skipped: a nearer skill is already named "${parsed.skill.name}"` };
84
+ }
85
+ const record = { name: parsed.skill.name, tier: "skill", contentHash: await sha256(read.bytes) };
86
+ return { skill: parsed.skill, record, ...(parsed.notice === undefined ? {} : { warning: parsed.notice }) };
87
+ }
88
+ /**
89
+ * Finds the skills of the project `cwd` is in: each folder under `.agents/skills` holding a `SKILL.md`, in `cwd` and
90
+ * every folder above it up to the repository root (the first folder with a `.git`). A `cwd` in no repository searches
91
+ * only itself. A file that is not a skill, a `SKILL.md` that is a link leaving the project, a name already taken by
92
+ * a nearer skill, and a folder whose name holds a control character, or a `\` on POSIX, are skipped with a notice, and
93
+ * the rest still load. The skills' paths are absolute. No skill file is read
94
+ * until the trust store and `headless` allow it: an untrusted project, or a headless run without `loadInHeadless`,
95
+ * lists no skills and returns one notice saying why.
96
+ */
97
+ export async function discoverSkills(cwd, options) {
98
+ const dirs = await projectDirs(cwd);
99
+ const root = dirs.at(-1);
100
+ const result = { skills: [], records: [], notices: [] };
101
+ const reason = await skipReason(root, options);
102
+ if (reason !== undefined) {
103
+ result.notices.push(reason);
104
+ return result;
105
+ }
106
+ const names = new Set();
107
+ for (const dir of dirs) {
108
+ for (const file of await skillFiles(join(dir, ".agents", "skills"), result.notices)) {
109
+ const found = await loadSkill(root, file, names);
110
+ if ("notice" in found)
111
+ result.notices.push(found.notice);
112
+ if (!("skill" in found))
113
+ continue;
114
+ if (found.warning !== undefined)
115
+ result.notices.push(found.warning);
116
+ names.add(found.skill.name);
117
+ result.skills.push(found.skill);
118
+ result.records.push(found.record);
119
+ }
120
+ }
121
+ return result;
122
+ }
123
+ //# sourceMappingURL=skills-node.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills-node.js","sourceRoot":"","sources":["../../src/extensions/skills-node.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Finding the skills a project holds. They are the folders under `.agents/skills` that hold a `SKILL.md`, in the\n * working directory and in every folder above it up to the repository root. Node-only.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, sep } from \"node:path\";\nimport { sha256 } from \"./compose.js\";\nimport { attribute } from \"./context-files.js\";\nimport { projectTrusted } from \"./load.js\";\nimport { projectDirs, readProjectFile } from \"./project-dirs.js\";\nimport { parseSkill, type Skill } from \"./skills.js\";\nimport type { ExtensionLoadedRecord, TrustStore } from \"./types.js\";\n\n/** The settings of `discoverSkills()`. */\nexport interface DiscoverSkillsOptions {\n /**\n * The project-trust gate, required as it is for extensions: a project's skills are listed only when the store trusts\n * the project and the run is not headless. A skill's name and description go into the system prompt, so an untrusted\n * checkout must not reach it. A host that trusts every project it opens says so with a store that trusts them.\n */\n readonly trust: TrustStore;\n /** True for a run nobody can answer: project skills are skipped unless `loadInHeadless` is set. Default false. */\n readonly headless?: boolean;\n /** Lets a headless run list a trusted project's skills. Default false. */\n readonly loadInHeadless?: boolean;\n}\n\n/** The skills found, what to record about them, and why any were left out. */\nexport interface DiscoveredSkills {\n /** Nearest folder first, then by path. A name found twice keeps the nearer one. */\n readonly skills: Skill[];\n /** `extension_loaded` records with tier `skill`, for `HarnessOptions.extensionRecords`. */\n readonly records: ExtensionLoadedRecord[];\n /** One line for each file or folder skipped and each skill that shares a name. */\n readonly notices: string[];\n}\n\nconst MAX_DEPTH = 4;\n/** The longest `SKILL.md` listed, our own limit. A longer one is skipped with a notice, so a record's hash covers the whole file. */\nconst SKILL_FILE_MAX_BYTES = 256 * 1024;\n\n/**\n * Why a folder's name is not walked, or `undefined` when it may be. A control character would put a line of the\n * project's choosing into the system prompt, which lists each skill's path. On POSIX a `\\` is an ordinary character in\n * a name, but a model or a tool that reads the path as Windows does takes it for a separator, so a folder named\n * `a\\..\\..\\etc` would give a skill a path that seems to name a file outside its folder.\n */\nfunction badName(name: string): string | undefined {\n if (/\\p{Cc}/u.test(name)) return \"it holds a control character\";\n if (sep === \"/\" && name.includes(\"\\\\\")) return \"it holds a \\\\, which a path on Windows reads as a separator\";\n return undefined;\n}\n\n/**\n * The `SKILL.md` files under `dir`, found by walking down at most `MAX_DEPTH` levels, with a notice in `notices` for\n * each folder whose name is not walked. Links are not followed.\n */\nasync function skillFiles(dir: string, notices: string[], depth = 0): Promise<string[]> {\n let entries: import(\"node:fs\").Dirent[];\n try {\n entries = await readdir(dir, { withFileTypes: true });\n } catch {\n return [];\n }\n entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));\n const found: string[] = [];\n if (entries.some((entry) => entry.name === \"SKILL.md\" && (entry.isFile() || entry.isSymbolicLink())))\n found.push(join(dir, \"SKILL.md\"));\n // A skill's own folder holds its references and scripts, and none of them is another skill.\n if (found.length > 0 || depth >= MAX_DEPTH) return found;\n for (const entry of entries) {\n if (!entry.isDirectory() || entry.name === \"node_modules\") continue;\n const reason = badName(entry.name);\n if (reason === undefined) found.push(...(await skillFiles(join(dir, entry.name), notices, depth + 1)));\n else notices.push(`${attribute(join(dir, entry.name))} is skipped: ${reason}`);\n }\n return found;\n}\n\n/** Why the project's skills are not listed, or `undefined` when they may be. */\nasync function skipReason(root: string, options: DiscoverSkillsOptions): Promise<string | undefined> {\n if (options.headless === true && options.loadInHeadless !== true) {\n return `the project skills of ${root} are skipped: this run is headless`;\n }\n if (!(await projectTrusted(options.trust, root))) {\n return `the project skills of ${root} are skipped: the project is not trusted`;\n }\n return undefined;\n}\n\n/** One `SKILL.md` read and checked: the skill with its record, a notice saying why it is skipped, or nothing when it is gone. */\nasync function loadSkill(\n root: string,\n file: string,\n taken: ReadonlySet<string>,\n): Promise<\n { skill: Skill; record: ExtensionLoadedRecord; warning?: string } | { notice: string } | Record<string, never>\n> {\n const read = await readProjectFile(root, file, SKILL_FILE_MAX_BYTES);\n if (read === undefined) return {};\n if (\"notice\" in read) return read;\n // The record's hash must cover the whole file, and a cut file's hash would not.\n if (read.truncated) return { notice: `${file} is longer than ${SKILL_FILE_MAX_BYTES} bytes, so it is not listed` };\n // The path the model reads is the one found, not a link's target.\n const parsed = parseSkill(read.text, file);\n if (\"problem\" in parsed) return { notice: `${parsed.problem}, so it is not listed` };\n if (taken.has(parsed.skill.name)) {\n return { notice: `${file} is skipped: a nearer skill is already named \"${parsed.skill.name}\"` };\n }\n const record = { name: parsed.skill.name, tier: \"skill\" as const, contentHash: await sha256(read.bytes) };\n return { skill: parsed.skill, record, ...(parsed.notice === undefined ? {} : { warning: parsed.notice }) };\n}\n\n/**\n * Finds the skills of the project `cwd` is in: each folder under `.agents/skills` holding a `SKILL.md`, in `cwd` and\n * every folder above it up to the repository root (the first folder with a `.git`). A `cwd` in no repository searches\n * only itself. A file that is not a skill, a `SKILL.md` that is a link leaving the project, a name already taken by\n * a nearer skill, and a folder whose name holds a control character, or a `\\` on POSIX, are skipped with a notice, and\n * the rest still load. The skills' paths are absolute. No skill file is read\n * until the trust store and `headless` allow it: an untrusted project, or a headless run without `loadInHeadless`,\n * lists no skills and returns one notice saying why.\n */\nexport async function discoverSkills(cwd: string, options: DiscoverSkillsOptions): Promise<DiscoveredSkills> {\n const dirs = await projectDirs(cwd);\n const root = dirs.at(-1) as string;\n const result: DiscoveredSkills = { skills: [], records: [], notices: [] };\n const reason = await skipReason(root, options);\n if (reason !== undefined) {\n result.notices.push(reason);\n return result;\n }\n const names = new Set<string>();\n for (const dir of dirs) {\n for (const file of await skillFiles(join(dir, \".agents\", \"skills\"), result.notices)) {\n const found = await loadSkill(root, file, names);\n if (\"notice\" in found) result.notices.push(found.notice);\n if (!(\"skill\" in found)) continue;\n if (found.warning !== undefined) result.notices.push(found.warning);\n names.add(found.skill.name);\n result.skills.push(found.skill);\n result.records.push(found.record);\n }\n }\n return result;\n}\n"]}
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Skills, the no-code extension tier: a folder with a `SKILL.md` whose frontmatter names the skill and says when to use
3
+ * it. Only the name, description and path go into the system prompt, and the model reads the body through the `read`
4
+ * tool when a task matches. This file holds the parts that need no file system, so any runtime can use them;
5
+ * `discoverSkills()` in `@buildanagent/harness/extensions/node` finds the files.
6
+ */
7
+ /** The longest skill name, in characters. */
8
+ export declare const SKILL_NAME_MAX = 64;
9
+ /** The longest skill description, in characters. */
10
+ export declare const SKILL_DESCRIPTION_MAX = 1024;
11
+ /** A skill as the system prompt lists it: the body stays in the file. */
12
+ export interface Skill {
13
+ /** Lowercase letters, digits and single hyphens, at most 64 characters. */
14
+ readonly name: string;
15
+ /** Says when to load the skill, at most 1,024 characters. */
16
+ readonly description: string;
17
+ /** The absolute path of the skill's `SKILL.md`, which the model reads to load the body. */
18
+ readonly path: string;
19
+ }
20
+ /** What `parseSkill()` makes of one file: the skill, or why the file is not one. Either may carry a notice. */
21
+ export type ParsedSkill = {
22
+ readonly skill: Skill;
23
+ readonly notice?: string;
24
+ } | {
25
+ readonly problem: string;
26
+ };
27
+ /**
28
+ * Reads one `SKILL.md`. The frontmatter is a small subset of YAML: `key: value` lines, quoted or plain, with a value
29
+ * that may continue on indented lines or be a `>` or `|` block, which is folded onto one line; the indicator may carry
30
+ * an indentation digit and a chomping sign, such as `|2` or `>-`. A plain value's `#` comment is dropped, so
31
+ * `name: deploy # prod only` names `deploy`, and quotes are removed only from a value that is one quoted string, so
32
+ * `'a' or 'b'` stays as written. A file with no
33
+ * frontmatter, a missing or empty name or description, a name that is not lowercase letters, digits and single hyphens
34
+ * or runs past 64 characters, or a description past 1,024 characters is not a skill, and `problem` says why. A skill's
35
+ * name should match the name of its folder: one that differs still loads, with a notice.
36
+ */
37
+ export declare function parseSkill(text: string, path: string): ParsedSkill;
38
+ /** The `## Skills` section a system prompt carries: each skill's name, description and path, and never its body. */
39
+ export declare function skillsPrompt(skills: readonly Skill[]): string;
40
+ /** `system` followed by the skills section, or `system` alone when there are no skills. */
41
+ export declare function withSkills(system: string, skills: readonly Skill[]): string;
42
+ /**
43
+ * The skill whose `SKILL.md` a `read` call opens, or `undefined`. The input names the file in its `path` or
44
+ * `file_path` string, which is taken relative to `cwd` when it is not absolute. Only the skill's own `SKILL.md` counts:
45
+ * reading another file in its folder loads no skill. A skill whose path is a Windows path, with a drive such as `C:\`,
46
+ * matches Windows reads: `\` separates segments as `/` does, and the drive letter's case is ignored. Any other skill
47
+ * path is a POSIX one, where only `/` separates segments and a `\` is part of a name, so a read of `a\..\x` never
48
+ * matches the skill at `x`. A read that asks for part of the file, by an `offset` or a `limit` that is not `undefined`
49
+ * or `null`, loads no skill, because it may have shown only a few lines of it.
50
+ */
51
+ export declare function skillOfRead(skills: readonly Skill[], cwd: string, input: unknown): Skill | undefined;
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Skills, the no-code extension tier: a folder with a `SKILL.md` whose frontmatter names the skill and says when to use
3
+ * it. Only the name, description and path go into the system prompt, and the model reads the body through the `read`
4
+ * tool when a task matches. This file holds the parts that need no file system, so any runtime can use them;
5
+ * `discoverSkills()` in `@buildanagent/harness/extensions/node` finds the files.
6
+ */
7
+ // Both limits are taken from Pi's skills documentation; the Agent Skills specification was unreachable when they were set.
8
+ /** The longest skill name, in characters. */
9
+ export const SKILL_NAME_MAX = 64;
10
+ /** The longest skill description, in characters. */
11
+ export const SKILL_DESCRIPTION_MAX = 1024;
12
+ const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
13
+ /** The top-level `key: value` pairs of a `---` fenced frontmatter block, or `undefined` when the file has none. */
14
+ function frontmatter(text) {
15
+ const lines = text.replace(/^/, "").split(/\r?\n/);
16
+ if (lines[0]?.trim() !== "---")
17
+ return undefined;
18
+ const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
19
+ if (end < 0)
20
+ return undefined;
21
+ const fields = new Map();
22
+ let key;
23
+ let parts = [];
24
+ const close = () => {
25
+ if (key !== undefined)
26
+ fields.set(key, joined(parts));
27
+ key = undefined;
28
+ parts = [];
29
+ };
30
+ for (const line of lines.slice(1, end)) {
31
+ const match = /^([A-Za-z][\w-]*):(.*)$/.exec(line);
32
+ if (match !== null) {
33
+ close();
34
+ key = match[1];
35
+ parts = [match[2]];
36
+ }
37
+ else if (key !== undefined && /^\s+\S/.test(line)) {
38
+ parts.push(line);
39
+ }
40
+ }
41
+ close();
42
+ return fields;
43
+ }
44
+ /** A block scalar's indicator: `>` or `|`, then an optional indentation digit and chomping sign, in either order. */
45
+ const BLOCK = /^[>|](?:[1-9][+-]?|[+-][1-9]?)?$/;
46
+ /** One fully double-quoted or single-quoted value, which only a comment may follow. */
47
+ const QUOTED = /^(?:"((?:[^"\\]|\\.)*)"|'((?:[^']|'')*)')(?:\s+#.*)?$/s;
48
+ /** A plain line without its comment: YAML starts one at a `#` that opens the line or follows a space. */
49
+ const uncommented = (line) => line.replace(/(?:^|\s)#.*$/, "").trimEnd();
50
+ /**
51
+ * One value from its lines. A block scalar keeps its lines as written and drops its indicator line; a value that is one
52
+ * quoted string loses its quotes, with a single quote's `''` read as `'`; a plain value loses its comments. The lines
53
+ * are then folded with a space.
54
+ */
55
+ function joined(parts) {
56
+ const lines = parts.map((part) => part.trim());
57
+ const [first = "", ...rest] = lines;
58
+ const kept = (values) => values.filter((value) => value !== "").join(" ");
59
+ if (BLOCK.test(uncommented(first)))
60
+ return kept(rest);
61
+ const quoted = QUOTED.exec(kept(lines));
62
+ if (quoted !== null)
63
+ return quoted[1] ?? quoted[2].replaceAll("''", "'");
64
+ return kept(lines.map(uncommented));
65
+ }
66
+ /**
67
+ * Reads one `SKILL.md`. The frontmatter is a small subset of YAML: `key: value` lines, quoted or plain, with a value
68
+ * that may continue on indented lines or be a `>` or `|` block, which is folded onto one line; the indicator may carry
69
+ * an indentation digit and a chomping sign, such as `|2` or `>-`. A plain value's `#` comment is dropped, so
70
+ * `name: deploy # prod only` names `deploy`, and quotes are removed only from a value that is one quoted string, so
71
+ * `'a' or 'b'` stays as written. A file with no
72
+ * frontmatter, a missing or empty name or description, a name that is not lowercase letters, digits and single hyphens
73
+ * or runs past 64 characters, or a description past 1,024 characters is not a skill, and `problem` says why. A skill's
74
+ * name should match the name of its folder: one that differs still loads, with a notice.
75
+ */
76
+ export function parseSkill(text, path) {
77
+ const fields = frontmatter(text);
78
+ if (fields === undefined)
79
+ return { problem: `${path} has no frontmatter between --- lines` };
80
+ const name = fields.get("name") ?? "";
81
+ const description = fields.get("description") ?? "";
82
+ if (name === "")
83
+ return { problem: `${path} has no name` };
84
+ if (description === "")
85
+ return { problem: `${path} has no description` };
86
+ if (name.length > SKILL_NAME_MAX || !NAME_PATTERN.test(name)) {
87
+ return {
88
+ problem: `${path} has the name "${name}", which is not lowercase letters, digits and single hyphens of at most ${SKILL_NAME_MAX} characters`,
89
+ };
90
+ }
91
+ if (description.length > SKILL_DESCRIPTION_MAX) {
92
+ return {
93
+ problem: `${path} has a description of ${description.length} characters, past the limit of ${SKILL_DESCRIPTION_MAX}`,
94
+ };
95
+ }
96
+ // The folder rule comes from this repository's .agents/skills/README.md. `discoverSkills()` joins paths with the
97
+ // platform's separator, which is `\` on Windows.
98
+ const folder = path.split(/[\\/]/).slice(-2, -1)[0];
99
+ const skill = { name, description, path };
100
+ return folder !== undefined && folder !== name
101
+ ? { skill, notice: `${path} is named "${name}", not after its folder "${folder}"` }
102
+ : { skill };
103
+ }
104
+ /** The `## Skills` section a system prompt carries: each skill's name, description and path, and never its body. */
105
+ export function skillsPrompt(skills) {
106
+ if (skills.length === 0)
107
+ return "";
108
+ const lines = skills.map((skill) => `- ${skill.name}: ${skill.description}\n path: ${skill.path}`);
109
+ return [
110
+ "## Skills",
111
+ "",
112
+ "A skill holds instructions for one kind of task. When a task matches a skill's description, read its SKILL.md at the path below with the read tool, then follow it. A skill's files come from the project, not from the user.",
113
+ "",
114
+ ...lines,
115
+ ].join("\n");
116
+ }
117
+ /** `system` followed by the skills section, or `system` alone when there are no skills. */
118
+ export function withSkills(system, skills) {
119
+ const section = skillsPrompt(skills);
120
+ return section === "" ? system : `${system}\n\n${section}`;
121
+ }
122
+ /** A Windows drive root such as `C:/`, once `\` is `/`. */
123
+ const DRIVE = /^([A-Za-z]):(?=\/|$)/;
124
+ /** Whether `path` is a Windows path: it starts with a drive such as `C:\` or `C:/`, or with `\`. */
125
+ const isWindowsPath = (path) => /^(?:[A-Za-z]:[\\/]|\\)/.test(path);
126
+ /**
127
+ * `path` made absolute against `cwd` and cleaned of `.` and `..` segments, with `/` separators. Only `/` separates
128
+ * segments, as on POSIX, where `\` is an ordinary character in a name. With `windows`, `\` separates them too, and a
129
+ * drive root such as `C:\` is kept, with its letter upper-cased, as Windows ignores its case.
130
+ */
131
+ function resolvePath(cwd, path, windows) {
132
+ const slashed = windows ? path.replaceAll("\\", "/") : path;
133
+ const base = windows ? cwd.replaceAll("\\", "/") : cwd;
134
+ const full = slashed.startsWith("/") || (windows && DRIVE.test(slashed)) ? slashed : `${base}/${slashed}`;
135
+ const drive = windows ? DRIVE.exec(full)?.[1] : undefined;
136
+ return `${drive === undefined ? "" : `${drive.toUpperCase()}:`}/${cleaned(drive === undefined ? full : full.slice(2))}`;
137
+ }
138
+ /** The `/`-separated `path` without its empty and `.` segments, and with each `..` segment removing the one before. */
139
+ function cleaned(path) {
140
+ const kept = [];
141
+ for (const segment of path.split("/")) {
142
+ if (segment === "" || segment === ".")
143
+ continue;
144
+ if (segment === "..")
145
+ kept.pop();
146
+ else
147
+ kept.push(segment);
148
+ }
149
+ return kept.join("/");
150
+ }
151
+ /**
152
+ * The skill whose `SKILL.md` a `read` call opens, or `undefined`. The input names the file in its `path` or
153
+ * `file_path` string, which is taken relative to `cwd` when it is not absolute. Only the skill's own `SKILL.md` counts:
154
+ * reading another file in its folder loads no skill. A skill whose path is a Windows path, with a drive such as `C:\`,
155
+ * matches Windows reads: `\` separates segments as `/` does, and the drive letter's case is ignored. Any other skill
156
+ * path is a POSIX one, where only `/` separates segments and a `\` is part of a name, so a read of `a\..\x` never
157
+ * matches the skill at `x`. A read that asks for part of the file, by an `offset` or a `limit` that is not `undefined`
158
+ * or `null`, loads no skill, because it may have shown only a few lines of it.
159
+ */
160
+ export function skillOfRead(skills, cwd, input) {
161
+ if (typeof input !== "object" || input === null)
162
+ return undefined;
163
+ // `offset` and `limit` are the range names of Pi's and Claude Code's read tools; the built-in `read` must keep them.
164
+ const { path, file_path: filePath, offset, limit } = input;
165
+ if ((offset !== undefined && offset !== null) || (limit !== undefined && limit !== null))
166
+ return undefined;
167
+ const named = typeof path === "string" ? path : filePath;
168
+ if (typeof named !== "string" || named === "")
169
+ return undefined;
170
+ return skills.find((skill) => {
171
+ const windows = isWindowsPath(skill.path);
172
+ return resolvePath("/", skill.path, windows) === resolvePath(cwd, named, windows);
173
+ });
174
+ }
175
+ //# sourceMappingURL=skills.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/extensions/skills.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skills, the no-code extension tier: a folder with a `SKILL.md` whose frontmatter names the skill and says when to use\n * it. Only the name, description and path go into the system prompt, and the model reads the body through the `read`\n * tool when a task matches. This file holds the parts that need no file system, so any runtime can use them;\n * `discoverSkills()` in `@buildanagent/harness/extensions/node` finds the files.\n */\n\n// Both limits are taken from Pi's skills documentation; the Agent Skills specification was unreachable when they were set.\n/** The longest skill name, in characters. */\nexport const SKILL_NAME_MAX = 64;\n/** The longest skill description, in characters. */\nexport const SKILL_DESCRIPTION_MAX = 1024;\n\n/** A skill as the system prompt lists it: the body stays in the file. */\nexport interface Skill {\n /** Lowercase letters, digits and single hyphens, at most 64 characters. */\n readonly name: string;\n /** Says when to load the skill, at most 1,024 characters. */\n readonly description: string;\n /** The absolute path of the skill's `SKILL.md`, which the model reads to load the body. */\n readonly path: string;\n}\n\n/** What `parseSkill()` makes of one file: the skill, or why the file is not one. Either may carry a notice. */\nexport type ParsedSkill = { readonly skill: Skill; readonly notice?: string } | { readonly problem: string };\n\nconst NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;\n\n/** The top-level `key: value` pairs of a `---` fenced frontmatter block, or `undefined` when the file has none. */\nfunction frontmatter(text: string): Map<string, string> | undefined {\n const lines = text.replace(/^/, \"\").split(/\\r?\\n/);\n if (lines[0]?.trim() !== \"---\") return undefined;\n const end = lines.findIndex((line, i) => i > 0 && line.trim() === \"---\");\n if (end < 0) return undefined;\n const fields = new Map<string, string>();\n let key: string | undefined;\n let parts: string[] = [];\n const close = () => {\n if (key !== undefined) fields.set(key, joined(parts));\n key = undefined;\n parts = [];\n };\n for (const line of lines.slice(1, end)) {\n const match = /^([A-Za-z][\\w-]*):(.*)$/.exec(line);\n if (match !== null) {\n close();\n key = match[1] as string;\n parts = [match[2] as string];\n } else if (key !== undefined && /^\\s+\\S/.test(line)) {\n parts.push(line);\n }\n }\n close();\n return fields;\n}\n\n/** A block scalar's indicator: `>` or `|`, then an optional indentation digit and chomping sign, in either order. */\nconst BLOCK = /^[>|](?:[1-9][+-]?|[+-][1-9]?)?$/;\n/** One fully double-quoted or single-quoted value, which only a comment may follow. */\nconst QUOTED = /^(?:\"((?:[^\"\\\\]|\\\\.)*)\"|'((?:[^']|'')*)')(?:\\s+#.*)?$/s;\n\n/** A plain line without its comment: YAML starts one at a `#` that opens the line or follows a space. */\nconst uncommented = (line: string): string => line.replace(/(?:^|\\s)#.*$/, \"\").trimEnd();\n\n/**\n * One value from its lines. A block scalar keeps its lines as written and drops its indicator line; a value that is one\n * quoted string loses its quotes, with a single quote's `''` read as `'`; a plain value loses its comments. The lines\n * are then folded with a space.\n */\nfunction joined(parts: readonly string[]): string {\n const lines = parts.map((part) => part.trim());\n const [first = \"\", ...rest] = lines;\n const kept = (values: readonly string[]) => values.filter((value) => value !== \"\").join(\" \");\n if (BLOCK.test(uncommented(first))) return kept(rest);\n const quoted = QUOTED.exec(kept(lines));\n if (quoted !== null) return quoted[1] ?? (quoted[2] as string).replaceAll(\"''\", \"'\");\n return kept(lines.map(uncommented));\n}\n\n/**\n * Reads one `SKILL.md`. The frontmatter is a small subset of YAML: `key: value` lines, quoted or plain, with a value\n * that may continue on indented lines or be a `>` or `|` block, which is folded onto one line; the indicator may carry\n * an indentation digit and a chomping sign, such as `|2` or `>-`. A plain value's `#` comment is dropped, so\n * `name: deploy # prod only` names `deploy`, and quotes are removed only from a value that is one quoted string, so\n * `'a' or 'b'` stays as written. A file with no\n * frontmatter, a missing or empty name or description, a name that is not lowercase letters, digits and single hyphens\n * or runs past 64 characters, or a description past 1,024 characters is not a skill, and `problem` says why. A skill's\n * name should match the name of its folder: one that differs still loads, with a notice.\n */\nexport function parseSkill(text: string, path: string): ParsedSkill {\n const fields = frontmatter(text);\n if (fields === undefined) return { problem: `${path} has no frontmatter between --- lines` };\n const name = fields.get(\"name\") ?? \"\";\n const description = fields.get(\"description\") ?? \"\";\n if (name === \"\") return { problem: `${path} has no name` };\n if (description === \"\") return { problem: `${path} has no description` };\n if (name.length > SKILL_NAME_MAX || !NAME_PATTERN.test(name)) {\n return {\n problem: `${path} has the name \"${name}\", which is not lowercase letters, digits and single hyphens of at most ${SKILL_NAME_MAX} characters`,\n };\n }\n if (description.length > SKILL_DESCRIPTION_MAX) {\n return {\n problem: `${path} has a description of ${description.length} characters, past the limit of ${SKILL_DESCRIPTION_MAX}`,\n };\n }\n // The folder rule comes from this repository's .agents/skills/README.md. `discoverSkills()` joins paths with the\n // platform's separator, which is `\\` on Windows.\n const folder = path.split(/[\\\\/]/).slice(-2, -1)[0];\n const skill: Skill = { name, description, path };\n return folder !== undefined && folder !== name\n ? { skill, notice: `${path} is named \"${name}\", not after its folder \"${folder}\"` }\n : { skill };\n}\n\n/** The `## Skills` section a system prompt carries: each skill's name, description and path, and never its body. */\nexport function skillsPrompt(skills: readonly Skill[]): string {\n if (skills.length === 0) return \"\";\n const lines = skills.map((skill) => `- ${skill.name}: ${skill.description}\\n path: ${skill.path}`);\n return [\n \"## Skills\",\n \"\",\n \"A skill holds instructions for one kind of task. When a task matches a skill's description, read its SKILL.md at the path below with the read tool, then follow it. A skill's files come from the project, not from the user.\",\n \"\",\n ...lines,\n ].join(\"\\n\");\n}\n\n/** `system` followed by the skills section, or `system` alone when there are no skills. */\nexport function withSkills(system: string, skills: readonly Skill[]): string {\n const section = skillsPrompt(skills);\n return section === \"\" ? system : `${system}\\n\\n${section}`;\n}\n\n/** A Windows drive root such as `C:/`, once `\\` is `/`. */\nconst DRIVE = /^([A-Za-z]):(?=\\/|$)/;\n\n/** Whether `path` is a Windows path: it starts with a drive such as `C:\\` or `C:/`, or with `\\`. */\nconst isWindowsPath = (path: string): boolean => /^(?:[A-Za-z]:[\\\\/]|\\\\)/.test(path);\n\n/**\n * `path` made absolute against `cwd` and cleaned of `.` and `..` segments, with `/` separators. Only `/` separates\n * segments, as on POSIX, where `\\` is an ordinary character in a name. With `windows`, `\\` separates them too, and a\n * drive root such as `C:\\` is kept, with its letter upper-cased, as Windows ignores its case.\n */\nfunction resolvePath(cwd: string, path: string, windows: boolean): string {\n const slashed = windows ? path.replaceAll(\"\\\\\", \"/\") : path;\n const base = windows ? cwd.replaceAll(\"\\\\\", \"/\") : cwd;\n const full = slashed.startsWith(\"/\") || (windows && DRIVE.test(slashed)) ? slashed : `${base}/${slashed}`;\n const drive = windows ? DRIVE.exec(full)?.[1] : undefined;\n return `${drive === undefined ? \"\" : `${drive.toUpperCase()}:`}/${cleaned(drive === undefined ? full : full.slice(2))}`;\n}\n\n/** The `/`-separated `path` without its empty and `.` segments, and with each `..` segment removing the one before. */\nfunction cleaned(path: string): string {\n const kept: string[] = [];\n for (const segment of path.split(\"/\")) {\n if (segment === \"\" || segment === \".\") continue;\n if (segment === \"..\") kept.pop();\n else kept.push(segment);\n }\n return kept.join(\"/\");\n}\n\n/**\n * The skill whose `SKILL.md` a `read` call opens, or `undefined`. The input names the file in its `path` or\n * `file_path` string, which is taken relative to `cwd` when it is not absolute. Only the skill's own `SKILL.md` counts:\n * reading another file in its folder loads no skill. A skill whose path is a Windows path, with a drive such as `C:\\`,\n * matches Windows reads: `\\` separates segments as `/` does, and the drive letter's case is ignored. Any other skill\n * path is a POSIX one, where only `/` separates segments and a `\\` is part of a name, so a read of `a\\..\\x` never\n * matches the skill at `x`. A read that asks for part of the file, by an `offset` or a `limit` that is not `undefined`\n * or `null`, loads no skill, because it may have shown only a few lines of it.\n */\nexport function skillOfRead(skills: readonly Skill[], cwd: string, input: unknown): Skill | undefined {\n if (typeof input !== \"object\" || input === null) return undefined;\n // `offset` and `limit` are the range names of Pi's and Claude Code's read tools; the built-in `read` must keep them.\n const { path, file_path: filePath, offset, limit } = input as Record<string, unknown>;\n if ((offset !== undefined && offset !== null) || (limit !== undefined && limit !== null)) return undefined;\n const named = typeof path === \"string\" ? path : filePath;\n if (typeof named !== \"string\" || named === \"\") return undefined;\n return skills.find((skill) => {\n const windows = isWindowsPath(skill.path);\n return resolvePath(\"/\", skill.path, windows) === resolvePath(cwd, named, windows);\n });\n}\n"]}
@@ -0,0 +1,3 @@
1
+ import type { TrustStore } from "./types.js";
2
+ /** A trust store in the file at `file`, created on the first `trust()`. A folder is compared by its real path, so a symlinked root and its target are one project. */
3
+ export declare function fileTrustStore(file: string): TrustStore;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The trust store that keeps its folders in a JSON file. It uses Node's file system, so it has its own entry,
3
+ * `@buildanagent/harness/extensions/node`. A folder in the file may load its own extensions; trust is not a sandbox, and
4
+ * what an extension may do once loaded is the permission pipeline's decision.
5
+ */
6
+ import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
7
+ import { dirname } from "node:path";
8
+ import { HarnessError } from "../errors.js";
9
+ import { canonicalPath } from "./load.js";
10
+ import { parseObject } from "./lock.js";
11
+ async function read(file) {
12
+ let text;
13
+ try {
14
+ const info = await stat(file);
15
+ if (!info.isFile())
16
+ throw new HarnessError("invalid_extension", `the trust file ${file} is not a regular file`);
17
+ // A file others may write is one anyone could add a project to.
18
+ if ((info.mode & 0o022) !== 0)
19
+ throw new HarnessError("invalid_extension", `the trust file ${file} is writable by others`);
20
+ text = await readFile(file, "utf8");
21
+ }
22
+ catch (error) {
23
+ if (error.code === "ENOENT")
24
+ return [];
25
+ throw error;
26
+ }
27
+ const roots = parseObject(text, file).trusted;
28
+ if (!Array.isArray(roots) || !roots.every((root) => typeof root === "string")) {
29
+ throw new HarnessError("invalid_extension", `the trust file ${file} is not a { "trusted": [paths] } object`);
30
+ }
31
+ return roots;
32
+ }
33
+ /** A trust store in the file at `file`, created on the first `trust()`. A folder is compared by its real path, so a symlinked root and its target are one project. */
34
+ export function fileTrustStore(file) {
35
+ // One write at a time in this process, so two `trust()` calls cannot lose one addition. Two processes can still race.
36
+ let writing = Promise.resolve();
37
+ return {
38
+ async isTrusted(projectRoot) {
39
+ return (await read(file)).includes(await canonicalPath(projectRoot));
40
+ },
41
+ trust(projectRoot) {
42
+ const next = writing.then(() => add(file, projectRoot));
43
+ writing = next.catch(() => undefined);
44
+ return next;
45
+ },
46
+ };
47
+ }
48
+ async function add(file, projectRoot) {
49
+ const roots = new Set(await read(file));
50
+ roots.add(await canonicalPath(projectRoot));
51
+ await mkdir(dirname(file), { recursive: true, mode: 0o700 });
52
+ const temp = `${file}.${globalThis.crypto.randomUUID()}.tmp`;
53
+ try {
54
+ await writeFile(temp, `${JSON.stringify({ trusted: [...roots].sort() }, null, 2)}\n`, { mode: 0o600 });
55
+ await rename(temp, file);
56
+ }
57
+ catch (error) {
58
+ await rm(temp, { force: true });
59
+ throw error;
60
+ }
61
+ }
62
+ //# sourceMappingURL=trust-file.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trust-file.js","sourceRoot":"","sources":["../../src/extensions/trust-file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,KAAK,UAAU,IAAI,CAAC,IAAY;IAC9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,kBAAkB,IAAI,wBAAwB,CAAC,CAAC;QAChH,gEAAgE;QAChE,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC;YAC3B,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,kBAAkB,IAAI,wBAAwB,CAAC,CAAC;QAC9F,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA2B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAC9D,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC;IAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,kBAAkB,IAAI,yCAAyC,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,KAAiB,CAAC;AAC3B,CAAC;AAED,sKAAsK;AACtK,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,sHAAsH;IACtH,IAAI,OAAO,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAClD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,WAAW;YACzB,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,KAAK,CAAC,WAAW;YACf,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;YACxD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAAY,EAAE,WAAmB;IAClD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,KAAK,CAAC,GAAG,CAAC,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACvG,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * The trust store that keeps its folders in a JSON file. It uses Node's file system, so it has its own entry,\n * `@buildanagent/harness/extensions/node`. A folder in the file may load its own extensions; trust is not a sandbox, and\n * what an extension may do once loaded is the permission pipeline's decision.\n */\nimport { mkdir, readFile, rename, rm, stat, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { HarnessError } from \"../errors.js\";\nimport { canonicalPath } from \"./load.js\";\nimport { parseObject } from \"./lock.js\";\nimport type { TrustStore } from \"./types.js\";\n\nasync function read(file: string): Promise<string[]> {\n let text: string;\n try {\n const info = await stat(file);\n if (!info.isFile()) throw new HarnessError(\"invalid_extension\", `the trust file ${file} is not a regular file`);\n // A file others may write is one anyone could add a project to.\n if ((info.mode & 0o022) !== 0)\n throw new HarnessError(\"invalid_extension\", `the trust file ${file} is writable by others`);\n text = await readFile(file, \"utf8\");\n } catch (error) {\n if ((error as { code?: string }).code === \"ENOENT\") return [];\n throw error;\n }\n const roots = parseObject(text, file).trusted;\n if (!Array.isArray(roots) || !roots.every((root) => typeof root === \"string\")) {\n throw new HarnessError(\"invalid_extension\", `the trust file ${file} is not a { \"trusted\": [paths] } object`);\n }\n return roots as string[];\n}\n\n/** A trust store in the file at `file`, created on the first `trust()`. A folder is compared by its real path, so a symlinked root and its target are one project. */\nexport function fileTrustStore(file: string): TrustStore {\n // One write at a time in this process, so two `trust()` calls cannot lose one addition. Two processes can still race.\n let writing: Promise<unknown> = Promise.resolve();\n return {\n async isTrusted(projectRoot) {\n return (await read(file)).includes(await canonicalPath(projectRoot));\n },\n trust(projectRoot) {\n const next = writing.then(() => add(file, projectRoot));\n writing = next.catch(() => undefined);\n return next;\n },\n };\n}\n\nasync function add(file: string, projectRoot: string): Promise<void> {\n const roots = new Set(await read(file));\n roots.add(await canonicalPath(projectRoot));\n await mkdir(dirname(file), { recursive: true, mode: 0o700 });\n const temp = `${file}.${globalThis.crypto.randomUUID()}.tmp`;\n try {\n await writeFile(temp, `${JSON.stringify({ trusted: [...roots].sort() }, null, 2)}\\n`, { mode: 0o600 });\n await rename(temp, file);\n } catch (error) {\n await rm(temp, { force: true });\n throw error;\n }\n}\n"]}
@@ -0,0 +1,10 @@
1
+ import type { TrustStore } from "./types.js";
2
+ /**
3
+ * A trust store in memory, for tests and for a host that decides trust itself, that resolves each folder to its real
4
+ * path when the store is built and when `trust()` adds it. A host that trusts `/tmp/proj`, where `/tmp` links to
5
+ * `/private/tmp` as on macOS, gets that project trusted. A link pointed at another folder after it was added does not
6
+ * carry the trust with it, because the store holds the folder the link named then. A lookup compares the path it is
7
+ * given as written, which is the real path the loaders pass. `memoryTrustStore()` is the portable store, which
8
+ * compares every path as written.
9
+ */
10
+ export declare function realPathTrustStore(trusted?: readonly string[]): TrustStore;
@@ -0,0 +1,33 @@
1
+ /** A trust store in memory that keeps each folder as its real path. Node-only, because it resolves links on the spot. */
2
+ import { realpathSync } from "node:fs";
3
+ import { resolve } from "node:path";
4
+ /** The real path of `path` as it is now, made absolute, or the absolute path when it does not exist. */
5
+ function realPathNow(path) {
6
+ const absolute = resolve(path);
7
+ try {
8
+ return realpathSync(absolute);
9
+ }
10
+ catch {
11
+ return absolute;
12
+ }
13
+ }
14
+ /**
15
+ * A trust store in memory, for tests and for a host that decides trust itself, that resolves each folder to its real
16
+ * path when the store is built and when `trust()` adds it. A host that trusts `/tmp/proj`, where `/tmp` links to
17
+ * `/private/tmp` as on macOS, gets that project trusted. A link pointed at another folder after it was added does not
18
+ * carry the trust with it, because the store holds the folder the link named then. A lookup compares the path it is
19
+ * given as written, which is the real path the loaders pass. `memoryTrustStore()` is the portable store, which
20
+ * compares every path as written.
21
+ */
22
+ export function realPathTrustStore(trusted = []) {
23
+ const roots = new Set(trusted.map(realPathNow));
24
+ return {
25
+ async isTrusted(projectRoot) {
26
+ return roots.has(projectRoot);
27
+ },
28
+ async trust(projectRoot) {
29
+ roots.add(realPathNow(projectRoot));
30
+ },
31
+ };
32
+ }
33
+ //# sourceMappingURL=trust-store-node.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trust-store-node.js","sourceRoot":"","sources":["../../src/extensions/trust-store-node.ts"],"names":[],"mappings":"AAAA,yHAAyH;AACzH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wGAAwG;AACxG,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAAsB,EAAE;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;IAChD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,WAAW;YACzB,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,WAAW;YACrB,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/** A trust store in memory that keeps each folder as its real path. Node-only, because it resolves links on the spot. */\nimport { realpathSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport type { TrustStore } from \"./types.js\";\n\n/** The real path of `path` as it is now, made absolute, or the absolute path when it does not exist. */\nfunction realPathNow(path: string): string {\n const absolute = resolve(path);\n try {\n return realpathSync(absolute);\n } catch {\n return absolute;\n }\n}\n\n/**\n * A trust store in memory, for tests and for a host that decides trust itself, that resolves each folder to its real\n * path when the store is built and when `trust()` adds it. A host that trusts `/tmp/proj`, where `/tmp` links to\n * `/private/tmp` as on macOS, gets that project trusted. A link pointed at another folder after it was added does not\n * carry the trust with it, because the store holds the folder the link named then. A lookup compares the path it is\n * given as written, which is the real path the loaders pass. `memoryTrustStore()` is the portable store, which\n * compares every path as written.\n */\nexport function realPathTrustStore(trusted: readonly string[] = []): TrustStore {\n const roots = new Set(trusted.map(realPathNow));\n return {\n async isTrusted(projectRoot) {\n return roots.has(projectRoot);\n },\n async trust(projectRoot) {\n roots.add(realPathNow(projectRoot));\n },\n };\n}\n"]}
@@ -0,0 +1,42 @@
1
+ import type { McpServerRecord } from "@buildanagent/protocol";
2
+ import type { Interceptors, Observer } from "@buildanagent/sdk";
3
+ import type { ToolRegistration } from "../tools/types.js";
4
+ /** One tool an extension adds. It is registered with source `extension`; `override` lets it replace a built-in. */
5
+ export type ExtensionTool = Omit<ToolRegistration, "source">;
6
+ /**
7
+ * An in-process extension: hooks and tools that run in the harness's own process with its permissions. Nothing
8
+ * isolates them, so loading one is a trust decision.
9
+ *
10
+ * The hooks compose by the SDK's rules, and each moment has one: `transformContext`, `beforeModelCall` and
11
+ * `afterToolCall` chain in registration order; `beforeToolCall` is a gate where the first deny wins and any ask asks;
12
+ * `afterModelCall` passes the message on, so the last override stands; `shouldStop` lets any stop win. Observers are
13
+ * notified in order and can change nothing.
14
+ */
15
+ export interface Extension {
16
+ /** A name that is unique among the extensions of one harness. */
17
+ readonly name: string;
18
+ readonly version: string;
19
+ readonly interceptors?: Interceptors;
20
+ readonly observers?: readonly Observer[];
21
+ readonly tools?: readonly ExtensionTool[];
22
+ }
23
+ /** What the log records about a loaded extension, so a session shows which code ran. */
24
+ export interface ExtensionLoadedRecord {
25
+ readonly name: string;
26
+ readonly tier: "in_process" | "mcp" | "skill";
27
+ /**
28
+ * `sha256:` and the hex digest of the extension's files as they were pinned and imported, or of its name and version
29
+ * for one built in code. It is the hash that was checked, not proof of what ran: a file changed between the hash and
30
+ * the import is not caught. For an MCP server, the digest of the canonical JSON of `mcp`.
31
+ */
32
+ readonly contentHash: string;
33
+ /** For tier `mcp`: how the server was reached, a hash of its command, its era and a hash of its tools. */
34
+ readonly mcp?: McpServerRecord;
35
+ }
36
+ /** Which project folders may load their own extensions. Trust gates loading and nothing else: it is not a sandbox. */
37
+ export interface TrustStore {
38
+ /** Whether the project at `projectRoot` may load its own extensions. */
39
+ isTrusted(projectRoot: string): Promise<boolean>;
40
+ /** Records the project at `projectRoot` as trusted, so its extensions load from now on. */
41
+ trust(projectRoot: string): Promise<void>;
42
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { McpServerRecord } from \"@buildanagent/protocol\";\nimport type { Interceptors, Observer } from \"@buildanagent/sdk\";\nimport type { ToolRegistration } from \"../tools/types.js\";\n\n/** One tool an extension adds. It is registered with source `extension`; `override` lets it replace a built-in. */\nexport type ExtensionTool = Omit<ToolRegistration, \"source\">;\n\n/**\n * An in-process extension: hooks and tools that run in the harness's own process with its permissions. Nothing\n * isolates them, so loading one is a trust decision.\n *\n * The hooks compose by the SDK's rules, and each moment has one: `transformContext`, `beforeModelCall` and\n * `afterToolCall` chain in registration order; `beforeToolCall` is a gate where the first deny wins and any ask asks;\n * `afterModelCall` passes the message on, so the last override stands; `shouldStop` lets any stop win. Observers are\n * notified in order and can change nothing.\n */\nexport interface Extension {\n /** A name that is unique among the extensions of one harness. */\n readonly name: string;\n readonly version: string;\n readonly interceptors?: Interceptors;\n readonly observers?: readonly Observer[];\n readonly tools?: readonly ExtensionTool[];\n}\n\n/** What the log records about a loaded extension, so a session shows which code ran. */\nexport interface ExtensionLoadedRecord {\n readonly name: string;\n readonly tier: \"in_process\" | \"mcp\" | \"skill\";\n /**\n * `sha256:` and the hex digest of the extension's files as they were pinned and imported, or of its name and version\n * for one built in code. It is the hash that was checked, not proof of what ran: a file changed between the hash and\n * the import is not caught. For an MCP server, the digest of the canonical JSON of `mcp`.\n */\n readonly contentHash: string;\n /** For tier `mcp`: how the server was reached, a hash of its command, its era and a hash of its tools. */\n readonly mcp?: McpServerRecord;\n}\n\n/** Which project folders may load their own extensions. Trust gates loading and nothing else: it is not a sandbox. */\nexport interface TrustStore {\n /** Whether the project at `projectRoot` may load its own extensions. */\n isTrusted(projectRoot: string): Promise<boolean>;\n /** Records the project at `projectRoot` as trusted, so its extensions load from now on. */\n trust(projectRoot: string): Promise<void>;\n}\n"]}