@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,19 @@
1
+ import type { JsonObject } from "../contracts/types.js";
2
+ import { ExtensionPackageLoader } from "../extensions/package-loader.js";
3
+ import { ExtensionMaterials } from "../extensions/materials.js";
4
+ import { ExtensionRegistry } from "../extensions/registry.js";
5
+ /** Applies already-approved enable intent; confirmation and config persistence belong to maintenance. */
6
+ export declare class ExtensionServices {
7
+ #private;
8
+ readonly registry: ExtensionRegistry;
9
+ readonly packages: ExtensionPackageLoader;
10
+ readonly materials: ExtensionMaterials;
11
+ constructor(registry: ExtensionRegistry, packages: ExtensionPackageLoader, materials: ExtensionMaterials);
12
+ enable(name: string, config?: JsonObject): Promise<JsonObject>;
13
+ disable(name: string): Promise<JsonObject>;
14
+ get(name: string): JsonObject | null;
15
+ list(): readonly JsonObject[];
16
+ /** Reserve the real published instances while npm mutates their shared work tree. */
17
+ assertPackageChangeReady(): void;
18
+ withPackageChanges<T>(action: () => Promise<T>): Promise<T>;
19
+ }
@@ -0,0 +1,183 @@
1
+ import { AgentError, requireCondition } from "../contracts/errors.js";
2
+ import { canonicalJson } from "../contracts/json.js";
3
+ import { AsyncLocalStorage } from "node:async_hooks";
4
+ /** Applies already-approved enable intent; confirmation and config persistence belong to maintenance. */
5
+ export class ExtensionServices {
6
+ registry;
7
+ packages;
8
+ materials;
9
+ #entries = new Map();
10
+ #pending = new Map();
11
+ #packageOwner;
12
+ #packageContext = new AsyncLocalStorage();
13
+ constructor(registry, packages, materials) {
14
+ this.registry = registry;
15
+ this.packages = packages;
16
+ this.materials = materials;
17
+ requireCondition(packages.registry === registry &&
18
+ packages.modules.work === materials.work, "extension_profile_mismatch", "Extension loading, discovery and runtime must share one Agent profile.");
19
+ }
20
+ #name(value) {
21
+ requireCondition(typeof value === "string" &&
22
+ value.length <= 214 &&
23
+ /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value), "invalid_extension_package", "Use the actual installed npm package name.");
24
+ }
25
+ #view(entry, status = entry.status) {
26
+ return JSON.parse(canonicalJson({
27
+ name: entry.name,
28
+ extensionId: entry.prepared.handle.id,
29
+ origin: entry.prepared.handle.origin,
30
+ status,
31
+ methodCount: entry.prepared.handle.methods.length,
32
+ docs: entry.materials?.entry ?? null,
33
+ }));
34
+ }
35
+ #operation(name, action, intent, execute) {
36
+ requireCondition(!this.#packageOwner ||
37
+ this.#packageContext.getStore() === this.#packageOwner, "extension_busy", "An approved package change currently owns extension lifecycle admission.");
38
+ this.#name(name);
39
+ const existing = this.#pending.get(name);
40
+ if (existing) {
41
+ requireCondition(existing.action === action && existing.intent === intent, "extension_busy", "A different enable or disable operation is already using this package.");
42
+ return existing.promise;
43
+ }
44
+ // Reserve before invoking initialization or authorization callbacks. There
45
+ // is one in-flight action per package, without an implicit maintenance queue.
46
+ const task = Promise.resolve().then(execute);
47
+ this.#pending.set(name, { action, intent, promise: task });
48
+ void task
49
+ .finally(() => {
50
+ if (this.#pending.get(name)?.promise === task)
51
+ this.#pending.delete(name);
52
+ })
53
+ .catch(() => { });
54
+ return task;
55
+ }
56
+ async #stop(entry) {
57
+ try {
58
+ const task = this.registry.disable(entry.prepared.handle, () => {
59
+ // Withdrawal has no I/O and finishes before the instance stop signal
60
+ // can run an extension's own listeners or disposal callbacks.
61
+ this.materials.withdraw(entry.prepared.handle.id);
62
+ entry.status = "stopping";
63
+ this.#entries.set(entry.name, entry);
64
+ });
65
+ const report = await task;
66
+ if (report.status === "disabled" &&
67
+ this.#entries.get(entry.name) === entry)
68
+ this.#entries.delete(entry.name);
69
+ return report;
70
+ }
71
+ catch (cause) {
72
+ // A rejected stop request or failed persistence does not erase the actual
73
+ // prepared/active instance. A later explicit action can retry cleanup.
74
+ this.#entries.set(entry.name, entry);
75
+ throw cause;
76
+ }
77
+ }
78
+ enable(name, config = {}) {
79
+ const fixedConfig = JSON.parse(canonicalJson(config, 65536));
80
+ const intent = canonicalJson(fixedConfig, 65536);
81
+ return this.#operation(name, "enable", intent, async () => {
82
+ const existing = this.#entries.get(name);
83
+ if (existing?.status === "enabled") {
84
+ requireCondition(existing.config === intent, "extension_configuration_changed", "Disable the idle instance before applying a different approved configuration.", { extensionId: existing.prepared.handle.id });
85
+ await this.packages.verify(existing.prepared);
86
+ return this.#view(existing);
87
+ }
88
+ if (existing) {
89
+ const report = await this.#stop(existing);
90
+ requireCondition(report.status === "disabled", "extension_cleanup_unconfirmed", "The old instance must actually close before another initialization.", { extensionId: existing.prepared.handle.id, cleanup: report });
91
+ }
92
+ let prepared;
93
+ try {
94
+ prepared = await this.packages.prepare(name, fixedConfig);
95
+ }
96
+ catch (cause) {
97
+ const failed = this.packages.preparationFailure(cause);
98
+ if (failed)
99
+ this.#entries.set(name, {
100
+ name,
101
+ config: intent,
102
+ prepared: failed,
103
+ status: "stopping",
104
+ });
105
+ // The trusted failure identity remains stoppable even after enable
106
+ // intent is revoked. Namespace-conflict errors cannot name an owner.
107
+ throw cause;
108
+ }
109
+ const entry = { name, config: intent, prepared, status: "ready" };
110
+ try {
111
+ entry.materials = await this.materials.prepare(prepared.descriptor, prepared.handle);
112
+ await this.packages.verify(prepared);
113
+ this.registry.publish(prepared.handle, () => {
114
+ this.materials.publish(entry.materials);
115
+ entry.status = "enabled";
116
+ this.#entries.set(name, entry);
117
+ });
118
+ }
119
+ catch (cause) {
120
+ let cleanup;
121
+ try {
122
+ cleanup = await this.#stop(entry);
123
+ }
124
+ catch (stopError) {
125
+ cleanup = {
126
+ status: "unconfirmed",
127
+ code: stopError instanceof AgentError
128
+ ? stopError.code
129
+ : "extension_cleanup_failed",
130
+ };
131
+ }
132
+ throw new AgentError("extension_publication_failed", "The extension's complete contributions were not published.", { name, extensionId: prepared.handle.id, cleanup }, { cause });
133
+ }
134
+ // Publication is committed. A later delivery failure must not undo a
135
+ // valid shared instance or silently initialize it for a second time.
136
+ return this.#view(entry);
137
+ });
138
+ }
139
+ disable(name) {
140
+ return this.#operation(name, "disable", "", async () => {
141
+ const entry = this.#entries.get(name);
142
+ requireCondition(entry, "extension_unavailable", "This package has no instance managed by this Agent profile.");
143
+ const cleanup = await this.#stop(entry);
144
+ return {
145
+ ...this.#view(entry, cleanup.status),
146
+ cleanup,
147
+ };
148
+ });
149
+ }
150
+ get(name) {
151
+ this.#name(name);
152
+ const entry = this.#entries.get(name);
153
+ return entry ? this.#view(entry) : null;
154
+ }
155
+ list() {
156
+ return [...this.#entries.values()]
157
+ .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
158
+ .map((entry) => this.#view(entry));
159
+ }
160
+ /** Reserve the real published instances while npm mutates their shared work tree. */
161
+ assertPackageChangeReady() {
162
+ requireCondition(!this.#packageOwner ||
163
+ this.#packageContext.getStore() === this.#packageOwner, "extension_busy", "Another approved package change owns lifecycle admission.");
164
+ requireCondition(this.#pending.size === 0, "extension_busy", "An extension initialization or stop still uses the package tree.");
165
+ for (const entry of this.#entries.values())
166
+ this.registry.assertIdle(entry.prepared.handle);
167
+ }
168
+ async withPackageChanges(action) {
169
+ requireCondition(!this.#packageOwner, "extension_busy", "Another approved package change is using this work tree.");
170
+ this.assertPackageChangeReady();
171
+ const release = this.registry.reservePackageChanges([...this.#entries.values()].map((entry) => entry.prepared.handle));
172
+ const owner = Symbol("package-maintenance");
173
+ this.#packageOwner = owner;
174
+ try {
175
+ return await this.#packageContext.run(owner, action);
176
+ }
177
+ finally {
178
+ this.#packageOwner = undefined;
179
+ release();
180
+ }
181
+ }
182
+ }
183
+ //# sourceMappingURL=extensions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/services/extensions.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,37 @@
1
+ import type { JsonObject, JsonValue } from "../contracts/types.js";
2
+ import type { AccessTarget } from "../extensions/api.js";
3
+ import type { StateDeletion, StateService, StateValue } from "../extensions/state.js";
4
+ import { SqliteStore } from "../storage/sqlite.js";
5
+ export interface StateScope {
6
+ readonly context: Readonly<JsonObject>;
7
+ readonly signal: AbortSignal;
8
+ assertCurrent(): void;
9
+ authorize(target: AccessTarget): void;
10
+ }
11
+ export interface UserStateIdentity {
12
+ readonly principalId: string;
13
+ readonly clientId: string;
14
+ /** Preserved from the verified invocation; a real Cloud backend requires it. */
15
+ readonly grantId?: string;
16
+ readonly agentId: string;
17
+ readonly cloudEnvironment: string;
18
+ }
19
+ /** The Cloud authority performs each version comparison and mutation atomically. */
20
+ export interface UserStateBackend {
21
+ get(identity: UserStateIdentity, key: string, signal: AbortSignal): Promise<StateValue | null>;
22
+ set(identity: UserStateIdentity, key: string, value: JsonValue, expectedVersion: number | null, signal: AbortSignal): Promise<StateValue>;
23
+ delete(identity: UserStateIdentity, key: string, expectedVersion: number, signal: AbortSignal): Promise<StateDeletion>;
24
+ }
25
+ export declare class StateServices {
26
+ #private;
27
+ readonly store: SqliteStore;
28
+ readonly user?: UserStateBackend | undefined;
29
+ constructor(store: SqliteStore, user?: UserStateBackend | undefined, options?: {
30
+ maxBytes?: number;
31
+ /** Trusted Core admission; Cloud user state is not local managed storage. */
32
+ reserve?: (bytes: number) => Promise<{
33
+ release(): void;
34
+ }>;
35
+ });
36
+ bind(scope: StateScope): StateService;
37
+ }
@@ -0,0 +1,125 @@
1
+ import { requireCondition } from "../contracts/errors.js";
2
+ import { authorizeCall } from "../contracts/caller.js";
3
+ import { canonicalJson } from "../contracts/json.js";
4
+ export class StateServices {
5
+ store;
6
+ user;
7
+ #maxBytes;
8
+ #reserve;
9
+ constructor(store, user, options = {}) {
10
+ this.store = store;
11
+ this.user = user;
12
+ this.#maxBytes = options.maxBytes ?? 64 * 1024;
13
+ this.#reserve = options.reserve;
14
+ requireCondition(Number.isSafeInteger(this.#maxBytes) &&
15
+ this.#maxBytes > 0 &&
16
+ this.#maxBytes <= 1024 * 1024, "invalid_state_options", "Shared value control data needs a positive bounded byte budget.");
17
+ }
18
+ bind(scope) {
19
+ const caller = scope.context.caller;
20
+ requireCondition(caller &&
21
+ !Array.isArray(caller) &&
22
+ typeof caller === "object" &&
23
+ typeof caller.principalId === "string" &&
24
+ caller.principalId.length > 0 &&
25
+ typeof caller.clientId === "string" &&
26
+ caller.clientId.length > 0 &&
27
+ scope.context.agentId === this.store.binding.agentId, "invalid_state_context", "Shared services require the verified caller and actual Agent binding.");
28
+ const identity = Object.freeze({
29
+ principalId: caller.principalId,
30
+ clientId: caller.clientId,
31
+ ...(typeof caller.grantId === "string"
32
+ ? { grantId: caller.grantId }
33
+ : {}),
34
+ agentId: this.store.binding.agentId,
35
+ cloudEnvironment: this.store.binding.cloudEnvironment,
36
+ });
37
+ const copy = (value, metadataBytes = 0) => JSON.parse(canonicalJson(value, this.#maxBytes + metadataBytes));
38
+ const authorize = (kind, key, access) => {
39
+ scope.signal.throwIfAborted();
40
+ authorizeCall(() => scope.assertCurrent());
41
+ requireCondition(typeof key === "string" &&
42
+ key.length > 0 &&
43
+ Buffer.byteLength(key) <= 256 &&
44
+ !key.includes("\0"), "invalid_state_key", "A shared key must be nonempty bounded text.");
45
+ authorizeCall(() => scope.authorize({
46
+ type: kind === "agent" ? "agent-state" : "user-state",
47
+ value: key,
48
+ access,
49
+ }));
50
+ };
51
+ const version = (value, allowNull) => (allowNull && value === null) ||
52
+ (typeof value === "number" && Number.isSafeInteger(value) && value > 0);
53
+ const stateValue = (value) => {
54
+ const data = copy(value, 1024);
55
+ requireCondition(data &&
56
+ typeof data === "object" &&
57
+ Object.hasOwn(data, "value") &&
58
+ version(data.version, false) &&
59
+ Number.isSafeInteger(data.updatedAt) &&
60
+ Object.keys(data).every((key) => ["value", "version", "updatedAt"].includes(key)), "invalid_state_response", "The shared authority returned an invalid value or revision.");
61
+ copy(data.value);
62
+ return data;
63
+ };
64
+ const backend = () => {
65
+ requireCondition(this.user, "user_state_unavailable", "The Cloud user-state authority is unavailable; no local cache was substituted.");
66
+ return this.user;
67
+ };
68
+ const namespace = (kind) => Object.freeze({
69
+ get: async (key) => {
70
+ authorize(kind, key, "read");
71
+ const data = kind === "agent"
72
+ ? this.store.getState(key)
73
+ : await backend().get(identity, key, scope.signal);
74
+ authorize(kind, key, "read");
75
+ return data === null ? null : stateValue(data);
76
+ },
77
+ set: async (key, value, options) => {
78
+ authorize(kind, key, "write");
79
+ const control = copy(options);
80
+ requireCondition(control &&
81
+ Object.keys(control).length === 1 &&
82
+ Object.hasOwn(control, "expectedVersion") &&
83
+ version(control.expectedVersion, true), "invalid_state_version", "A shared write needs its read revision or null for create-only.");
84
+ const serialized = canonicalJson(value, this.#maxBytes);
85
+ const data = JSON.parse(serialized);
86
+ // No retry: a disconnected mutation may already have committed at its authority.
87
+ if (kind === "user")
88
+ return stateValue(await backend().set(identity, key, data, control.expectedVersion, scope.signal));
89
+ // The fixed overhead accounts for the key, revision and local metadata;
90
+ // SQLite settlement/headroom is retained by the Core budget provider.
91
+ const reservation = await this.#reserve?.(Buffer.byteLength(serialized) + Buffer.byteLength(key) + 1024);
92
+ try {
93
+ // Admission may wait for a native usage scan. It never freezes authority.
94
+ authorize(kind, key, "write");
95
+ return stateValue(this.store.setState(key, data, control.expectedVersion));
96
+ }
97
+ finally {
98
+ reservation?.release();
99
+ }
100
+ },
101
+ delete: async (key, options) => {
102
+ authorize(kind, key, "write");
103
+ const control = copy(options);
104
+ requireCondition(control &&
105
+ Object.keys(control).length === 1 &&
106
+ Object.hasOwn(control, "expectedVersion") &&
107
+ version(control.expectedVersion, false), "invalid_state_version", "Deleting a shared value requires its positive read revision.");
108
+ const changed = kind === "agent"
109
+ ? this.store.deleteState(key, control.expectedVersion)
110
+ : await backend().delete(identity, key, control.expectedVersion, scope.signal);
111
+ const result = copy(changed);
112
+ requireCondition(result &&
113
+ result.deleted === true &&
114
+ version(result.version, false) &&
115
+ Number.isSafeInteger(result.updatedAt), "invalid_state_response", "The shared authority returned an invalid deletion receipt.");
116
+ return result;
117
+ },
118
+ });
119
+ return Object.freeze({
120
+ agent: namespace("agent"),
121
+ user: namespace("user"),
122
+ });
123
+ }
124
+ }
125
+ //# sourceMappingURL=state.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/services/state.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,86 @@
1
+ import { EventEmitter } from "node:events";
2
+ import type { Readable, Writable } from "node:stream";
3
+ import { type Caller } from "../contracts/caller.js";
4
+ import type { Binding, ContributionOrigin, JsonObject } from "../contracts/types.js";
5
+ import type { AccessTarget } from "../extensions/api.js";
6
+ import { ResourceManager } from "../extensions/resources.js";
7
+ import type { TransferService, TransferSnapshot } from "../extensions/transfer.js";
8
+ import { ArtifactStore } from "../results/artifacts.js";
9
+ import { SqliteStore } from "../storage/sqlite.js";
10
+ import type { TransferStop, TransferTarget } from "../storage/transfers.js";
11
+ import { TransferOfferDelivery, type IssuedTransferSnapshot, type TransferOfferScope, type TransferRequest } from "../transfer/offers.js";
12
+ import { TransferStreamSlots } from "../transfer/stream-slots.js";
13
+ export interface TransferScope {
14
+ readonly context: Readonly<JsonObject>;
15
+ readonly runId?: string;
16
+ readonly signal: AbortSignal;
17
+ readonly deadline?: number;
18
+ assertCurrent(): void;
19
+ authorize(target: AccessTarget): void;
20
+ }
21
+ /** Fresh Core authority for one actual HTTP/wire claim, never the settled SDK invocation. */
22
+ export interface TransferClaimScope {
23
+ readonly binding: Binding & {
24
+ readonly bootId: string;
25
+ };
26
+ readonly caller: Caller;
27
+ readonly signal: AbortSignal;
28
+ assertCurrent(): void;
29
+ authorize(target: AccessTarget): void;
30
+ }
31
+ export interface TransferChannelBinding {
32
+ readonly binding: Binding & {
33
+ readonly bootId: string;
34
+ };
35
+ readonly transferId: string;
36
+ readonly resourceId: string;
37
+ readonly caller: Caller;
38
+ readonly direction: "upload" | "download";
39
+ readonly claimDeadlineAt: number;
40
+ readonly maxBytes: number;
41
+ readonly target: TransferTarget;
42
+ }
43
+ /** Implemented by the real Cloud control/binary bridge, or a component HTTP fixture. */
44
+ export interface TransferChannelPort {
45
+ prepare(binding: TransferChannelBinding, signal: AbortSignal): Promise<TransferRequest>;
46
+ /** Resolves only when no remaining claimant/stream uses this channel. */
47
+ revoke(binding: TransferChannelBinding, reason: TransferStop): Promise<void>;
48
+ }
49
+ export type TransferClaimIo = ({
50
+ readonly upload: Readable;
51
+ readonly contentLength?: number;
52
+ } | {
53
+ readonly download: Writable;
54
+ }) & {
55
+ /** Actual transport closure/acknowledgement, independent of Writable.finish. */
56
+ readonly closed: Promise<void>;
57
+ };
58
+ export interface TransferReservation {
59
+ readonly transferId: string;
60
+ }
61
+ export interface TransferServicesOptions {
62
+ readonly origin: ContributionOrigin;
63
+ readonly maxBytes?: number;
64
+ readonly claimTimeoutMs?: number;
65
+ readonly activeTimeoutMs?: number;
66
+ readonly reservationTimeoutMs?: number;
67
+ readonly streams?: TransferStreamSlots;
68
+ readonly now?: () => number;
69
+ }
70
+ /** Agent/profile Core coordinator. Extension factories receive only bind()'s public service. */
71
+ export declare class TransferServices extends EventEmitter {
72
+ #private;
73
+ readonly store: SqliteStore;
74
+ readonly resources: ResourceManager;
75
+ readonly artifacts: ArtifactStore;
76
+ readonly offers: TransferOfferDelivery;
77
+ readonly channels: TransferChannelPort;
78
+ readonly streams: TransferStreamSlots;
79
+ constructor(store: SqliteStore, resources: ResourceManager, artifacts: ArtifactStore, offers: TransferOfferDelivery, channels: TransferChannelPort, options: TransferServicesOptions);
80
+ bind(scope: TransferScope): TransferService;
81
+ /** Used only by the Core delivery authority; a snapshot alone grants no access. */
82
+ authorizeDelivery(scope: TransferOfferScope, snapshot: IssuedTransferSnapshot): void;
83
+ reserveClaim(id: string, scope: TransferClaimScope): TransferReservation;
84
+ releaseReservation(identity: TransferReservation): void;
85
+ commitClaim(identity: TransferReservation, io: TransferClaimIo): Promise<TransferSnapshot>;
86
+ }