@nexum-hub/agent 0.0.0-stage → 0.0.1

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 (343) hide show
  1. package/README.md +129 -2
  2. package/contracts/v2/common.schema.json +262 -0
  3. package/contracts/v2/fixtures/inputs.json +244 -0
  4. package/contracts/v2/fixtures/wire.json +6493 -0
  5. package/contracts/v2/model/agent.close.input.schema.json +14 -0
  6. package/contracts/v2/model/agent.close.output.schema.json +101 -0
  7. package/contracts/v2/model/agent.list.input.schema.json +57 -0
  8. package/contracts/v2/model/agent.list.output.schema.json +220 -0
  9. package/contracts/v2/model/agent.open.input.schema.json +35 -0
  10. package/contracts/v2/model/agent.open.output.schema.json +41 -0
  11. package/contracts/v2/model/agent.run.cancel.input.schema.json +18 -0
  12. package/contracts/v2/model/agent.run.cancel.output.schema.json +100 -0
  13. package/contracts/v2/model/agent.run.get.input.schema.json +41 -0
  14. package/contracts/v2/model/agent.run.get.output.schema.json +100 -0
  15. package/contracts/v2/model/agent.run.input.input.schema.json +30 -0
  16. package/contracts/v2/model/agent.run.input.output.schema.json +100 -0
  17. package/contracts/v2/model/agent.run.list.input.schema.json +47 -0
  18. package/contracts/v2/model/agent.run.list.output.schema.json +41 -0
  19. package/contracts/v2/model/agent.run.start.input.schema.json +73 -0
  20. package/contracts/v2/model/agent.run.start.output.schema.json +100 -0
  21. package/contracts/v2/wire/bodies.schema.json +383 -0
  22. package/contracts/v2/wire/envelope.schema.json +2280 -0
  23. package/contracts/v2/wire/events.schema.json +242 -0
  24. package/contracts/v2/wire/maintenance.schema.json +308 -0
  25. package/contracts/v2/wire/operations.schema.json +1791 -0
  26. package/contracts/v2/wire/stream.schema.json +74 -0
  27. package/contracts/v2/wire/types.schema.json +2616 -0
  28. package/dist/adapters/mcp-http.d.ts +22 -0
  29. package/dist/adapters/mcp-http.js +472 -0
  30. package/dist/adapters/mcp-http.js.map +1 -0
  31. package/dist/adapters/mcp-oauth.d.ts +29 -0
  32. package/dist/adapters/mcp-oauth.js +653 -0
  33. package/dist/adapters/mcp-oauth.js.map +1 -0
  34. package/dist/adapters/mcp-wire.d.ts +21 -0
  35. package/dist/adapters/mcp-wire.js +307 -0
  36. package/dist/adapters/mcp-wire.js.map +1 -0
  37. package/dist/adapters/mcp.d.ts +56 -0
  38. package/dist/adapters/mcp.js +1989 -0
  39. package/dist/adapters/mcp.js.map +1 -0
  40. package/dist/adapters/openapi-http.d.ts +29 -0
  41. package/dist/adapters/openapi-http.js +504 -0
  42. package/dist/adapters/openapi-http.js.map +1 -0
  43. package/dist/adapters/openapi-request.d.ts +26 -0
  44. package/dist/adapters/openapi-request.js +597 -0
  45. package/dist/adapters/openapi-request.js.map +1 -0
  46. package/dist/adapters/openapi-schema.d.ts +22 -0
  47. package/dist/adapters/openapi-schema.js +471 -0
  48. package/dist/adapters/openapi-schema.js.map +1 -0
  49. package/dist/adapters/openapi-typegen.d.ts +11 -0
  50. package/dist/adapters/openapi-typegen.js +185 -0
  51. package/dist/adapters/openapi-typegen.js.map +1 -0
  52. package/dist/adapters/openapi-types.d.ts +99 -0
  53. package/dist/adapters/openapi-types.js +2 -0
  54. package/dist/adapters/openapi-types.js.map +1 -0
  55. package/dist/adapters/openapi.d.ts +7 -0
  56. package/dist/adapters/openapi.js +768 -0
  57. package/dist/adapters/openapi.js.map +1 -0
  58. package/dist/application/activation.d.ts +28 -0
  59. package/dist/application/activation.js +289 -0
  60. package/dist/application/activation.js.map +1 -0
  61. package/dist/application/attachments.d.ts +24 -0
  62. package/dist/application/attachments.js +87 -0
  63. package/dist/application/attachments.js.map +1 -0
  64. package/dist/application/authority.d.ts +32 -0
  65. package/dist/application/authority.js +213 -0
  66. package/dist/application/authority.js.map +1 -0
  67. package/dist/application/catalog.d.ts +11 -0
  68. package/dist/application/catalog.js +177 -0
  69. package/dist/application/catalog.js.map +1 -0
  70. package/dist/application/config.d.ts +24 -0
  71. package/dist/application/config.js +140 -0
  72. package/dist/application/config.js.map +1 -0
  73. package/dist/application/connection.d.ts +35 -0
  74. package/dist/application/connection.js +465 -0
  75. package/dist/application/connection.js.map +1 -0
  76. package/dist/application/data-plane.d.ts +35 -0
  77. package/dist/application/data-plane.js +437 -0
  78. package/dist/application/data-plane.js.map +1 -0
  79. package/dist/application/diagnostics.d.ts +4 -0
  80. package/dist/application/diagnostics.js +65 -0
  81. package/dist/application/diagnostics.js.map +1 -0
  82. package/dist/application/dispatcher.d.ts +4 -0
  83. package/dist/application/dispatcher.js +16 -0
  84. package/dist/application/dispatcher.js.map +1 -0
  85. package/dist/application/main.d.ts +12 -0
  86. package/dist/application/main.js +167 -0
  87. package/dist/application/main.js.map +1 -0
  88. package/dist/application/maintenance.d.ts +27 -0
  89. package/dist/application/maintenance.js +244 -0
  90. package/dist/application/maintenance.js.map +1 -0
  91. package/dist/application/packages.d.ts +25 -0
  92. package/dist/application/packages.js +208 -0
  93. package/dist/application/packages.js.map +1 -0
  94. package/dist/application/processes.d.ts +49 -0
  95. package/dist/application/processes.js +180 -0
  96. package/dist/application/processes.js.map +1 -0
  97. package/dist/application/run-view.d.ts +17 -0
  98. package/dist/application/run-view.js +286 -0
  99. package/dist/application/run-view.js.map +1 -0
  100. package/dist/application/runtime.d.ts +78 -0
  101. package/dist/application/runtime.js +1747 -0
  102. package/dist/application/runtime.js.map +1 -0
  103. package/dist/application/tasks.d.ts +38 -0
  104. package/dist/application/tasks.js +23 -0
  105. package/dist/application/tasks.js.map +1 -0
  106. package/dist/application/user-state.d.ts +20 -0
  107. package/dist/application/user-state.js +52 -0
  108. package/dist/application/user-state.js.map +1 -0
  109. package/dist/application/work-git.d.ts +14 -0
  110. package/dist/application/work-git.js +67 -0
  111. package/dist/application/work-git.js.map +1 -0
  112. package/dist/cli.d.ts +2 -0
  113. package/dist/cli.js +40 -0
  114. package/dist/cli.js.map +1 -0
  115. package/dist/contracts/caller.d.ts +51 -0
  116. package/dist/contracts/caller.js +95 -0
  117. package/dist/contracts/caller.js.map +1 -0
  118. package/dist/contracts/error-data.d.ts +6 -0
  119. package/dist/contracts/error-data.js +51 -0
  120. package/dist/contracts/error-data.js.map +1 -0
  121. package/dist/contracts/errors.d.ts +10 -0
  122. package/dist/contracts/errors.js +28 -0
  123. package/dist/contracts/errors.js.map +1 -0
  124. package/dist/contracts/json.d.ts +9 -0
  125. package/dist/contracts/json.js +104 -0
  126. package/dist/contracts/json.js.map +1 -0
  127. package/dist/contracts/types.d.ts +122 -0
  128. package/dist/contracts/types.js +19 -0
  129. package/dist/contracts/types.js.map +1 -0
  130. package/dist/contracts/validation.d.ts +4 -0
  131. package/dist/contracts/validation.js +157 -0
  132. package/dist/contracts/validation.js.map +1 -0
  133. package/dist/contracts/wire-validation.d.ts +9 -0
  134. package/dist/contracts/wire-validation.js +399 -0
  135. package/dist/contracts/wire-validation.js.map +1 -0
  136. package/dist/contracts/wire.d.ts +1083 -0
  137. package/dist/contracts/wire.js +62 -0
  138. package/dist/contracts/wire.js.map +1 -0
  139. package/dist/extension-api.d.ts +12 -0
  140. package/dist/extension-api.js +2 -0
  141. package/dist/extension-api.js.map +1 -0
  142. package/dist/extensions/api.d.ts +72 -0
  143. package/dist/extensions/api.js +2 -0
  144. package/dist/extensions/api.js.map +1 -0
  145. package/dist/extensions/host-requests.d.ts +23 -0
  146. package/dist/extensions/host-requests.js +60 -0
  147. package/dist/extensions/host-requests.js.map +1 -0
  148. package/dist/extensions/materials.d.ts +37 -0
  149. package/dist/extensions/materials.js +691 -0
  150. package/dist/extensions/materials.js.map +1 -0
  151. package/dist/extensions/package-loader.d.ts +28 -0
  152. package/dist/extensions/package-loader.js +177 -0
  153. package/dist/extensions/package-loader.js.map +1 -0
  154. package/dist/extensions/packages.d.ts +73 -0
  155. package/dist/extensions/packages.js +441 -0
  156. package/dist/extensions/packages.js.map +1 -0
  157. package/dist/extensions/registry.d.ts +92 -0
  158. package/dist/extensions/registry.js +1540 -0
  159. package/dist/extensions/registry.js.map +1 -0
  160. package/dist/extensions/resources.d.ts +105 -0
  161. package/dist/extensions/resources.js +595 -0
  162. package/dist/extensions/resources.js.map +1 -0
  163. package/dist/extensions/state.d.ts +25 -0
  164. package/dist/extensions/state.js +10 -0
  165. package/dist/extensions/state.js.map +1 -0
  166. package/dist/extensions/transfer.d.ts +81 -0
  167. package/dist/extensions/transfer.js +16 -0
  168. package/dist/extensions/transfer.js.map +1 -0
  169. package/dist/index.d.ts +7 -0
  170. package/dist/index.js +25 -0
  171. package/dist/index.js.map +1 -0
  172. package/dist/maintenance/configuration.d.ts +79 -0
  173. package/dist/maintenance/configuration.js +1503 -0
  174. package/dist/maintenance/configuration.js.map +1 -0
  175. package/dist/maintenance/credentials.d.ts +23 -0
  176. package/dist/maintenance/credentials.js +177 -0
  177. package/dist/maintenance/credentials.js.map +1 -0
  178. package/dist/maintenance/files.d.ts +2 -0
  179. package/dist/maintenance/files.js +40 -0
  180. package/dist/maintenance/files.js.map +1 -0
  181. package/dist/maintenance/npm.d.ts +71 -0
  182. package/dist/maintenance/npm.js +1013 -0
  183. package/dist/maintenance/npm.js.map +1 -0
  184. package/dist/maintenance/oauth.d.ts +45 -0
  185. package/dist/maintenance/oauth.js +686 -0
  186. package/dist/maintenance/oauth.js.map +1 -0
  187. package/dist/maintenance/requests.d.ts +347 -0
  188. package/dist/maintenance/requests.js +959 -0
  189. package/dist/maintenance/requests.js.map +1 -0
  190. package/dist/maintenance/work-git.d.ts +29 -0
  191. package/dist/maintenance/work-git.js +776 -0
  192. package/dist/maintenance/work-git.js.map +1 -0
  193. package/dist/process/backend.d.ts +54 -0
  194. package/dist/process/backend.js +39 -0
  195. package/dist/process/backend.js.map +1 -0
  196. package/dist/process/environment-windows.d.ts +15 -0
  197. package/dist/process/environment-windows.js +151 -0
  198. package/dist/process/environment-windows.js.map +1 -0
  199. package/dist/process/environment.d.ts +28 -0
  200. package/dist/process/environment.js +410 -0
  201. package/dist/process/environment.js.map +1 -0
  202. package/dist/process/launch.d.ts +31 -0
  203. package/dist/process/launch.js +281 -0
  204. package/dist/process/launch.js.map +1 -0
  205. package/dist/process/managed.d.ts +36 -0
  206. package/dist/process/managed.js +459 -0
  207. package/dist/process/managed.js.map +1 -0
  208. package/dist/process/output-log.d.ts +50 -0
  209. package/dist/process/output-log.js +552 -0
  210. package/dist/process/output-log.js.map +1 -0
  211. package/dist/process/pipes.d.ts +16 -0
  212. package/dist/process/pipes.js +588 -0
  213. package/dist/process/pipes.js.map +1 -0
  214. package/dist/process/pty.d.ts +22 -0
  215. package/dist/process/pty.js +512 -0
  216. package/dist/process/pty.js.map +1 -0
  217. package/dist/process/windows-conout-worker.d.ts +1 -0
  218. package/dist/process/windows-conout-worker.js +90 -0
  219. package/dist/process/windows-conout-worker.js.map +1 -0
  220. package/dist/process/windows-conout.d.ts +46 -0
  221. package/dist/process/windows-conout.js +140 -0
  222. package/dist/process/windows-conout.js.map +1 -0
  223. package/dist/process/windows-helper.d.ts +43 -0
  224. package/dist/process/windows-helper.js +255 -0
  225. package/dist/process/windows-helper.js.map +1 -0
  226. package/dist/process/windows-job.d.ts +39 -0
  227. package/dist/process/windows-job.js +224 -0
  228. package/dist/process/windows-job.js.map +1 -0
  229. package/dist/process/windows-pipes.d.ts +16 -0
  230. package/dist/process/windows-pipes.js +475 -0
  231. package/dist/process/windows-pipes.js.map +1 -0
  232. package/dist/results/artifacts.d.ts +118 -0
  233. package/dist/results/artifacts.js +873 -0
  234. package/dist/results/artifacts.js.map +1 -0
  235. package/dist/results/encoder.d.ts +57 -0
  236. package/dist/results/encoder.js +1179 -0
  237. package/dist/results/encoder.js.map +1 -0
  238. package/dist/results/mcp.d.ts +95 -0
  239. package/dist/results/mcp.js +656 -0
  240. package/dist/results/mcp.js.map +1 -0
  241. package/dist/results/media.d.ts +19 -0
  242. package/dist/results/media.js +301 -0
  243. package/dist/results/media.js.map +1 -0
  244. package/dist/results/normalize.d.ts +29 -0
  245. package/dist/results/normalize.js +464 -0
  246. package/dist/results/normalize.js.map +1 -0
  247. package/dist/runtime/control-scripts.d.ts +23 -0
  248. package/dist/runtime/control-scripts.js +242 -0
  249. package/dist/runtime/control-scripts.js.map +1 -0
  250. package/dist/runtime/engine.d.ts +177 -0
  251. package/dist/runtime/engine.js +1159 -0
  252. package/dist/runtime/engine.js.map +1 -0
  253. package/dist/runtime/globals.d.ts +1 -0
  254. package/dist/runtime/globals.js +31 -0
  255. package/dist/runtime/globals.js.map +1 -0
  256. package/dist/runtime/material-retention.d.ts +34 -0
  257. package/dist/runtime/material-retention.js +671 -0
  258. package/dist/runtime/material-retention.js.map +1 -0
  259. package/dist/runtime/modules.d.ts +50 -0
  260. package/dist/runtime/modules.js +320 -0
  261. package/dist/runtime/modules.js.map +1 -0
  262. package/dist/runtime/names.d.ts +2 -0
  263. package/dist/runtime/names.js +22 -0
  264. package/dist/runtime/names.js.map +1 -0
  265. package/dist/runtime/operations.d.ts +20 -0
  266. package/dist/runtime/operations.js +137 -0
  267. package/dist/runtime/operations.js.map +1 -0
  268. package/dist/runtime/paths.d.ts +3 -0
  269. package/dist/runtime/paths.js +38 -0
  270. package/dist/runtime/paths.js.map +1 -0
  271. package/dist/runtime/promises.d.ts +9 -0
  272. package/dist/runtime/promises.js +78 -0
  273. package/dist/runtime/promises.js.map +1 -0
  274. package/dist/runtime/retention.d.ts +88 -0
  275. package/dist/runtime/retention.js +735 -0
  276. package/dist/runtime/retention.js.map +1 -0
  277. package/dist/runtime/run-log.d.ts +30 -0
  278. package/dist/runtime/run-log.js +207 -0
  279. package/dist/runtime/run-log.js.map +1 -0
  280. package/dist/runtime/scripts.d.ts +84 -0
  281. package/dist/runtime/scripts.js +387 -0
  282. package/dist/runtime/scripts.js.map +1 -0
  283. package/dist/runtime/tasks.d.ts +54 -0
  284. package/dist/runtime/tasks.js +290 -0
  285. package/dist/runtime/tasks.js.map +1 -0
  286. package/dist/sdk/maintenance.d.ts +3 -0
  287. package/dist/sdk/maintenance.js +80 -0
  288. package/dist/sdk/maintenance.js.map +1 -0
  289. package/dist/sdk/output-extension.d.ts +3 -0
  290. package/dist/sdk/output-extension.js +44 -0
  291. package/dist/sdk/output-extension.js.map +1 -0
  292. package/dist/sdk/output.d.ts +52 -0
  293. package/dist/sdk/output.js +350 -0
  294. package/dist/sdk/output.js.map +1 -0
  295. package/dist/sdk/runtime.d.ts +3 -0
  296. package/dist/sdk/runtime.js +26 -0
  297. package/dist/sdk/runtime.js.map +1 -0
  298. package/dist/sdk/sh.d.ts +3 -0
  299. package/dist/sdk/sh.js +384 -0
  300. package/dist/sdk/sh.js.map +1 -0
  301. package/dist/sdk/state.d.ts +2 -0
  302. package/dist/sdk/state.js +69 -0
  303. package/dist/sdk/state.js.map +1 -0
  304. package/dist/sdk/transfer.d.ts +3 -0
  305. package/dist/sdk/transfer.js +141 -0
  306. package/dist/sdk/transfer.js.map +1 -0
  307. package/dist/services/extensions.d.ts +19 -0
  308. package/dist/services/extensions.js +183 -0
  309. package/dist/services/extensions.js.map +1 -0
  310. package/dist/services/state.d.ts +37 -0
  311. package/dist/services/state.js +125 -0
  312. package/dist/services/state.js.map +1 -0
  313. package/dist/services/transfer.d.ts +86 -0
  314. package/dist/services/transfer.js +948 -0
  315. package/dist/services/transfer.js.map +1 -0
  316. package/dist/storage/schema.d.ts +8 -0
  317. package/dist/storage/schema.js +241 -0
  318. package/dist/storage/schema.js.map +1 -0
  319. package/dist/storage/sqlite.d.ts +241 -0
  320. package/dist/storage/sqlite.js +1855 -0
  321. package/dist/storage/sqlite.js.map +1 -0
  322. package/dist/storage/transfers.d.ts +90 -0
  323. package/dist/storage/transfers.js +2 -0
  324. package/dist/storage/transfers.js.map +1 -0
  325. package/dist/transfer/io.d.ts +74 -0
  326. package/dist/transfer/io.js +425 -0
  327. package/dist/transfer/io.js.map +1 -0
  328. package/dist/transfer/offers.d.ts +72 -0
  329. package/dist/transfer/offers.js +380 -0
  330. package/dist/transfer/offers.js.map +1 -0
  331. package/dist/transfer/stream-slots.d.ts +12 -0
  332. package/dist/transfer/stream-slots.js +28 -0
  333. package/dist/transfer/stream-slots.js.map +1 -0
  334. package/dist/work/catalog.d.ts +43 -0
  335. package/dist/work/catalog.js +198 -0
  336. package/dist/work/catalog.js.map +1 -0
  337. package/dist/work/discovery.d.ts +70 -0
  338. package/dist/work/discovery.js +465 -0
  339. package/dist/work/discovery.js.map +1 -0
  340. package/dist/work/service.d.ts +83 -0
  341. package/dist/work/service.js +703 -0
  342. package/dist/work/service.js.map +1 -0
  343. package/package.json +66 -4
