@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
package/llms.txt ADDED
@@ -0,0 +1,435 @@
1
+ # @buildanagent/harness
2
+
3
+ > The buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop.
4
+
5
+ The sections of README.md and every public export, generated from this package's README and declaration files in the same commit as its code.
6
+
7
+ ## Docs
8
+
9
+ - [Install the alpha with `pnpm add @buildanagent/harness@alpha`](README.md#install-the-alpha-with-pnpm-add-buildanagentharnessalpha)
10
+ - [The session log holds twenty-one entry types](README.md#the-session-log-holds-twenty-one-entry-types)
11
+ - [A sandbox says what it stops, and the host decides what it may touch](README.md#a-sandbox-says-what-it-stops-and-the-host-decides-what-it-may-touch)
12
+ - [The srt backend confines each command with Anthropic's OS sandbox](README.md#the-srt-backend-confines-each-command-with-anthropics-os-sandbox)
13
+ - [The Docker backend runs each command in a locked-down container](README.md#the-docker-backend-runs-each-command-in-a-locked-down-container)
14
+ - [The egress proxy keeps every credential outside the sandbox](README.md#the-egress-proxy-keeps-every-credential-outside-the-sandbox)
15
+ - [Every spawned process gets a cleared environment](README.md#every-spawned-process-gets-a-cleared-environment)
16
+ - [Test a sandbox with the fake and the conformance suite](README.md#test-a-sandbox-with-the-fake-and-the-conformance-suite)
17
+ - [One registry names, defers and wraps every tool](README.md#one-registry-names-defers-and-wraps-every-tool)
18
+ - [One pipeline decides every tool call, and a call no rule settles is denied when nobody can answer](README.md#one-pipeline-decides-every-tool-call-and-a-call-no-rule-settles-is-denied-when-nobody-can-answer)
19
+ - [A session belongs to a user, and every store call names both](README.md#a-session-belongs-to-a-user-and-every-store-call-names-both)
20
+ - [One writer holds a session's lock, and a lock outlives a crash only by its lease](README.md#one-writer-holds-a-sessions-lock-and-a-lock-outlives-a-crash-only-by-its-lease)
21
+ - [HEAD moves by entries, and a fork or a revert writes a new file and never edits an old one](README.md#head-moves-by-entries-and-a-fork-or-a-revert-writes-a-new-file-and-never-edits-an-old-one)
22
+ - [Nothing is deleted unless you set a retention period](README.md#nothing-is-deleted-unless-you-set-a-retention-period)
23
+ - [`runTurn()` writes one SDK run into the log, and the user entry goes first](README.md#runturn-writes-one-sdk-run-into-the-log-and-the-user-entry-goes-first)
24
+ - [One dispatcher answers every client, and a client in the same process needs no framing](README.md#one-dispatcher-answers-every-client-and-a-client-in-the-same-process-needs-no-framing)
25
+ - [A request for a person goes to every watching client once its entry is durable, and the first answer wins](README.md#a-request-for-a-person-goes-to-every-watching-client-once-its-entry-is-durable-and-the-first-answer-wins)
26
+ - [A client tool's call goes to the client that started the turn](README.md#a-client-tools-call-goes-to-the-client-that-started-the-turn)
27
+ - [Either side cancels its own request with `$/cancelRequest`](README.md#either-side-cancels-its-own-request-with-cancelrequest)
28
+ - [Each connection's queues are bounded at 128, and only events are dropped](README.md#each-connections-queues-are-bounded-at-128-and-only-events-are-dropped)
29
+ - [`session/open` with `fromSeq` replays the entries a client missed](README.md#sessionopen-with-fromseq-replays-the-entries-a-client-missed)
30
+ - [A client that reconnects finds its pending requests in `initialize` and is asked again on open](README.md#a-client-that-reconnects-finds-its-pending-requests-in-initialize-and-is-asked-again-on-open)
31
+ - [`stdioTransport()` serves one client over a pair of byte streams](README.md#stdiotransport-serves-one-client-over-a-pair-of-byte-streams)
32
+ - [`webSocketTransport()` serves one client on one WebSocket](README.md#websockettransport-serves-one-client-on-one-websocket)
33
+ - [The log is the only state, so a turn rebuilds its context from it](README.md#the-log-is-the-only-state-so-a-turn-rebuilds-its-context-from-it)
34
+ - [A crash leaves open calls, and the next turn settles them by what they could have done](README.md#a-crash-leaves-open-calls-and-the-next-turn-settles-them-by-what-they-could-have-done)
35
+ - [Two cheap layers keep a long run small: a write cap that spills, and masking in steps](README.md#two-cheap-layers-keep-a-long-run-small-a-write-cap-that-spills-and-masking-in-steps)
36
+ - [A summary replaces an outgrown span between turns, and the log keeps every original](README.md#a-summary-replaces-an-outgrown-span-between-turns-and-the-log-keeps-every-original)
37
+ - [Two more triggers compact inside a turn: at 90% of a small window, and after a provider overflow](README.md#two-more-triggers-compact-inside-a-turn-at-90-of-a-small-window-and-after-a-provider-overflow)
38
+ - [A turn that ends `done` runs the project's checks, and the diff flags are recorded, never fatal](README.md#a-turn-that-ends-done-runs-the-projects-checks-and-the-diff-flags-are-recorded-never-fatal)
39
+ - [An extension adds hooks and tools in the harness's own process, and project trust only gates loading](README.md#an-extension-adds-hooks-and-tools-in-the-harnesss-own-process-and-project-trust-only-gates-loading)
40
+ - [MCP servers connect side by side, each in its own era, and their tools wait behind tool search](README.md#mcp-servers-connect-side-by-side-each-in-its-own-era-and-their-tools-wait-behind-tool-search)
41
+ - [A skill is a file the model reads, and only its name, description and path are in the prompt](README.md#a-skill-is-a-file-the-model-reads-and-only-its-name-description-and-path-are-in-the-prompt)
42
+ - [`AGENTS.md`, `CLAUDE.md` and the plan files lead every request, labelled untrusted](README.md#agentsmd-claudemd-and-the-plan-files-lead-every-request-labelled-untrusted)
43
+ - [A call that needs a person is a signed pause that any process with the key file can resume](README.md#a-call-that-needs-a-person-is-a-signed-pause-that-any-process-with-the-key-file-can-resume)
44
+ - [One answer can cover more than its call, and a quorum can ask for several](README.md#one-answer-can-cover-more-than-its-call-and-a-quorum-can-ask-for-several)
45
+ - [Code runs a side effect through the same pipeline and pause as the model, with no model call](README.md#code-runs-a-side-effect-through-the-same-pipeline-and-pause-as-the-model-with-no-model-call)
46
+ - [The key ring is a 0600 file outside the log and the sandbox](README.md#the-key-ring-is-a-0600-file-outside-the-log-and-the-sandbox)
47
+ - [A read-only secret can hold the key ring instead](README.md#a-read-only-secret-can-hold-the-key-ring-instead)
48
+
49
+ ## Exports from `@buildanagent/harness`
50
+
51
+ - `class HarnessError`: Thrown for a mistake in how the harness is called, and for a sandbox that is unavailable or refuses a file operation.
52
+ - `type HarnessErrorCode`: Why a `HarnessError` was thrown.
53
+ - `isHarnessError()`: True for a `HarnessError`, including one from another copy of the package.
54
+ - `PACKAGE_NAME`: The package's npm name, `@buildanagent/harness`.
55
+
56
+ ## Exports from `@buildanagent/harness/session`
57
+
58
+ - `ABORTED_EXIT_CODE`: The exit code recorded for a check that never finished because the turn's signal aborted (130, as for SIGINT).
59
+ - `interface AppendOptions`: The options of `append()`.
60
+ - `ApprovalPolicy`: re-exported from `@buildanagent/protocol`.
61
+ - `interface Approvals`: The approvals of one harness.
62
+ - `interface ApprovalsOptions`: The options of `createApprovals()`.
63
+ - `interface CheckConfig`: The parts of the workspace that decide what a check does, as text: the config file, the bodies of the `package.json` scripts discovery names and the resolved checks run (with their `pre` and `post` hooks), and the `Makefile` `test` rule.
64
+ - `CheckoutEntry`: re-exported from `@buildanagent/protocol`.
65
+ - `type ChildLink`: What links a child session to the session that started it: a tool call, or a workflow step.
66
+ - `interface ClientToolCall`: One call to a `client_request` tool, as `TurnOptions.clientTool` receives it.
67
+ - `type ClientToolRunner`: Runs a `client_request` tool's call by asking the client that holds the tool, and resolves with its result.
68
+ - `CodeCallEntry`: re-exported from `@buildanagent/protocol`.
69
+ - `CompactionEntry`: re-exported from `@buildanagent/protocol`.
70
+ - `CompletionCheckEntry`: re-exported from `@buildanagent/protocol`.
71
+ - `type CompletionOutcome`: What a check found: the body of the `completion_check` entry.
72
+ - `interface CompletionSettings`: What a turn needs to check its own completion.
73
+ - `interface CompletionStart`: What a turn recorded before the model ran.
74
+ - `class ConflictError`: Thrown by `append()` when the log is not in the state the caller expected: `expectedLastId` is stale, an entry id is already stored with different content, or a batch is partly stored out of order.
75
+ - `createApprovals()`: Creates the approvals of `harness`, which needs a `signer` to check the requests it resumes.
76
+ - `DEFAULT_CHECK_TIMEOUT_MS`: How long one check may run before it is stopped with exit code 124.
77
+ - `DEFAULT_MAX_ENTRY_BYTES`: The default bound on one entry's JSON, in bytes.
78
+ - `DEFAULT_PLATFORM_HINT`: Where a read-only store's error sends the owner when no hint is given.
79
+ - `DENIED_EXIT_CODE`: The exit code recorded for a check that the sandbox's policy refused to run.
80
+ - `DERIVED`: The prefix of the name of a file that holds part of a session, such as a revert's or a migration's file.
81
+ - `DISCOVERED_SCRIPTS`: The `package.json` scripts discovery runs, in the order it runs them.
82
+ - `effectScope()`: The `EffectScope` a guarded write takes for `toolCallId`.
83
+ - `EntryBase`: re-exported from `@buildanagent/protocol`.
84
+ - `type EntryInput`: An entry as a caller writes it.
85
+ - `class EntryTooLargeError`: Thrown by `append()` when an entry's JSON is over the store's bound, which is 64 KiB unless the store sets another.
86
+ - `EnvStampEntry`: re-exported from `@buildanagent/protocol`.
87
+ - `ExtensionLoadedEntry`: re-exported from `@buildanagent/protocol`.
88
+ - `flagChanges()`: Compares the workspace at the start of a turn with the end, and returns one sentence for each pattern the plan names: an added skip marker (`.skip(`, `xit(` or `@pytest.mark.skip`), an added placeholder (`TODO` or `FIXME` in capitals, or "not implemented" in any case), a new file whose name has `mock`, `stub` or `fake` in it, a deleted test file, and a test file with fewer assertion lines than before.
89
+ - `FORMAT_VERSION`: re-exported from `@buildanagent/protocol`.
90
+ - `gitSnapshotter`: The default snapshotter: every file git tracks or would track (so untracked files that `.gitignore` leaves out stay out), read as UTF-8 text up to `MAX_SNAPSHOT_FILE_BYTES` each and `MAX_SNAPSHOT_FILES` files.
91
+ - `HARNESS_CONFIG_PATH`: Where a project lists its checks, relative to the workspace root.
92
+ - `isDerivedFile`: Whether a file id names a derived file.
93
+ - `isProtocolError`: re-exported from `@buildanagent/protocol`.
94
+ - `isTestFile()`: Whether a path looks like a test file: a code file (by its extension, such as `.ts`, `.py` or `.go`) in a `test`, `tests` or `__tests__` folder, or a file named as a test anywhere.
95
+ - `interface KeyChangeOptions`: The options of `rotateKeys()` and `pruneKeys()`.
96
+ - `listSessions()`: The user's sessions, oldest first, without the files that only hold part of a session (a revert's or a migration's).
97
+ - `interface LoadOptions`: The options of `load()`.
98
+ - `LoadoutEntry`: re-exported from `@buildanagent/protocol`.
99
+ - `interface LockHandle`: What `acquire()` returns to the writer that got the lock.
100
+ - `MAX_FLAGS`: The most flags one check records.
101
+ - `MAX_SNAPSHOT_FILE_BYTES`: The largest file a snapshot keeps, in bytes.
102
+ - `MAX_SNAPSHOT_FILES`: The most files a snapshot keeps.
103
+ - `memoryIndex()`: A pointer index in memory, for tests and for a process that keeps its sessions in `memoryStore()`.
104
+ - `memoryStore()`: A store that keeps sessions in memory, for tests and for a process that doesn't need them after it ends.
105
+ - `interface MemoryStoreOptions`: The options of `memoryStore()`.
106
+ - `MessageBlockEntry`: re-exported from `@buildanagent/protocol`.
107
+ - `MessageEndEntry`: re-exported from `@buildanagent/protocol`.
108
+ - `interface MigrateOptions`: The options of `migrateSession()`.
109
+ - `migrateSession()`: Migrates the session's current file to the current format.
110
+ - `interface Migration`: One step of format change: it maps each entry of a file at format `from` to an entry at format `to`.
111
+ - `type MigrationResult`: What `migrateSession()` did.
112
+ - `oneResolution`: The default policy: the latest answer decides.
113
+ - `openSession()`: Opens a session.
114
+ - `interface OpenSessionOptions`: The options of `openSession()`.
115
+ - `Origin`: re-exported from `@buildanagent/protocol`.
116
+ - `parseEntry`: re-exported from `@buildanagent/protocol`.
117
+ - `interface PendingApproval`: A request that waits for a person, with the input its call would run with once approved.
118
+ - `PermissionDecisionEntry`: re-exported from `@buildanagent/protocol`.
119
+ - `PermissionMode`: re-exported from `@buildanagent/protocol`.
120
+ - `processScheduler()`: A `Scheduler` for a host that stays up: each wake is a timer, and the handlers registered with `onWake()` receive it.
121
+ - `interface ProcessScheduler`: A scheduler that delivers its wakes in this process, to handlers registered with `onWake()`.
122
+ - `interface ProcessSchedulerOptions`: The options of `processScheduler()`.
123
+ - `ProductRecordEntry`: re-exported from `@buildanagent/protocol`.
124
+ - `ProtocolError`: re-exported from `@buildanagent/protocol`.
125
+ - `ProtocolErrorCode`: re-exported from `@buildanagent/protocol`.
126
+ - `pruneKeys()`: Calls `store.prune(inUse)` and returns the ids it removed.
127
+ - `quorumOf()`: A policy that needs `needed` allows from distinct approvers, named by `Resolution.by`.
128
+ - `interface QuorumPolicy`: Decides when a request has enough answers.
129
+ - `type QuorumVerdict`: What a quorum policy says about one request: its answers are enough, not yet, a refusal, or too old.
130
+ - `rerunFrom()`: Re-runs from an entry: HEAD moves to `entryId` with a `checkout` entry, and a new turn follows it as a new branch of the same log.
131
+ - `resolveChecks()`: Finds what checks the task.
132
+ - `interface ResolvedChecks`: The checks to run, and whether the project named them or the harness found them.
133
+ - `interface ResolveOptions`: The settings a resume takes besides the answers: a turn's settings, and what the answers cover.
134
+ - `rotateKeys()`: Adds a new current key to `store` and returns its id.
135
+ - `runCompletionCheck()`: Runs the checks `start` resolved before the turn, in the sandbox, one after another and all of them even when one fails, and compares the workspace and the check config with `start`.
136
+ - `runTurn()`: Runs one turn on a session and writes it to the log.
137
+ - `SandboxTier`: re-exported from `@buildanagent/protocol`.
138
+ - `interface Scheduler`: Promises a wake at a time.
139
+ - `secretKeyStore()`: A `KeyStore` whose `load()` calls `read()` and parses the text it returns.
140
+ - `interface SecretKeyStoreOptions`: The options of `secretKeyStore()`.
141
+ - `class Session`: One session.
142
+ - `SESSION_ENTRY_TYPES`: re-exported from `@buildanagent/protocol`.
143
+ - `SessionEntry`: re-exported from `@buildanagent/protocol`.
144
+ - `SessionHeaderEntry`: re-exported from `@buildanagent/protocol`.
145
+ - `interface SessionIndex`: Where each session's current file is.
146
+ - `interface SessionKey`: Which session: its user and its id.
147
+ - `interface SessionLock`: Keeps two writers from extending one session's log at once.
148
+ - `interface SessionStore`: Where a session's entries live.
149
+ - `interface SessionSummary`: What `list()` says about a session, read from its header and its last entry.
150
+ - `ShadowCallEntry`: re-exported from `@buildanagent/protocol`.
151
+ - `SkillLoadedEntry`: re-exported from `@buildanagent/protocol`.
152
+ - `SNAPSHOT_TIMEOUT_MS`: How long the listing, and each file read, may take before the snapshot gives up on it.
153
+ - `interface SnapshotOptions`: What a snapshotter needs to run a command in the sandbox.
154
+ - `snapshotStart()`: Takes the turn's start state, once, before the run: it resolves the checks, reads the check config and snapshots the workspace.
155
+ - `type Snapshotter`: Takes a snapshot, or returns `undefined` when the workspace can't be listed, so no diff flags are raised.
156
+ - `SubagentLinkEntry`: re-exported from `@buildanagent/protocol`.
157
+ - `ToolResultEntry`: re-exported from `@buildanagent/protocol`.
158
+ - `TurnEndEntry`: re-exported from `@buildanagent/protocol`.
159
+ - `interface TurnOptions`: The options of one turn.
160
+ - `type TurnResult`: What a turn returns: the SDK's result, and where the turn left the log.
161
+ - `TurnStartEntry`: re-exported from `@buildanagent/protocol`.
162
+ - `UsageEntry`: re-exported from `@buildanagent/protocol`.
163
+ - `type WakeHandler`: What receives a wake: the id it was asked for and the time it was asked for.
164
+ - `interface WorkspaceSnapshot`: What the workspace held at one moment.
165
+
166
+ ## Exports from `@buildanagent/harness/session/jsonl`
167
+
168
+ - `defaultKeyPath()`: Where the ring is when no path is given: `$XDG_STATE_HOME/buildanagent/keys.json`, or under `~/.local/state`.
169
+ - `fileIndex()`: A pointer index in files under `options.dir`.
170
+ - `interface FileIndexOptions`: The options of `fileIndex()`.
171
+ - `fileKeyStore()`: A key ring in the file at `path` (default `defaultKeyPath()`).
172
+ - `fileLock()`: A `SessionLock` over lock files in `options.dir`.
173
+ - `interface FileLockOptions`: The options of `fileLock()` and `unlockSession()`.
174
+ - `jsonlStore()`: A store that keeps each session in `<dir>/<user>/<session>.jsonl`, one JSON entry per line.
175
+ - `interface JsonlStoreOptions`: The options of `jsonlStore()`.
176
+ - `type KeptReason`: Why an expired session was left alone.
177
+ - `interface LockRecord`: What a lock file holds.
178
+ - `interface PruneOptions`: The options of `pruneSessions()`.
179
+ - `interface PruneResult`: What `pruneSessions()` did, by session id.
180
+ - `pruneSessions()`: Expires the user's sessions: each one whose last entry is more than `retention.days` old is archived or purged, and with no `retention` nothing happens.
181
+ - `type RemovedLock`: What `unlockSession()` removed: the lock's record, or `"unreadable"` when the file held no valid record.
182
+ - `interface Retention`: How long to keep a session after its last entry, and what to do with it then.
183
+ - `unlockSession()`: Removes a session's lock whatever its state: the library behind `buildanagent session unlock --force`.
184
+
185
+ ## Exports from `@buildanagent/harness/context`
186
+
187
+ - `interface CompactEvent`: What `hooks.beforeCompact` receives: the span about to be summarised.
188
+ - `type CompactionLog`: Called with each record of a compaction or a skipped one.
189
+ - `interface CompactionRecord`: What a layer reports when it compacts or declines to.
190
+ - `interface ContextFill`: How full the request view is: an estimate, so a display can warn before the window does.
191
+ - `interface ContextHooks`: Hooks around a compaction.
192
+ - `interface ContextPolicy`: A context policy: the layers, built once and applied to every turn of a harness.
193
+ - `interface ContextPolicyOptions`: The settings of `createContextPolicy()`.
194
+ - `createContextPolicy()`: Creates a context policy.
195
+ - `cutoffFor()`: The message index before which tool results are masked: it moves forward in whole steps as the transcript grows.
196
+ - `type LayerName`: The five context layers, cheapest first.
197
+ - `maskMessages()`: The messages with every tool result before the cutoff masked, and where the cutoff stands.
198
+ - `memorySpillStore()`: A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`.
199
+ - `interface SpillStore`: Where the full text of a capped tool result goes, so the model keeps a pointer and nothing is lost.
200
+ - `interface SummarizeSettings`: The settings of the summary layer.
201
+ - `SUMMARY_PROMPT_VERSION`: The version of the template below.
202
+ - `interface TurnContext`: The policy's hooks and state for one turn.
203
+ - `interface TurnContextOptions`: What the policy knows about one turn.
204
+
205
+ ## Exports from `@buildanagent/harness/context/file`
206
+
207
+ - `fileSpillStore()`: A spill store that writes `<dir>/<user>/<session>/<callId>.txt` and returns that path.
208
+
209
+ ## Exports from `@buildanagent/harness/tools`
210
+
211
+ - `type ApprovalReuse`: Which approvals may cover later calls: a sticky one, a grouped one, both, or none, so each call asks.
212
+ - `createToolRegistry()`: Creates an empty registry.
213
+ - `class DuplicateToolError`: Thrown by `register()` when a registry already holds a tool, or an alias, by that name.
214
+ - `type HostPattern`: How a tool's code is reached: in this process, or by asking the client through a `tool/call` server request.
215
+ - `type OutputTrust`: Whether a tool's output may carry instructions an attacker wrote.
216
+ - `interface PreambleOptions`: The options of `preambleTokens()`.
217
+ - `interface RegisteredTool`: A tool as the registry holds it, with its canonical name and every default resolved.
218
+ - `type ToolExposure`: Whether a request sends the tool: `direct` always, `deferred` once tool search names it, `hidden` only when named.
219
+ - `interface ToolRegistration`: What `register()` takes: the tool, where it comes from, and any default it overrides.
220
+ - `interface ToolRegistry`: One registry for the tools of every source.
221
+ - `toolSearchInterceptors()`: The interceptor that sends what tool search activated.
222
+ - `interface ToolSearchOptions`: The options of `toolSearchTool()`.
223
+ - `toolSearchTool()`: The `tool_search` tool: it searches the registry's `deferred` tools by the words of a query, records the best matches in `options.activated` and tells the model their names, plus the descriptions of trusted tools.
224
+ - `type ToolSource`: Where a tool comes from: the harness, an in-process extension, one MCP server (`mcp:<server>`) or the client.
225
+ - `type ToolWrapper`: Wraps one registered tool's definition for a turn: a write cap, shadow mode or a sandbox binding, with the turn's host context.
226
+
227
+ ## Exports from `@buildanagent/harness/mcp`
228
+
229
+ - `connectMcpServer()`: Connects one server and negotiates its era.
230
+ - `createMcpManager()`: Creates the MCP client for a set of servers.
231
+ - `killMcpServersOnSignal()`: Opts this process in to ending every MCP server on `SIGINT`, `SIGTERM` or `SIGHUP`, for a host whose process those signals end, such as a one-shot command.
232
+ - `type McpCallFailure`: Why an MCP tool call ended without a result.
233
+ - `interface McpCallResult`: What one tool call returned.
234
+ - `interface McpChannel`: A message channel to a server in this process, such as an `InMemoryTransport` from `@modelcontextprotocol/server`.
235
+ - `interface McpConnection`: One connected server.
236
+ - `type McpEra`: The protocol era a server speaks: the 2026-07-28 revision, or `legacy` for the 2025 revisions and their `initialize`.
237
+ - `class McpError`: Thrown for a server that could not connect (`mcp_connect_failed`), a tool list the harness refuses (`mcp_tool_list_refused`) and a tool call that ended with no result (`mcp_call_failed`, with `failure` saying why).
238
+ - `interface McpInProcessTransport`: A server in this process, reached through a channel the host built.
239
+ - `interface McpManager`: The MCP client as one removable component: it connects the servers and registers their tools.
240
+ - `interface McpManagerOptions`: What `createMcpManager()` takes.
241
+ - `interface McpServerConfig`: One MCP server the harness connects to.
242
+ - `type McpServerStatus`: How one server's connection went.
243
+ - `interface McpStdioTransport`: A server the harness starts as a child process and speaks to over its standard input and output, one JSON message per line.
244
+ - `interface McpTool`: A tool as a server lists it.
245
+
246
+ ## Exports from `@buildanagent/harness/permissions`
247
+
248
+ - `createPermissionPipeline()`: Creates the pipeline.
249
+ - `interface Decision`: The pipeline's decision on one call.
250
+ - `defaultAskRules`: The ask rules the harness ships: a change to a test file, and a change to a hook, CI configuration or a rules file.
251
+ - `interface HookDecision`: What a hook may return: a refusal or a question, never an allow.
252
+ - `interface PermissionConfig`: The pipeline's settings.
253
+ - `class PermissionConfigError`: Thrown when a permission configuration could never work as written.
254
+ - `type PermissionHook`: A hook that can deny or ask about a call and cannot allow it, by type and at run time.
255
+ - `PermissionMode`: re-exported from `@buildanagent/protocol`.
256
+ - `interface PermissionPipeline`: The pipeline `createPermissionPipeline()` returns.
257
+ - `interface PolicyContext`: What a hook or the host callback receives: `PolicyInput` plus the pipeline's own mode and policy version.
258
+ - `interface PolicyInput`: What a decision may read: the session, the turn's host context and the session's entries.
259
+ - `interface PolicySession`: The part of a session the permission code needs: somewhere to append the entries it writes.
260
+ - `type RecordedEntry`: The entries the permission code writes.
261
+ - `interface Rule`: A rule that matches tool calls.
262
+ - `interface ToolCall`: One tool call to decide.
263
+
264
+ ## Exports from `@buildanagent/harness/sandbox`
265
+
266
+ - `type ApprovalPolicy`: When a denied action may be asked for again, which is the host's decision and never the sandbox's.
267
+ - `interface ExecOptions`: The options of `Sandbox.exec()`.
268
+ - `type ExecResult`: What a command did: its exit status and output, or the denial that stopped it.
269
+ - `NONE_SANDBOX_WARNING`: The warning written when a sandbox starts.
270
+ - `noneSandbox()`: Builds the `none` backend.
271
+ - `interface NoneSandboxOptions`: The options of `noneSandbox()`.
272
+ - `interface Sandbox`: A provisioned sandbox.
273
+ - `interface SandboxClient`: A sandbox backend.
274
+ - `interface SandboxDenial`: What the policy refused.
275
+ - `class SandboxDeniedError`: Thrown when the policy refuses a file read or write.
276
+ - `interface SandboxPolicy`: What a sandbox may touch.
277
+ - `type SandboxStop`: What a backend claims to stop.
278
+ - `type SandboxTier`: How strongly a backend confines a process.
279
+ - `class SandboxUnavailableError`: Thrown by `provision()` when a backend can't start, such as a missing binary.
280
+ - `spawnEnv()`: The environment for a spawned process: `PATH`, a fresh temp `HOME`, `TMPDIR` and `LANG`, plus the parent variables named in `allow` that are set, plus every `extra`.
281
+ - `interface WorkspaceManifest`: The workspace a sandbox is provisioned for: its root directory and the files to put there first.
282
+
283
+ ## Exports from `@buildanagent/harness/sandbox/srt`
284
+
285
+ - `SRT_ADDED_ENVIRONMENT`: The variables `srt` 0.0.83 adds to a command's environment, which are its proxy settings and the few that go with them.
286
+ - `SRT_SYSTEM_READ_ROOTS`: The system folders a program needs to start.
287
+ - `interface SrtPathEntry`: A path that `srt` must read as written.
288
+ - `srtSandbox()`: Builds the `srt` backend.
289
+ - `interface SrtSandboxOptions`: The options of `srtSandbox()`.
290
+ - `srtSettings()`: Denies every read and then allows the policy's read and write roots, the system folders and the helper folders back.
291
+ - `interface SrtSettings`: The settings `srt` reads from its `--settings` file.
292
+ - `interface SrtSettingsInput`: What the settings are built from, beyond the policy.
293
+
294
+ ## Exports from `@buildanagent/harness/sandbox/docker`
295
+
296
+ - `DOCKER_PROXY_SOCKET_PATH`: Where a command finds the proxy socket, when the caller mounts one.
297
+ - `dockerSandbox()`: Builds the Docker backend.
298
+ - `interface DockerSandboxOptions`: The options of `dockerSandbox()`.
299
+
300
+ ## Exports from `@buildanagent/harness/credentials`
301
+
302
+ - `interface CredentialRoute`: One credential route: where a request for `/<route>/…` goes, and how the proxy adds the credential.
303
+ - `interface EgressProxy`: A running egress proxy.
304
+ - `interface EgressProxyOptions`: The options of `startEgressProxy()`.
305
+ - `interface EgressRecord`: One line of the egress log.
306
+ - `isAddressLiteral()`: Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up.
307
+ - `isPublicAddress()`: Whether `address` is a public one a proxy may connect to.
308
+ - `REDACTED`: What replaces a secret.
309
+ - `scrubSecrets()`: Returns a copy of `entry` with every secret replaced by `[REDACTED]`, in every string value and every key, at any depth.
310
+ - `startEgressProxy()`: Starts the egress proxy on `127.0.0.1` with a port the system picks, or on `socketPath`.
311
+
312
+ ## Exports from `@buildanagent/harness/extensions`
313
+
314
+ - `composeExtensions()`: Joins the extensions' interceptors, in the order given, by the SDK's composition rules, and their observers.
315
+ - `CONTEXT_FILE_MAX_BYTES`: The most bytes of one context, plan or progress file the harness reads.
316
+ - `CONTEXT_FILES_MAX_TOTAL_BYTES`: The most bytes of all the `AGENTS.md` and `CLAUDE.md` files together, as UTF-8.
317
+ - `interface ContextFile`: One `AGENTS.md` or `CLAUDE.md` the project holds.
318
+ - `contextText()`: The text of the leading block: a note saying what it is, then each file in its own labelled section.
319
+ - `interface Extension`: An in-process extension: hooks and tools that run in the harness's own process with its permissions.
320
+ - `interface ExtensionLoadedRecord`: What the log records about a loaded extension, so a session shows which code ran.
321
+ - `type ExtensionTool`: One tool an extension adds.
322
+ - `memoryTrustStore()`: A trust store in memory, for tests and for a host that decides trust itself.
323
+ - `type ParsedSkill`: What `parseSkill()` makes of one file: the skill, or why the file is not one.
324
+ - `parseSkill()`: Reads one `SKILL.md`.
325
+ - `PLAN_FILE`: The plan file, relative to the project root.
326
+ - `interface PlanFiles`: What a plan source found: the text of each file that exists, and a note for each that could not be used.
327
+ - `planPrompt()`: The system prompt's account of the plan files, for a task too long for one context.
328
+ - `type PlanSource`: Reads the plan and progress files.
329
+ - `PROGRESS_FILE`: The progress file, relative to the project root.
330
+ - `projectContext()`: An extension that puts the context files, and the plan and progress files, at the start of every request.
331
+ - `interface ProjectContextOptions`: The settings of `projectContext()`.
332
+ - `recordsOf()`: The records for extensions written in code: their hash covers the name and version, since there are no files.
333
+ - `registerExtensionTools()`: Registers every extension's tools in `registry` with source `extension`.
334
+ - `sha256()`: The digest of `data`, as `sha256:` and hex.
335
+ - `interface Skill`: A skill as the system prompt lists it: the body stays in the file.
336
+ - `SKILL_DESCRIPTION_MAX`: The longest skill description, in characters.
337
+ - `SKILL_NAME_MAX`: The longest skill name, in characters.
338
+ - `skillOfRead()`: The skill whose `SKILL.md` a `read` call opens, or `undefined`.
339
+ - `skillsPrompt()`: The `## Skills` section a system prompt carries: each skill's name, description and path, and never its body.
340
+ - `interface TrustStore`: Which project folders may load their own extensions.
341
+ - `withPlanConvention()`: `system` followed by the plan-file convention.
342
+ - `withSkills()`: `system` followed by the skills section, or `system` alone when there are no skills.
343
+
344
+ ## Exports from `@buildanagent/harness/extensions/node`
345
+
346
+ - `contextFiles()`: Reads the `AGENTS.md` and `CLAUDE.md` of `cwd` and of every folder above it up to the repository root (the first folder with a `.git`; with none, `cwd` alone).
347
+ - `interface DiscoveredSkills`: The skills found, what to record about them, and why any were left out.
348
+ - `discoverSkills()`: Finds the skills of the project `cwd` is in: each folder under `.agents/skills` holding a `SKILL.md`, in `cwd` and every folder above it up to the repository root (the first folder with a `.git`).
349
+ - `interface DiscoverSkillsOptions`: The settings of `discoverSkills()`.
350
+ - `fileTrustStore()`: A trust store in the file at `file`, created on the first `trust()`.
351
+ - `interface FoundContextFiles`: The context files found, and why any were skipped.
352
+ - `hashExtensionDir()`: The hash of an extension folder: `sha256:` and the digest over each file's path and content digest, in sorted order.
353
+ - `interface LoadOptions`: What `loadProjectExtensions()` needs to decide.
354
+ - `loadProjectExtensions()`: Loads the extensions in a project, or skips them with a notice.
355
+ - `pinProjectExtensions()`: Writes the lock file for every extension folder as it is now.
356
+ - `planFileSource()`: A plan source that reads `.agents/plan.md` and `.agents/progress.json` under `root` each time it is called.
357
+ - `interface ProjectExtensions`: The extensions a project supplied, what to record about them, and why any were skipped.
358
+ - `readLock()`: The pins in a lock file, by extension folder name, or `undefined` when there is no lock file.
359
+ - `realPathTrustStore()`: A trust store in memory, for tests and for a host that decides trust itself, that resolves each folder to its real path when the store is built and when `trust()` adds it.
360
+ - `writeLock()`: Writes the lock file for these pins, replacing the old one in one step.
361
+
362
+ ## Exports from `@buildanagent/harness/memory`
363
+
364
+
365
+ ## Exports from `@buildanagent/harness/telemetry`
366
+
367
+
368
+ ## Exports from `@buildanagent/harness/server`
369
+
370
+ - `interface CodeCall`: A tool call that the host's own code makes with `Harness.invokeTool()`, with no model step.
371
+ - `type CodeCallResult`: What a code call ended in.
372
+ - `interface Connection`: One client's end of the dispatcher: send it messages, and it calls back with what the server sends.
373
+ - `interface ConnectOptions`: What `Dispatcher.connect()` takes besides `send`.
374
+ - `createDispatcher()`: Creates the dispatcher that serves `options.harness` over the protocol's commands.
375
+ - `createHarness()`: Creates a harness.
376
+ - `type Deliver`: Takes one message.
377
+ - `interface Dispatcher`: The dispatcher `createDispatcher()` returns.
378
+ - `interface DispatcherOptions`: The settings of `createDispatcher()`.
379
+ - `EXPERIMENTAL_METHODS`: The methods a client must opt into, by listing each in the `capabilities` of its `initialize`.
380
+ - `interface Harness`: A harness: its options with the defaults filled in.
381
+ - `interface HarnessEnv`: What the session's `env_stamp` records about where the turns run.
382
+ - `interface HarnessOptions`: The options of `createHarness()`.
383
+ - `interface InProcessClient`: What a client sees: calls that resolve with a result, the server's messages, and a way to answer its requests.
384
+ - `inProcessTransport()`: Connects a new client to `dispatcher`.
385
+ - `interface NodeInput`: A Node `Readable` as the transport reads it, such as `process.stdin`.
386
+ - `interface NodeOutput`: A Node `Writable` as the transport writes to it, such as `process.stdout`.
387
+ - `interface RequestOptions`: What `InProcessClient.request()` takes besides the method and its params.
388
+ - `class RpcFailure`: A command the server answered with an error.
389
+ - `type StdioInput`: The bytes the transport reads: a Node `Readable` such as `process.stdin`, or a Web `ReadableStream`.
390
+ - `interface StdioIo`: The streams `stdioTransport()` serves a client over.
391
+ - `interface StdioOptions`: What `stdioTransport()` takes besides the dispatcher and the streams.
392
+ - `type StdioOutput`: Where the transport writes: a Node `Writable` such as `process.stdout`, or a Web `WritableStream`.
393
+ - `stdioTransport()`: Serves one client over a pair of byte streams, one JSON-RPC 2.0 message per line, and resolves once the client is done.
394
+ - `interface WebSocketCloseEvent`: A close event as the transport reads it.
395
+ - `interface WebSocketLike`: A WebSocket as the transport uses it: the methods of the standard `WebSocket` interface, which the global `WebSocket` of Node and browsers fits.
396
+ - `interface WebSocketMessageEvent`: A message event as the transport reads it: `data` is a string for a text frame and anything else for binary.
397
+ - `interface WebSocketOptions`: What `webSocketTransport()` takes besides the dispatcher and the socket.
398
+ - `webSocketTransport()`: Serves one client over one open WebSocket, one JSON-RPC 2.0 message per text frame, and resolves once the client is gone or the transport stops.
399
+
400
+ ## Exports from `@buildanagent/harness/ablation`
401
+
402
+
403
+ ## Exports from `@buildanagent/harness/testing`
404
+
405
+ - `interface DeliveredWake`: One wake a scheduler delivered.
406
+ - `FAKE_COMMANDS`: The commands the fake runs, in the form `[name, ...arguments]`: `echo` prints its arguments, `env` prints the environment it was given as `NAME=value` lines, `cat <path>` prints a file, `write <path> <text>` writes one, `true` and `false` exit with 0 and 1, `sleep <seconds>` waits and honours the timeout and the signal, and `net-probe <host>` reaches a host only if the policy allows it.
407
+ - `fakeSandbox()`: Builds a fake backend with the tier `os` and the stops `mistakes` and `exfiltration`, because it enforces the policy's file roots and network allowlist in memory.
408
+ - `interface FakeSandboxClient`: A fake backend, and what it has seen.
409
+ - `interface FakeSandboxOptions`: The options of `fakeSandbox()`.
410
+ - `type KeyStoreCase`: One key store case.
411
+ - `keyStoreConformanceCases()`: The cases, each run against a store from `factory`.
412
+ - `type KeyStoreConformanceReport`: What `runKeyStoreConformance()` reports.
413
+ - `type KeyStoreFactory`: Makes a fresh store for each case.
414
+ - `interface KeyStoreUnderTest`: What a factory returns: the store under test.
415
+ - `interface RecordedExec`: One command the fake received, with what the caller passed.
416
+ - `runKeyStoreConformance()`: Runs every case and reports which passed, which skipped and which failed.
417
+ - `runSandboxConformance()`: Runs every case against backends from `factory` and reports which passed, which skipped with a reason and which failed.
418
+ - `runSchedulerConformance()`: Runs every case and reports which passed, which skipped and which failed.
419
+ - `runStoreConformance()`: Runs every case and reports which passed, which skipped with a reason and which failed.
420
+ - `type SandboxCase`: One case of the sandbox conformance suite, which a runner can register as a test of its own.
421
+ - `sandboxConformanceCases()`: The cases, for a backend from `factory`.
422
+ - `interface SandboxConformanceOptions`: The options of the suite.
423
+ - `type SandboxConformanceReport`: The report the sandbox conformance suite returns: which cases passed, which skipped with a reason and which failed.
424
+ - `type SandboxFactory`: Makes a fresh backend and workspace for each case.
425
+ - `interface SandboxUnderTest`: What a factory returns: the backend, and the absolute folder to use as the workspace root.
426
+ - `type SchedulerCase`: One case of the scheduler conformance suite, which a runner can register as a test of its own.
427
+ - `schedulerConformanceCases()`: The cases, each run against a scheduler from `factory`.
428
+ - `type SchedulerConformanceReport`: The report the scheduler conformance suite returns: which cases passed, which skipped with a reason and which failed.
429
+ - `type SchedulerFactory`: Makes a fresh scheduler for each case.
430
+ - `interface SchedulerUnderTest`: What a factory returns: the scheduler, and the means to move its clock and read what it delivered.
431
+ - `type StoreCase`: One case of the store conformance suite, which a runner can register as a test of its own.
432
+ - `storeConformanceCases()`: Every conformance case, each against a store from `factory`.
433
+ - `type StoreConformanceReport`: The report the store conformance suite returns: which cases passed, which skipped with a reason and which failed.
434
+ - `type StoreFactory`: Makes a fresh store for each case.
435
+ - `interface StoreUnderTest`: What a factory returns: a fresh, empty store, and optionally a way to tear a log's last line.
package/package.json CHANGED
@@ -1,6 +1,121 @@
1
1
  {
2
2
  "name": "@buildanagent/harness",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-alpha.28",
4
+ "description": "The buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop.",
5
+ "license": "Apache-2.0 OR MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/laudebugs/buildanagent.git",
9
+ "directory": "packages/harness"
10
+ },
11
+ "homepage": "https://github.com/laudebugs/buildanagent/tree/main/packages/harness#readme",
12
+ "type": "module",
13
+ "sideEffects": false,
14
+ "engines": {
15
+ "node": ">=22.19.0"
16
+ },
17
+ "files": [
18
+ "dist",
19
+ "llms.txt",
20
+ "LICENSE",
21
+ "LICENSE-APACHE",
22
+ "LICENSE-MIT"
23
+ ],
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.ts",
27
+ "default": "./dist/index.js"
28
+ },
29
+ "./session": {
30
+ "types": "./dist/session/index.d.ts",
31
+ "default": "./dist/session/index.js"
32
+ },
33
+ "./session/jsonl": {
34
+ "types": "./dist/session/jsonl.d.ts",
35
+ "default": "./dist/session/jsonl.js"
36
+ },
37
+ "./context": {
38
+ "types": "./dist/context/index.d.ts",
39
+ "default": "./dist/context/index.js"
40
+ },
41
+ "./context/file": {
42
+ "types": "./dist/context/file-spill.d.ts",
43
+ "default": "./dist/context/file-spill.js"
44
+ },
45
+ "./tools": {
46
+ "types": "./dist/tools/index.d.ts",
47
+ "default": "./dist/tools/index.js"
48
+ },
49
+ "./mcp": {
50
+ "types": "./dist/mcp/index.d.ts",
51
+ "default": "./dist/mcp/index.js"
52
+ },
53
+ "./permissions": {
54
+ "types": "./dist/permissions/index.d.ts",
55
+ "default": "./dist/permissions/index.js"
56
+ },
57
+ "./sandbox": {
58
+ "types": "./dist/sandbox/index.d.ts",
59
+ "default": "./dist/sandbox/index.js"
60
+ },
61
+ "./sandbox/srt": {
62
+ "types": "./dist/sandbox/srt/index.d.ts",
63
+ "default": "./dist/sandbox/srt/index.js"
64
+ },
65
+ "./sandbox/docker": {
66
+ "types": "./dist/sandbox/docker/index.d.ts",
67
+ "default": "./dist/sandbox/docker/index.js"
68
+ },
69
+ "./credentials": {
70
+ "types": "./dist/credentials/index.d.ts",
71
+ "default": "./dist/credentials/index.js"
72
+ },
73
+ "./extensions": {
74
+ "types": "./dist/extensions/index.d.ts",
75
+ "default": "./dist/extensions/index.js"
76
+ },
77
+ "./extensions/node": {
78
+ "types": "./dist/extensions/node.d.ts",
79
+ "default": "./dist/extensions/node.js"
80
+ },
81
+ "./memory": {
82
+ "types": "./dist/memory/index.d.ts",
83
+ "default": "./dist/memory/index.js"
84
+ },
85
+ "./telemetry": {
86
+ "types": "./dist/telemetry/index.d.ts",
87
+ "default": "./dist/telemetry/index.js"
88
+ },
89
+ "./server": {
90
+ "types": "./dist/server/index.d.ts",
91
+ "default": "./dist/server/index.js"
92
+ },
93
+ "./ablation": {
94
+ "types": "./dist/ablation.d.ts",
95
+ "default": "./dist/ablation.js"
96
+ },
97
+ "./testing": {
98
+ "types": "./dist/testing/index.d.ts",
99
+ "default": "./dist/testing/index.js"
100
+ }
101
+ },
102
+ "dependencies": {
103
+ "@anthropic-ai/sandbox-runtime": "0.0.83",
104
+ "@earendil-works/pi-schema": "1.5.2",
105
+ "@modelcontextprotocol/client": "2.4.0",
106
+ "@buildanagent/agent-safety": "0.1.0-alpha.28",
107
+ "@buildanagent/gateway": "0.1.0-alpha.28",
108
+ "@buildanagent/sdk": "0.1.0-alpha.28",
109
+ "@buildanagent/protocol": "0.1.0-alpha.28"
110
+ },
111
+ "devDependencies": {
112
+ "@modelcontextprotocol/server": "2.4.0",
113
+ "json-rpc-2.0": "1.8.1"
114
+ },
115
+ "scripts": {
116
+ "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
117
+ "typecheck": "tsc -p tsconfig.json",
118
+ "test": "vitest run",
119
+ "test:sandbox": "HARNESS_TEST_SANDBOX=1 vitest run test/sandbox/srt.test.ts test/sandbox/docker.test.ts"
120
+ }
6
121
  }