@@ -0,0 +1,671 @@
1
+ import path from "node:path";
2
+ import { createHash } from "node:crypto";
3
+ import { constants, closeSync, fsyncSync, fstatSync, lstatSync, openSync, readSync, realpathSync, rmdirSync, unlinkSync, writeSync, } from "node:fs";
4
+ import { lstat, open, opendir, realpath, unlink } from "node:fs/promises";
5
+ import { AgentError, requireCondition } from "../contracts/errors.js";
6
+ import { privateDirectory } from "./paths.js";
7
+ const markerBytes = 4096, grace = 7 * 86400000;
8
+ const absent = (cause) => cause?.code === "ENOENT";
9
+ const key = (ref) => createHash("sha256").update(ref).digest("hex");
10
+ function generation(ref) {
11
+ const work = /^(work\/tmp\/contexts\/snapshot_[0-9a-f]{32})(?:\/[^\0]*)?$/.exec(ref);
12
+ if (work)
13
+ return { kind: "work", ref: work[1] };
14
+ const catalog = /^(work\/docs\/\.catalog\/[0-9a-f]{64})(?:\/[^\0]*)?$/.exec(ref);
15
+ if (catalog)
16
+ return { kind: "catalog", ref: catalog[1] };
17
+ const extension = /^(work\/docs\/extensions\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/[0-9a-f]{64})(?:\/[^\0]*)?$/.exec(ref);
18
+ if (extension &&
19
+ !extension[1].split("/").some((part) => part === "." || part === ".."))
20
+ return { kind: "extension", ref: extension[1] };
21
+ const adapter = /^(work\/docs\/adapters\/(?:api|mcp)\/[0-9a-f]{64}\/[0-9a-f]{64})(?:\/[^\0]*)?$/.exec(ref);
22
+ if (adapter)
23
+ return { kind: "extension", ref: adapter[1] };
24
+ return null;
25
+ }
26
+ /** Private fixed-size lifecycle facts. No mtime inference or reconstruction of missing materials. */
27
+ export class MaterialRetention {
28
+ options;
29
+ root;
30
+ #pending = new Map();
31
+ #preparing = new Map();
32
+ #published = new Map();
33
+ #deleting = new Set();
34
+ #pendingStages = new Map();
35
+ #directory;
36
+ #deletion;
37
+ #sweeping;
38
+ #closing = false;
39
+ #closed = false;
40
+ #stopping;
41
+ constructor(root, options) {
42
+ this.options = options;
43
+ requireCondition(path.isAbsolute(root) && path.resolve(root) === root, "material_profile_mismatch", "Material retention needs the fixed Agent profile root.");
44
+ this.root = root;
45
+ requireCondition(options.retentionMs === undefined ||
46
+ (Number.isSafeInteger(options.retentionMs) &&
47
+ options.retentionMs > 0 &&
48
+ options.retentionMs <= 253_402_300_799_999 - this.#now()), "invalid_material_retention", "New material retention must fit a positive protocol timestamp duration.");
49
+ }
50
+ #now() {
51
+ const now = this.options.now?.() ?? Date.now();
52
+ requireCondition(Number.isSafeInteger(now) && now >= 0, "invalid_material_clock", "Material lifecycle time must be a valid timestamp.");
53
+ return now;
54
+ }
55
+ #assertOpen() {
56
+ requireCondition(!this.#closing, "material_retention_closed", "Material retention is closing and cannot accept new work.");
57
+ }
58
+ #ref(directory) {
59
+ requireCondition(path.isAbsolute(directory), "material_path_escape", "Material lifecycle paths must be absolute profile coordinates.");
60
+ const relative = path
61
+ .relative(this.root, directory)
62
+ .split(path.sep)
63
+ .join("/"), value = generation(relative);
64
+ requireCondition(value && value.ref === relative, "material_path_escape", "Only a fixed work or material generation can enter retention.");
65
+ return value;
66
+ }
67
+ #marker(ref) {
68
+ return path.join(this.root, "state", "material-retention", `${key(ref)}.json`);
69
+ }
70
+ #existing(directory) {
71
+ requireCondition(realpathSync.native(this.root) === this.root &&
72
+ lstatSync(this.root).isDirectory(), "material_path_escape", "The actual profile root cannot redirect material access.");
73
+ let current = this.root;
74
+ for (const part of path.relative(this.root, directory).split(path.sep)) {
75
+ requireCondition(part !== "." && part !== ".." && part.length > 0, "material_path_escape", "A material coordinate must stay in its profile.");
76
+ current = path.join(current, part);
77
+ const info = lstatSync(current);
78
+ requireCondition(info.isDirectory() &&
79
+ !info.isSymbolicLink() &&
80
+ realpathSync.native(current) === current, "material_path_escape", "A material directory cannot redirect or be reconstructed.");
81
+ }
82
+ }
83
+ #encode(value) {
84
+ const bytes = Buffer.from(JSON.stringify(value));
85
+ requireCondition(bytes.length <= markerBytes, "material_marker_too_large", "The fixed private lifecycle marker is too large.");
86
+ const buffer = Buffer.alloc(markerBytes, 32);
87
+ bytes.copy(buffer);
88
+ return buffer;
89
+ }
90
+ #decode(buffer, hash) {
91
+ const marker = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffer));
92
+ const actual = marker && generation(marker.ref);
93
+ requireCondition(marker &&
94
+ [
95
+ "kind,ref,schemaVersion,unreferencedSince",
96
+ "kind,ref,retentionMs,schemaVersion,unreferencedSince",
97
+ ].includes(Object.keys(marker).sort().join(",")) &&
98
+ marker.schemaVersion === 1 &&
99
+ actual &&
100
+ actual.ref === marker.ref &&
101
+ actual.kind === marker.kind &&
102
+ key(marker.ref) === hash &&
103
+ (marker.unreferencedSince === null ||
104
+ (Number.isSafeInteger(marker.unreferencedSince) &&
105
+ marker.unreferencedSince >= 0)) &&
106
+ (marker.retentionMs === undefined ||
107
+ (Number.isSafeInteger(marker.retentionMs) &&
108
+ marker.retentionMs > 0 &&
109
+ marker.retentionMs <= 253_402_300_799_999)), "invalid_material_marker", "The private material lifecycle fact is invalid.");
110
+ return marker;
111
+ }
112
+ #read(ref) {
113
+ this.#existing(path.join(this.root, "state", "material-retention"));
114
+ const file = openSync(this.#marker(ref), constants.O_RDONLY |
115
+ (constants.O_NOFOLLOW ?? 0) |
116
+ (constants.O_NONBLOCK ?? 0));
117
+ try {
118
+ const info = fstatSync(file);
119
+ requireCondition(info.isFile() && info.nlink === 1 && info.size === markerBytes, "invalid_material_marker", "A lifecycle marker must keep its fixed regular-file size.");
120
+ const buffer = Buffer.alloc(markerBytes);
121
+ let position = 0;
122
+ while (position < buffer.length) {
123
+ const count = readSync(file, buffer, position, buffer.length - position, position);
124
+ requireCondition(count > 0, "invalid_material_marker", "The lifecycle marker ended before its fixed record.");
125
+ position += count;
126
+ }
127
+ return this.#decode(buffer, key(ref));
128
+ }
129
+ finally {
130
+ closeSync(file);
131
+ }
132
+ }
133
+ #update(ref, time) {
134
+ const marker = this.#read(ref);
135
+ if (marker.unreferencedSince === time)
136
+ return;
137
+ const bytes = this.#encode({ ...marker, unreferencedSince: time });
138
+ const file = openSync(this.#marker(ref), constants.O_RDWR |
139
+ (constants.O_NOFOLLOW ?? 0) |
140
+ (constants.O_NONBLOCK ?? 0));
141
+ try {
142
+ const info = fstatSync(file);
143
+ requireCondition(info.isFile() && info.nlink === 1 && info.size === markerBytes, "invalid_material_marker", "A material marker cannot grow during synchronous publication.");
144
+ let position = 0;
145
+ while (position < bytes.length) {
146
+ const count = writeSync(file, bytes, position, bytes.length - position, position);
147
+ requireCondition(count > 0, "material_marker_write_failed", "The lifecycle marker stopped accepting bytes.");
148
+ position += count;
149
+ }
150
+ fsyncSync(file);
151
+ }
152
+ finally {
153
+ closeSync(file);
154
+ }
155
+ }
156
+ async #ensure(kind, ref) {
157
+ privateDirectory(this.root, "state", "material-retention");
158
+ try {
159
+ const current = this.#read(ref);
160
+ requireCondition(current.kind === kind, "material_marker_conflict", "A generation cannot change its lifecycle kind.");
161
+ return;
162
+ }
163
+ catch (cause) {
164
+ if (!absent(cause))
165
+ throw cause;
166
+ }
167
+ const reservation = await this.options.reserve?.(markerBytes);
168
+ let created = false;
169
+ try {
170
+ this.#assertOpen();
171
+ privateDirectory(this.root, "state", "material-retention");
172
+ const file = await open(this.#marker(ref), constants.O_WRONLY |
173
+ constants.O_CREAT |
174
+ constants.O_EXCL |
175
+ (constants.O_NOFOLLOW ?? 0), 0o600);
176
+ created = true;
177
+ try {
178
+ await file.writeFile(this.#encode({
179
+ schemaVersion: 1,
180
+ kind,
181
+ ref,
182
+ unreferencedSince: null,
183
+ retentionMs: this.options.retentionMs ?? grace,
184
+ }));
185
+ await file.sync();
186
+ }
187
+ finally {
188
+ await file.close();
189
+ }
190
+ }
191
+ catch (cause) {
192
+ if (cause.code === "EEXIST")
193
+ this.#read(ref);
194
+ else {
195
+ if (created)
196
+ await unlink(this.#marker(ref)).catch(() => { });
197
+ throw cause;
198
+ }
199
+ }
200
+ finally {
201
+ reservation?.release();
202
+ }
203
+ }
204
+ async hold(kind, directory) {
205
+ this.#assertOpen();
206
+ const actual = this.#ref(directory);
207
+ requireCondition(actual.kind === kind, "material_marker_conflict", "The generation path does not match its declared lifecycle kind.");
208
+ requireCondition(!this.#deleting.has(actual.ref), "material_retiring", "This retired generation is being removed; prepare a fresh generation after cleanup settles.");
209
+ requireCondition(this.#pending.has(actual.ref) || this.#pending.size < 4096, "material_retention_busy", "Too many material preparations are pending.");
210
+ this.#pending.set(actual.ref, (this.#pending.get(actual.ref) ?? 0) + 1);
211
+ try {
212
+ let preparing = this.#preparing.get(actual.ref);
213
+ if (!preparing) {
214
+ preparing = this.#ensure(kind, actual.ref);
215
+ this.#preparing.set(actual.ref, preparing);
216
+ void preparing
217
+ .finally(() => {
218
+ if (this.#preparing.get(actual.ref) === preparing)
219
+ this.#preparing.delete(actual.ref);
220
+ })
221
+ .catch(() => { });
222
+ }
223
+ await preparing;
224
+ this.#assertOpen();
225
+ }
226
+ catch (cause) {
227
+ const count = this.#pending.get(actual.ref) - 1;
228
+ if (count)
229
+ this.#pending.set(actual.ref, count);
230
+ else
231
+ this.#pending.delete(actual.ref);
232
+ throw cause;
233
+ }
234
+ let released = false;
235
+ return Object.freeze({
236
+ release: () => {
237
+ if (released)
238
+ return;
239
+ const count = this.#pending.get(actual.ref);
240
+ if (!this.#closing &&
241
+ count === 1 &&
242
+ ![...this.#published.values()].includes(actual.ref))
243
+ this.#update(actual.ref, null);
244
+ if (count > 1)
245
+ this.#pending.set(actual.ref, count - 1);
246
+ else
247
+ this.#pending.delete(actual.ref);
248
+ released = true;
249
+ },
250
+ });
251
+ }
252
+ setPublished(owner, directory) {
253
+ if (directory !== null)
254
+ this.#assertOpen();
255
+ requireCondition(typeof owner === "string" &&
256
+ owner.length > 0 &&
257
+ owner.length <= 512 &&
258
+ (!directory ||
259
+ this.#published.has(owner) ||
260
+ this.#published.size < 4096), "invalid_material_owner", "A material publisher needs its bounded actual Core identity.");
261
+ const previous = this.#published.get(owner), next = directory === null ? null : this.#ref(directory).ref;
262
+ requireCondition(!next || !this.#deleting.has(next), "material_retiring", "A deleting generation cannot become newly published.");
263
+ if (next) {
264
+ this.#existing(path.join(this.root, next));
265
+ this.#update(next, null);
266
+ }
267
+ if (!this.#closing &&
268
+ previous &&
269
+ previous !== next &&
270
+ !this.#pending.has(previous) &&
271
+ ![...this.#published].some(([key, ref]) => key !== owner && ref === previous))
272
+ this.#update(previous, null);
273
+ if (next)
274
+ this.#published.set(owner, next);
275
+ else
276
+ this.#published.delete(owner);
277
+ }
278
+ protectPending(directory) {
279
+ this.#assertOpen();
280
+ const ref = path.relative(this.root, directory).split(path.sep).join("/");
281
+ requireCondition(/^work\/docs\/extensions\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/\.prepare-[A-Za-z0-9_-]+$/.test(ref), "material_path_escape", "Only a real extension preparation stage can be protected here.");
282
+ this.#existing(directory);
283
+ this.#pendingStages.set(directory, (this.#pendingStages.get(directory) ?? 0) + 1);
284
+ let released = false;
285
+ return () => {
286
+ if (!released) {
287
+ released = true;
288
+ const count = this.#pendingStages.get(directory) - 1;
289
+ if (count)
290
+ this.#pendingStages.set(directory, count);
291
+ else
292
+ this.#pendingStages.delete(directory);
293
+ }
294
+ };
295
+ }
296
+ activeDirectories() {
297
+ return new Set([...this.#pending.keys(), ...this.#published.values()]
298
+ .map((ref) => path.join(this.root, ref))
299
+ .concat([...this.#pendingStages.keys()]));
300
+ }
301
+ async #bytes(filename, maximum) {
302
+ const file = await open(filename, constants.O_RDONLY |
303
+ (constants.O_NOFOLLOW ?? 0) |
304
+ (constants.O_NONBLOCK ?? 0));
305
+ try {
306
+ const info = await file.stat();
307
+ requireCondition(info.isFile() && info.size <= maximum, "material_snapshot_unavailable", "A retained material reference must be a bounded regular file.");
308
+ const buffer = Buffer.alloc(info.size + 1);
309
+ let position = 0;
310
+ while (position < buffer.length) {
311
+ const read = await file.read(buffer, position, buffer.length - position, position);
312
+ if (!read.bytesRead)
313
+ break;
314
+ position += read.bytesRead;
315
+ }
316
+ requireCondition(position === info.size, "material_snapshot_unavailable", "The retained material reference changed while reading.");
317
+ return buffer.subarray(0, position);
318
+ }
319
+ finally {
320
+ await file.close();
321
+ }
322
+ }
323
+ async #live() {
324
+ const live = new Set([
325
+ ...this.#pending.keys(),
326
+ ...this.#published.values(),
327
+ ]);
328
+ for (const directory of this.options.publishedDirectories?.() ?? []) {
329
+ const relative = path
330
+ .relative(this.root, directory)
331
+ .split(path.sep)
332
+ .join("/"), value = generation(relative);
333
+ if (value)
334
+ live.add(value.ref);
335
+ }
336
+ const snapshots = this.options.liveSnapshotRefs();
337
+ requireCondition(snapshots.size <= 4096, "material_reference_budget", "Live work references exceed the bounded cleanup inspection budget.");
338
+ const add = (value) => {
339
+ if (typeof value !== "string" || !path.isAbsolute(value))
340
+ return;
341
+ const actual = generation(path.relative(this.root, value).split(path.sep).join("/"));
342
+ if (actual)
343
+ live.add(actual.ref);
344
+ };
345
+ for (const ref of snapshots) {
346
+ requireCondition(/^work\/tmp\/contexts\/snapshot_[0-9a-f]{32}\/bundle\.json$/.test(ref), "invalid_material_reference", "Live work references must retain their actual private snapshot coordinate.");
347
+ live.add(path.posix.dirname(ref));
348
+ this.#existing(path.join(this.root, path.posix.dirname(ref)));
349
+ const bundle = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await this.#bytes(path.join(this.root, ref), 16 * 1024 * 1024)));
350
+ add(bundle.view?.agent?.docs?.entry);
351
+ for (const group of ["docs", "instructions", "skills"])
352
+ for (const item of bundle.published?.[group] ?? []) {
353
+ add(item.path);
354
+ add(item.skillFile);
355
+ }
356
+ }
357
+ return live;
358
+ }
359
+ #sameDirectory(directory, expected) {
360
+ const actual = lstatSync(directory);
361
+ requireCondition(actual.isDirectory() &&
362
+ !actual.isSymbolicLink() &&
363
+ actual.dev === expected.dev &&
364
+ actual.ino === expected.ino &&
365
+ realpathSync.native(directory) === directory, "material_path_escape", "A deleting material directory changed its canonical identity.");
366
+ }
367
+ #checkDeletion(deletion) {
368
+ this.#existing(deletion.target);
369
+ for (const frame of deletion.frames)
370
+ this.#sameDirectory(frame.directory, frame.identity);
371
+ }
372
+ async #closeFrame(frame) {
373
+ if (frame.closed)
374
+ return;
375
+ try {
376
+ await frame.handle.close();
377
+ }
378
+ catch (cause) {
379
+ if (cause.code !== "ERR_DIR_CLOSED")
380
+ throw cause;
381
+ }
382
+ frame.closed = true;
383
+ }
384
+ async #beginDeletion(ref) {
385
+ const marker = this.#marker(ref), parent = path.dirname(marker), target = path.join(this.root, ref);
386
+ this.#existing(parent);
387
+ const markerIdentity = lstatSync(marker);
388
+ requireCondition(markerIdentity.isFile() &&
389
+ !markerIdentity.isSymbolicLink() &&
390
+ markerIdentity.nlink === 1 &&
391
+ markerIdentity.size === markerBytes, "invalid_material_marker", "Only the actual fixed private lifecycle record can be removed.");
392
+ let identity;
393
+ try {
394
+ this.#existing(target);
395
+ identity = lstatSync(target);
396
+ }
397
+ catch (cause) {
398
+ if (!absent(cause))
399
+ throw cause;
400
+ }
401
+ const deletion = {
402
+ ref,
403
+ target,
404
+ marker,
405
+ markerIdentity,
406
+ markerParentIdentity: lstatSync(parent),
407
+ frames: [],
408
+ failed: false,
409
+ };
410
+ this.#deleting.add(ref);
411
+ this.#deletion = deletion;
412
+ if (!identity)
413
+ return;
414
+ try {
415
+ const handle = await opendir(target);
416
+ deletion.frames.push({
417
+ directory: target,
418
+ identity,
419
+ handle,
420
+ closed: false,
421
+ });
422
+ this.#checkDeletion(deletion);
423
+ }
424
+ catch (cause) {
425
+ deletion.failed = true;
426
+ throw cause;
427
+ }
428
+ }
429
+ async #deleteStep() {
430
+ const deletion = this.#deletion;
431
+ if (deletion.failed) {
432
+ const frame = deletion.frames.at(-1);
433
+ if (frame) {
434
+ try {
435
+ await this.#closeFrame(frame);
436
+ deletion.frames.pop();
437
+ }
438
+ catch (cause) {
439
+ return { removed: false, error: cause, blocked: true };
440
+ }
441
+ }
442
+ if (!deletion.frames.length) {
443
+ this.#deleting.delete(deletion.ref);
444
+ this.#deletion = undefined;
445
+ }
446
+ return { removed: false };
447
+ }
448
+ try {
449
+ const frame = deletion.frames.at(-1);
450
+ if (frame) {
451
+ const entry = await frame.handle.read();
452
+ // Native directory reads may yield. The complete established chain is
453
+ // checked again in the same turn as each actual unlink/rmdir below.
454
+ this.#checkDeletion(deletion);
455
+ if (!entry) {
456
+ await this.#closeFrame(frame);
457
+ this.#checkDeletion(deletion);
458
+ rmdirSync(frame.directory);
459
+ deletion.frames.pop();
460
+ }
461
+ else {
462
+ requireCondition(entry.name !== "." &&
463
+ entry.name !== ".." &&
464
+ path.basename(entry.name) === entry.name, "material_path_escape", "A material entry must keep its actual directory name.");
465
+ const filename = path.join(frame.directory, entry.name);
466
+ let identity;
467
+ try {
468
+ identity = lstatSync(filename);
469
+ }
470
+ catch (cause) {
471
+ if (absent(cause))
472
+ return { removed: false };
473
+ throw cause;
474
+ }
475
+ if (identity.isDirectory() && !identity.isSymbolicLink()) {
476
+ requireCondition(deletion.frames.length < 128, "material_depth_exceeded", "Retired material traversal exceeds its bounded directory depth.");
477
+ const handle = await opendir(filename);
478
+ deletion.frames.push({
479
+ directory: filename,
480
+ identity,
481
+ handle,
482
+ closed: false,
483
+ });
484
+ this.#checkDeletion(deletion);
485
+ }
486
+ else {
487
+ // unlink never follows a leaf symlink; an unexpected leaf type is
488
+ // removed only at its verified parent coordinate.
489
+ unlinkSync(filename);
490
+ }
491
+ }
492
+ return { removed: false };
493
+ }
494
+ const parent = path.dirname(deletion.marker);
495
+ this.#existing(parent);
496
+ this.#sameDirectory(parent, deletion.markerParentIdentity);
497
+ const marker = lstatSync(deletion.marker);
498
+ requireCondition(marker.isFile() &&
499
+ !marker.isSymbolicLink() &&
500
+ marker.nlink === 1 &&
501
+ marker.dev === deletion.markerIdentity.dev &&
502
+ marker.ino === deletion.markerIdentity.ino &&
503
+ marker.size === markerBytes, "invalid_material_marker", "The allocated lifecycle record changed during material deletion.");
504
+ unlinkSync(deletion.marker);
505
+ this.#deleting.delete(deletion.ref);
506
+ this.#deletion = undefined;
507
+ return { removed: true };
508
+ }
509
+ catch (cause) {
510
+ deletion.failed = true;
511
+ return { removed: false, error: cause };
512
+ }
513
+ }
514
+ sweep(limit = 100) {
515
+ this.#assertOpen();
516
+ requireCondition(Number.isSafeInteger(limit) && limit >= 0 && limit <= 100, "invalid_material_batch", "Material cleanup must fit the remaining Core batch budget.");
517
+ if (this.#sweeping)
518
+ return this.#sweeping;
519
+ const pending = this.#sweep(limit);
520
+ this.#sweeping = pending;
521
+ void pending
522
+ .finally(() => {
523
+ if (this.#sweeping === pending)
524
+ this.#sweeping = undefined;
525
+ })
526
+ .catch(() => { });
527
+ return pending;
528
+ }
529
+ async #sweep(limit) {
530
+ const errors = [];
531
+ let processed = 0, removed = 0;
532
+ if (!limit)
533
+ return { processed, removed, errors };
534
+ const directory = path.join(this.root, "state", "material-retention");
535
+ let live;
536
+ const now = this.#now();
537
+ while (processed < limit) {
538
+ if (this.#deletion) {
539
+ const ref = this.#deletion.ref;
540
+ processed++;
541
+ const step = await this.#deleteStep();
542
+ if (step.removed)
543
+ removed++;
544
+ if (step.error)
545
+ errors.push({
546
+ code: step.error instanceof AgentError
547
+ ? step.error.code
548
+ : "material_retention_failed",
549
+ ref,
550
+ });
551
+ if (step.blocked)
552
+ break;
553
+ continue;
554
+ }
555
+ if (!live) {
556
+ try {
557
+ requireCondition((await lstat(directory)).isDirectory() &&
558
+ (await realpath(directory)) === directory, "material_path_escape", "The lifecycle index must stay in its private directory.");
559
+ }
560
+ catch (cause) {
561
+ if (absent(cause))
562
+ return { processed, removed, errors };
563
+ throw cause;
564
+ }
565
+ live = await this.#live();
566
+ }
567
+ this.#directory ??= await opendir(directory);
568
+ const entry = await this.#directory.read();
569
+ processed++;
570
+ if (!entry) {
571
+ await this.#directory.close();
572
+ this.#directory = undefined;
573
+ break;
574
+ }
575
+ if (!/^[0-9a-f]{64}\.json$/.test(entry.name))
576
+ continue;
577
+ if ([...this.#pending.keys()].some((ref) => key(ref) + ".json" === entry.name))
578
+ continue;
579
+ let ref = entry.name;
580
+ try {
581
+ this.#existing(directory);
582
+ const bytes = await this.#bytes(path.join(directory, entry.name), markerBytes);
583
+ requireCondition(bytes.length === markerBytes, "invalid_material_marker", "The lifecycle record lost its fixed allocated size.");
584
+ const marker = this.#decode(bytes, entry.name.slice(0, -5));
585
+ ref = marker.ref;
586
+ if (live.has(ref)) {
587
+ if (marker.unreferencedSince !== null)
588
+ this.#update(ref, null);
589
+ continue;
590
+ }
591
+ if (marker.unreferencedSince === null) {
592
+ this.#update(ref, now);
593
+ continue;
594
+ }
595
+ if (now - marker.unreferencedSince < (marker.retentionMs ?? grace))
596
+ continue;
597
+ const current = await this.#live();
598
+ if (current.has(ref) ||
599
+ this.#pending.has(ref) ||
600
+ [...this.#published.values()].includes(ref)) {
601
+ this.#update(ref, null);
602
+ continue;
603
+ }
604
+ await this.#beginDeletion(ref);
605
+ }
606
+ catch (cause) {
607
+ errors.push({
608
+ code: cause instanceof AgentError
609
+ ? cause.code
610
+ : "material_retention_failed",
611
+ ref,
612
+ });
613
+ }
614
+ }
615
+ return { processed, removed, errors };
616
+ }
617
+ stop() {
618
+ if (this.#closed)
619
+ return Promise.resolve();
620
+ if (this.#stopping)
621
+ return this.#stopping;
622
+ this.#closing = true;
623
+ const stopping = this.#finishStop();
624
+ this.#stopping = stopping;
625
+ void stopping
626
+ .finally(() => {
627
+ if (this.#stopping === stopping)
628
+ this.#stopping = undefined;
629
+ })
630
+ .catch(() => { });
631
+ return stopping;
632
+ }
633
+ async #finishStop() {
634
+ await Promise.allSettled([...this.#preparing.values()]);
635
+ await this.#sweeping?.catch(() => { });
636
+ let failure;
637
+ const deletion = this.#deletion;
638
+ if (deletion) {
639
+ for (const frame of [...deletion.frames].reverse()) {
640
+ try {
641
+ await this.#closeFrame(frame);
642
+ }
643
+ catch (cause) {
644
+ failure ??= cause;
645
+ }
646
+ }
647
+ deletion.frames = deletion.frames.filter((frame) => !frame.closed);
648
+ if (!deletion.frames.length) {
649
+ this.#deleting.delete(deletion.ref);
650
+ this.#deletion = undefined;
651
+ }
652
+ }
653
+ const directory = this.#directory;
654
+ if (directory) {
655
+ try {
656
+ await directory.close();
657
+ this.#directory = undefined;
658
+ }
659
+ catch (cause) {
660
+ if (cause.code === "ERR_DIR_CLOSED")
661
+ this.#directory = undefined;
662
+ else
663
+ failure ??= cause;
664
+ }
665
+ }
666
+ if (failure)
667
+ throw failure;
668
+ this.#closed = true;
669
+ }
670
+ }
671
+ //# sourceMappingURL=material-retention.js.map