@amaranthic/hernex 0.0.0-stage → 0.3.0

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 (272) hide show
  1. package/CHANGELOG.md +261 -0
  2. package/LICENSE +21 -0
  3. package/README.md +66 -2
  4. package/dist/ai.d.ts +11 -0
  5. package/dist/ai.d.ts.map +1 -0
  6. package/dist/ai.js +11 -0
  7. package/dist/ai.js.map +1 -0
  8. package/dist/checkpoints/FileCheckpointStore.d.ts +95 -0
  9. package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -0
  10. package/dist/checkpoints/FileCheckpointStore.js +502 -0
  11. package/dist/checkpoints/FileCheckpointStore.js.map +1 -0
  12. package/dist/checkpoints/index.d.ts +7 -0
  13. package/dist/checkpoints/index.d.ts.map +1 -0
  14. package/dist/checkpoints/index.js +7 -0
  15. package/dist/checkpoints/index.js.map +1 -0
  16. package/dist/checkpoints/types.d.ts +157 -0
  17. package/dist/checkpoints/types.d.ts.map +1 -0
  18. package/dist/checkpoints/types.js +6 -0
  19. package/dist/checkpoints/types.js.map +1 -0
  20. package/dist/engine/AgentEngine.d.ts +156 -0
  21. package/dist/engine/AgentEngine.d.ts.map +1 -0
  22. package/dist/engine/AgentEngine.js +290 -0
  23. package/dist/engine/AgentEngine.js.map +1 -0
  24. package/dist/engine/engineConfig.d.ts +138 -0
  25. package/dist/engine/engineConfig.d.ts.map +1 -0
  26. package/dist/engine/engineConfig.js +6 -0
  27. package/dist/engine/engineConfig.js.map +1 -0
  28. package/dist/engine/eventQueue.d.ts +42 -0
  29. package/dist/engine/eventQueue.d.ts.map +1 -0
  30. package/dist/engine/eventQueue.js +93 -0
  31. package/dist/engine/eventQueue.js.map +1 -0
  32. package/dist/engine/index.d.ts +7 -0
  33. package/dist/engine/index.d.ts.map +1 -0
  34. package/dist/engine/index.js +6 -0
  35. package/dist/engine/index.js.map +1 -0
  36. package/dist/engine/runTurn.d.ts +17 -0
  37. package/dist/engine/runTurn.d.ts.map +1 -0
  38. package/dist/engine/runTurn.js +718 -0
  39. package/dist/engine/runTurn.js.map +1 -0
  40. package/dist/errors.d.ts +194 -0
  41. package/dist/errors.d.ts.map +1 -0
  42. package/dist/errors.js +219 -0
  43. package/dist/errors.js.map +1 -0
  44. package/dist/events/checkpointEvents.d.ts +20 -0
  45. package/dist/events/checkpointEvents.d.ts.map +1 -0
  46. package/dist/events/checkpointEvents.js +6 -0
  47. package/dist/events/checkpointEvents.js.map +1 -0
  48. package/dist/events/errorEvents.d.ts +23 -0
  49. package/dist/events/errorEvents.d.ts.map +1 -0
  50. package/dist/events/errorEvents.js +6 -0
  51. package/dist/events/errorEvents.js.map +1 -0
  52. package/dist/events/index.d.ts +11 -0
  53. package/dist/events/index.d.ts.map +1 -0
  54. package/dist/events/index.js +6 -0
  55. package/dist/events/index.js.map +1 -0
  56. package/dist/events/stepEvents.d.ts +68 -0
  57. package/dist/events/stepEvents.d.ts.map +1 -0
  58. package/dist/events/stepEvents.js +6 -0
  59. package/dist/events/stepEvents.js.map +1 -0
  60. package/dist/events/streamEvents.d.ts +41 -0
  61. package/dist/events/streamEvents.d.ts.map +1 -0
  62. package/dist/events/streamEvents.js +6 -0
  63. package/dist/events/streamEvents.js.map +1 -0
  64. package/dist/events/toolEvents.d.ts +64 -0
  65. package/dist/events/toolEvents.d.ts.map +1 -0
  66. package/dist/events/toolEvents.js +6 -0
  67. package/dist/events/toolEvents.js.map +1 -0
  68. package/dist/events/types.d.ts +44 -0
  69. package/dist/events/types.d.ts.map +1 -0
  70. package/dist/events/types.js +25 -0
  71. package/dist/events/types.js.map +1 -0
  72. package/dist/hooks/composeAgentHooks.d.ts +14 -0
  73. package/dist/hooks/composeAgentHooks.d.ts.map +1 -0
  74. package/dist/hooks/composeAgentHooks.js +154 -0
  75. package/dist/hooks/composeAgentHooks.js.map +1 -0
  76. package/dist/hooks/index.d.ts +7 -0
  77. package/dist/hooks/index.d.ts.map +1 -0
  78. package/dist/hooks/index.js +6 -0
  79. package/dist/hooks/index.js.map +1 -0
  80. package/dist/hooks/types.d.ts +133 -0
  81. package/dist/hooks/types.d.ts.map +1 -0
  82. package/dist/hooks/types.js +6 -0
  83. package/dist/hooks/types.js.map +1 -0
  84. package/dist/index.d.ts +28 -0
  85. package/dist/index.d.ts.map +1 -0
  86. package/dist/index.js +26 -0
  87. package/dist/index.js.map +1 -0
  88. package/dist/model/ProviderRegistry.d.ts +62 -0
  89. package/dist/model/ProviderRegistry.d.ts.map +1 -0
  90. package/dist/model/ProviderRegistry.js +114 -0
  91. package/dist/model/ProviderRegistry.js.map +1 -0
  92. package/dist/model/providers/alibaba.d.ts +11 -0
  93. package/dist/model/providers/alibaba.d.ts.map +1 -0
  94. package/dist/model/providers/alibaba.js +16 -0
  95. package/dist/model/providers/alibaba.js.map +1 -0
  96. package/dist/model/providers/anthropic.d.ts +11 -0
  97. package/dist/model/providers/anthropic.d.ts.map +1 -0
  98. package/dist/model/providers/anthropic.js +16 -0
  99. package/dist/model/providers/anthropic.js.map +1 -0
  100. package/dist/model/providers/cohere.d.ts +11 -0
  101. package/dist/model/providers/cohere.d.ts.map +1 -0
  102. package/dist/model/providers/cohere.js +16 -0
  103. package/dist/model/providers/cohere.js.map +1 -0
  104. package/dist/model/providers/compatible.d.ts +11 -0
  105. package/dist/model/providers/compatible.d.ts.map +1 -0
  106. package/dist/model/providers/compatible.js +17 -0
  107. package/dist/model/providers/compatible.js.map +1 -0
  108. package/dist/model/providers/deepseek.d.ts +11 -0
  109. package/dist/model/providers/deepseek.d.ts.map +1 -0
  110. package/dist/model/providers/deepseek.js +16 -0
  111. package/dist/model/providers/deepseek.js.map +1 -0
  112. package/dist/model/providers/google.d.ts +11 -0
  113. package/dist/model/providers/google.d.ts.map +1 -0
  114. package/dist/model/providers/google.js +16 -0
  115. package/dist/model/providers/google.js.map +1 -0
  116. package/dist/model/providers/groq.d.ts +11 -0
  117. package/dist/model/providers/groq.d.ts.map +1 -0
  118. package/dist/model/providers/groq.js +16 -0
  119. package/dist/model/providers/groq.js.map +1 -0
  120. package/dist/model/providers/mistral.d.ts +11 -0
  121. package/dist/model/providers/mistral.d.ts.map +1 -0
  122. package/dist/model/providers/mistral.js +16 -0
  123. package/dist/model/providers/mistral.js.map +1 -0
  124. package/dist/model/providers/openai.d.ts +11 -0
  125. package/dist/model/providers/openai.d.ts.map +1 -0
  126. package/dist/model/providers/openai.js +16 -0
  127. package/dist/model/providers/openai.js.map +1 -0
  128. package/dist/model/providers/openrouter.d.ts +14 -0
  129. package/dist/model/providers/openrouter.d.ts.map +1 -0
  130. package/dist/model/providers/openrouter.js +20 -0
  131. package/dist/model/providers/openrouter.js.map +1 -0
  132. package/dist/model/providers/togetherai.d.ts +11 -0
  133. package/dist/model/providers/togetherai.d.ts.map +1 -0
  134. package/dist/model/providers/togetherai.js +16 -0
  135. package/dist/model/providers/togetherai.js.map +1 -0
  136. package/dist/model/providers/vercelGateway.d.ts +14 -0
  137. package/dist/model/providers/vercelGateway.d.ts.map +1 -0
  138. package/dist/model/providers/vercelGateway.js +19 -0
  139. package/dist/model/providers/vercelGateway.js.map +1 -0
  140. package/dist/model/providers/xai.d.ts +11 -0
  141. package/dist/model/providers/xai.d.ts.map +1 -0
  142. package/dist/model/providers/xai.js +16 -0
  143. package/dist/model/providers/xai.js.map +1 -0
  144. package/dist/model/resolveModel.d.ts +45 -0
  145. package/dist/model/resolveModel.d.ts.map +1 -0
  146. package/dist/model/resolveModel.js +109 -0
  147. package/dist/model/resolveModel.js.map +1 -0
  148. package/dist/model/types.d.ts +98 -0
  149. package/dist/model/types.d.ts.map +1 -0
  150. package/dist/model/types.js +6 -0
  151. package/dist/model/types.js.map +1 -0
  152. package/dist/runtime.d.ts +74 -0
  153. package/dist/runtime.d.ts.map +1 -0
  154. package/dist/runtime.js +41 -0
  155. package/dist/runtime.js.map +1 -0
  156. package/dist/storage/atomicFile.d.ts +28 -0
  157. package/dist/storage/atomicFile.d.ts.map +1 -0
  158. package/dist/storage/atomicFile.js +82 -0
  159. package/dist/storage/atomicFile.js.map +1 -0
  160. package/dist/storage/homeDirectory.d.ts +21 -0
  161. package/dist/storage/homeDirectory.d.ts.map +1 -0
  162. package/dist/storage/homeDirectory.js +36 -0
  163. package/dist/storage/homeDirectory.js.map +1 -0
  164. package/dist/storage/index.d.ts +11 -0
  165. package/dist/storage/index.d.ts.map +1 -0
  166. package/dist/storage/index.js +11 -0
  167. package/dist/storage/index.js.map +1 -0
  168. package/dist/storage/jsonl.d.ts +55 -0
  169. package/dist/storage/jsonl.d.ts.map +1 -0
  170. package/dist/storage/jsonl.js +142 -0
  171. package/dist/storage/jsonl.js.map +1 -0
  172. package/dist/storage/lock.d.ts +70 -0
  173. package/dist/storage/lock.d.ts.map +1 -0
  174. package/dist/storage/lock.js +274 -0
  175. package/dist/storage/lock.js.map +1 -0
  176. package/dist/storage/valueCodec.d.ts +74 -0
  177. package/dist/storage/valueCodec.d.ts.map +1 -0
  178. package/dist/storage/valueCodec.js +165 -0
  179. package/dist/storage/valueCodec.js.map +1 -0
  180. package/dist/storage/workspaceLock.d.ts +38 -0
  181. package/dist/storage/workspaceLock.d.ts.map +1 -0
  182. package/dist/storage/workspaceLock.js +77 -0
  183. package/dist/storage/workspaceLock.js.map +1 -0
  184. package/dist/tasks/TaskManager.d.ts +155 -0
  185. package/dist/tasks/TaskManager.d.ts.map +1 -0
  186. package/dist/tasks/TaskManager.js +810 -0
  187. package/dist/tasks/TaskManager.js.map +1 -0
  188. package/dist/tasks/index.d.ts +7 -0
  189. package/dist/tasks/index.d.ts.map +1 -0
  190. package/dist/tasks/index.js +6 -0
  191. package/dist/tasks/index.js.map +1 -0
  192. package/dist/tasks/types.d.ts +166 -0
  193. package/dist/tasks/types.d.ts.map +1 -0
  194. package/dist/tasks/types.js +8 -0
  195. package/dist/tasks/types.js.map +1 -0
  196. package/dist/threads/FileThreadStore.d.ts +118 -0
  197. package/dist/threads/FileThreadStore.d.ts.map +1 -0
  198. package/dist/threads/FileThreadStore.js +324 -0
  199. package/dist/threads/FileThreadStore.js.map +1 -0
  200. package/dist/threads/index.d.ts +9 -0
  201. package/dist/threads/index.d.ts.map +1 -0
  202. package/dist/threads/index.js +9 -0
  203. package/dist/threads/index.js.map +1 -0
  204. package/dist/threads/transcriptMigration.d.ts +52 -0
  205. package/dist/threads/transcriptMigration.d.ts.map +1 -0
  206. package/dist/threads/transcriptMigration.js +100 -0
  207. package/dist/threads/transcriptMigration.js.map +1 -0
  208. package/dist/threads/transcriptProjection.d.ts +21 -0
  209. package/dist/threads/transcriptProjection.d.ts.map +1 -0
  210. package/dist/threads/transcriptProjection.js +123 -0
  211. package/dist/threads/transcriptProjection.js.map +1 -0
  212. package/dist/threads/types.d.ts +250 -0
  213. package/dist/threads/types.d.ts.map +1 -0
  214. package/dist/threads/types.js +6 -0
  215. package/dist/threads/types.js.map +1 -0
  216. package/dist/tools/AgentTool.d.ts +38 -0
  217. package/dist/tools/AgentTool.d.ts.map +1 -0
  218. package/dist/tools/AgentTool.js +6 -0
  219. package/dist/tools/AgentTool.js.map +1 -0
  220. package/dist/tools/BashTool.d.ts +61 -0
  221. package/dist/tools/BashTool.d.ts.map +1 -0
  222. package/dist/tools/BashTool.js +158 -0
  223. package/dist/tools/BashTool.js.map +1 -0
  224. package/dist/tools/EditFileTool.d.ts +49 -0
  225. package/dist/tools/EditFileTool.d.ts.map +1 -0
  226. package/dist/tools/EditFileTool.js +119 -0
  227. package/dist/tools/EditFileTool.js.map +1 -0
  228. package/dist/tools/GlobTool.d.ts +48 -0
  229. package/dist/tools/GlobTool.d.ts.map +1 -0
  230. package/dist/tools/GlobTool.js +117 -0
  231. package/dist/tools/GlobTool.js.map +1 -0
  232. package/dist/tools/GrepTool.d.ts +76 -0
  233. package/dist/tools/GrepTool.d.ts.map +1 -0
  234. package/dist/tools/GrepTool.js +276 -0
  235. package/dist/tools/GrepTool.js.map +1 -0
  236. package/dist/tools/ReadFileTool.d.ts +51 -0
  237. package/dist/tools/ReadFileTool.d.ts.map +1 -0
  238. package/dist/tools/ReadFileTool.js +153 -0
  239. package/dist/tools/ReadFileTool.js.map +1 -0
  240. package/dist/tools/TaskManagerTool.d.ts +102 -0
  241. package/dist/tools/TaskManagerTool.d.ts.map +1 -0
  242. package/dist/tools/TaskManagerTool.js +132 -0
  243. package/dist/tools/TaskManagerTool.js.map +1 -0
  244. package/dist/tools/ToolExecutionContext.d.ts +61 -0
  245. package/dist/tools/ToolExecutionContext.d.ts.map +1 -0
  246. package/dist/tools/ToolExecutionContext.js +8 -0
  247. package/dist/tools/ToolExecutionContext.js.map +1 -0
  248. package/dist/tools/ToolRegistry.d.ts +82 -0
  249. package/dist/tools/ToolRegistry.d.ts.map +1 -0
  250. package/dist/tools/ToolRegistry.js +116 -0
  251. package/dist/tools/ToolRegistry.js.map +1 -0
  252. package/dist/tools/WriteFileTool.d.ts +46 -0
  253. package/dist/tools/WriteFileTool.d.ts.map +1 -0
  254. package/dist/tools/WriteFileTool.js +92 -0
  255. package/dist/tools/WriteFileTool.js.map +1 -0
  256. package/dist/tools/index.d.ts +17 -0
  257. package/dist/tools/index.d.ts.map +1 -0
  258. package/dist/tools/index.js +17 -0
  259. package/dist/tools/index.js.map +1 -0
  260. package/dist/tools/internal/bashEnvironment.d.ts +20 -0
  261. package/dist/tools/internal/bashEnvironment.d.ts.map +1 -0
  262. package/dist/tools/internal/bashEnvironment.js +65 -0
  263. package/dist/tools/internal/bashEnvironment.js.map +1 -0
  264. package/dist/tools/internal/pathGuard.d.ts +27 -0
  265. package/dist/tools/internal/pathGuard.d.ts.map +1 -0
  266. package/dist/tools/internal/pathGuard.js +99 -0
  267. package/dist/tools/internal/pathGuard.js.map +1 -0
  268. package/dist/tools/prompts.d.ts +33 -0
  269. package/dist/tools/prompts.d.ts.map +1 -0
  270. package/dist/tools/prompts.js +48 -0
  271. package/dist/tools/prompts.js.map +1 -0
  272. package/package.json +65 -4
@@ -0,0 +1,74 @@
1
+ /**
2
+ * @fileoverview Tagged lossless value codec for binary, URLs, and complex message payloads.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Tagged discriminated union of JSON-serializable representations for arbitrary JavaScript values.
7
+ */
8
+ export type EncodedValue = {
9
+ readonly type: "string";
10
+ readonly value: string;
11
+ } | {
12
+ readonly type: "number";
13
+ readonly value: number;
14
+ } | {
15
+ readonly type: "nan";
16
+ } | {
17
+ readonly type: "infinity";
18
+ } | {
19
+ readonly type: "negativeInfinity";
20
+ } | {
21
+ readonly type: "negativeZero";
22
+ } | {
23
+ readonly type: "boolean";
24
+ readonly value: boolean;
25
+ } | {
26
+ readonly type: "null";
27
+ } | {
28
+ readonly type: "undefined";
29
+ } | {
30
+ readonly type: "buffer";
31
+ readonly base64: string;
32
+ } | {
33
+ readonly type: "uint8array";
34
+ readonly base64: string;
35
+ } | {
36
+ readonly type: "url";
37
+ readonly href: string;
38
+ } | {
39
+ readonly type: "array";
40
+ readonly items: readonly EncodedValue[];
41
+ } | {
42
+ readonly type: "object";
43
+ readonly entries: Record<string, EncodedValue>;
44
+ readonly isNullPrototype?: boolean;
45
+ } | {
46
+ readonly type: "binary";
47
+ readonly base64: string;
48
+ };
49
+ /**
50
+ * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
51
+ *
52
+ * Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
53
+ * URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
54
+ * acyclic references (diamond structures) while rejecting true circular references fail-closed.
55
+ * Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
56
+ * Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
57
+ *
58
+ * @param value - Any JavaScript value.
59
+ * @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
60
+ * @returns Lossless tagged EncodedValue.
61
+ * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
62
+ */
63
+ export declare function encodeValue(value: unknown, ancestors?: Set<object>): EncodedValue;
64
+ /**
65
+ * Decodes a tagged EncodedValue back to its original JavaScript form.
66
+ *
67
+ * Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
68
+ * using safe own-property definition semantics to prevent prototype tampering.
69
+ *
70
+ * @param encoded - The EncodedValue.
71
+ * @returns Restored original JavaScript value.
72
+ */
73
+ export declare function decodeValue(encoded: EncodedValue): unknown;
74
+ //# sourceMappingURL=valueCodec.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"valueCodec.d.ts","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GACnE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,GAAG,CAAC,MAAM,CAAa,GACjC,YAAY,CA8Gd;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CA8C1D"}
@@ -0,0 +1,165 @@
1
+ /**
2
+ * @fileoverview Tagged lossless value codec for binary, URLs, and complex message payloads.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
7
+ *
8
+ * Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
9
+ * URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
10
+ * acyclic references (diamond structures) while rejecting true circular references fail-closed.
11
+ * Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
12
+ * Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
13
+ *
14
+ * @param value - Any JavaScript value.
15
+ * @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
16
+ * @returns Lossless tagged EncodedValue.
17
+ * @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
18
+ */
19
+ export function encodeValue(value, ancestors = new Set()) {
20
+ if (value === null) {
21
+ return { type: "null" };
22
+ }
23
+ if (value === undefined) {
24
+ return { type: "undefined" };
25
+ }
26
+ if (typeof value === "string") {
27
+ return { type: "string", value };
28
+ }
29
+ if (typeof value === "boolean") {
30
+ return { type: "boolean", value };
31
+ }
32
+ if (typeof value === "number") {
33
+ if (Number.isNaN(value)) {
34
+ return { type: "nan" };
35
+ }
36
+ if (value === Infinity) {
37
+ return { type: "infinity" };
38
+ }
39
+ if (value === -Infinity) {
40
+ return { type: "negativeInfinity" };
41
+ }
42
+ if (Object.is(value, -0)) {
43
+ return { type: "negativeZero" };
44
+ }
45
+ return { type: "number", value };
46
+ }
47
+ if (typeof value === "bigint") {
48
+ throw new TypeError("Cannot encode value: bigint is not supported.");
49
+ }
50
+ if (typeof value === "symbol") {
51
+ throw new TypeError("Cannot encode value: symbols are not serializable.");
52
+ }
53
+ if (typeof value === "function") {
54
+ throw new TypeError("Cannot encode value: functions are not serializable.");
55
+ }
56
+ if (typeof value === "object") {
57
+ if (ancestors.has(value)) {
58
+ throw new TypeError("Cannot encode value: circular reference detected.");
59
+ }
60
+ ancestors.add(value);
61
+ try {
62
+ if (Buffer.isBuffer(value)) {
63
+ return {
64
+ type: "buffer",
65
+ base64: value.toString("base64"),
66
+ };
67
+ }
68
+ if (value instanceof Uint8Array) {
69
+ const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
70
+ return {
71
+ type: "uint8array",
72
+ base64: buffer.toString("base64"),
73
+ };
74
+ }
75
+ if (value instanceof URL) {
76
+ return {
77
+ type: "url",
78
+ href: value.href,
79
+ };
80
+ }
81
+ if (Array.isArray(value)) {
82
+ return {
83
+ type: "array",
84
+ items: value.map((item) => encodeValue(item, ancestors)),
85
+ };
86
+ }
87
+ const proto = Object.getPrototypeOf(value);
88
+ if (proto !== Object.prototype && proto !== null) {
89
+ throw new TypeError(`Cannot encode value: unsupported prototype "${proto?.constructor?.name ?? "unknown"}".`);
90
+ }
91
+ const isNullPrototype = proto === null;
92
+ const entries = Object.create(null);
93
+ for (const [k, v] of Object.entries(value)) {
94
+ Object.defineProperty(entries, k, {
95
+ value: encodeValue(v, ancestors),
96
+ enumerable: true,
97
+ writable: true,
98
+ configurable: true,
99
+ });
100
+ }
101
+ return isNullPrototype
102
+ ? { type: "object", entries, isNullPrototype: true }
103
+ : { type: "object", entries };
104
+ }
105
+ finally {
106
+ ancestors.delete(value);
107
+ }
108
+ }
109
+ throw new TypeError(`Cannot encode value: unsupported type "${typeof value}".`);
110
+ }
111
+ /**
112
+ * Decodes a tagged EncodedValue back to its original JavaScript form.
113
+ *
114
+ * Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
115
+ * using safe own-property definition semantics to prevent prototype tampering.
116
+ *
117
+ * @param encoded - The EncodedValue.
118
+ * @returns Restored original JavaScript value.
119
+ */
120
+ export function decodeValue(encoded) {
121
+ switch (encoded.type) {
122
+ case "null":
123
+ return null;
124
+ case "undefined":
125
+ return undefined;
126
+ case "string":
127
+ case "number":
128
+ case "boolean":
129
+ return encoded.value;
130
+ case "nan":
131
+ return NaN;
132
+ case "infinity":
133
+ return Infinity;
134
+ case "negativeInfinity":
135
+ return -Infinity;
136
+ case "negativeZero":
137
+ return -0;
138
+ case "buffer":
139
+ case "binary":
140
+ return Buffer.from(encoded.base64, "base64");
141
+ case "uint8array": {
142
+ const buf = Buffer.from(encoded.base64, "base64");
143
+ return new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
144
+ }
145
+ case "url":
146
+ return new URL(encoded.href);
147
+ case "array":
148
+ return encoded.items.map(decodeValue);
149
+ case "object": {
150
+ const result = encoded.isNullPrototype
151
+ ? Object.create(null)
152
+ : {};
153
+ for (const [k, v] of Object.entries(encoded.entries)) {
154
+ Object.defineProperty(result, k, {
155
+ value: decodeValue(v),
156
+ enumerable: true,
157
+ writable: true,
158
+ configurable: true,
159
+ });
160
+ }
161
+ return result;
162
+ }
163
+ }
164
+ }
165
+ //# sourceMappingURL=valueCodec.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @fileoverview Deterministic multi-file workspace mutation locking.
3
+ * @packageDocumentation
4
+ */
5
+ import { type ResolveHomeDirectoryOptions } from "./homeDirectory.js";
6
+ import { type FileLockOptions } from "./lock.js";
7
+ /**
8
+ * Derives the exclusive lock file path for a specific target file within a workspace.
9
+ *
10
+ * Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
11
+ * the workspace tree so locking never interferes with workspace file content or git status.
12
+ *
13
+ * @param workingDirectory - Absolute workspace root path.
14
+ * @param relativeFilePath - Normalized relative path within the workspace.
15
+ * @param homeDirectory - Optional explicit storage home directory override.
16
+ * @returns Absolute path to the lock file.
17
+ */
18
+ export declare function getWorkspaceLockPath(workingDirectory: string, relativeFilePath: string, homeDirectory?: string): string;
19
+ /**
20
+ * Executes an operation under exclusive file locks for one or more workspace target files.
21
+ *
22
+ * Invariants enforced:
23
+ * - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
24
+ * - Multi-file locks are acquired in strictly deterministic lexicographical order.
25
+ * This mathematically prevents lock inversion and deadlocks across concurrent mutations.
26
+ * - Holds locks across the entire transaction boundary (before pre-state capture/reading,
27
+ * through mutation, and through post-state checkpoint finalization).
28
+ * - All acquired locks are safely released in reverse order upon completion or failure.
29
+ *
30
+ * @typeParam T - The return type of the executed operation.
31
+ * @param workingDirectory - Absolute workspace root path.
32
+ * @param targetPaths - One or more target file paths relative to or within the workspace.
33
+ * @param operation - The asynchronous transaction callback to execute.
34
+ * @param options - Optional file lock and home directory configuration.
35
+ * @returns The resolved result of the executed operation.
36
+ */
37
+ export declare function withWorkspaceFileLock<T>(workingDirectory: string, targetPaths: string | readonly string[], operation: () => Promise<T>, options?: FileLockOptions & ResolveHomeDirectoryOptions): Promise<T>;
38
+ //# sourceMappingURL=workspaceLock.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workspaceLock.d.ts","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAY/D;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAcR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACvC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,eAAe,GAAG,2BAA2B,GACtD,OAAO,CAAC,CAAC,CAAC,CAoCZ"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * @fileoverview Deterministic multi-file workspace mutation locking.
3
+ * @packageDocumentation
4
+ */
5
+ import { createHash } from "node:crypto";
6
+ import path from "node:path";
7
+ import { resolveHomeDirectory, } from "./homeDirectory.js";
8
+ import { withFileLock } from "./lock.js";
9
+ /**
10
+ * Computes a deterministic hexadecimal hash digest of a path string.
11
+ *
12
+ * @param input - The raw path string to hash.
13
+ * @returns A 24-character hexadecimal hash digest.
14
+ */
15
+ function hashPathSegment(input) {
16
+ return createHash("sha256").update(input).digest("hex").slice(0, 24);
17
+ }
18
+ /**
19
+ * Derives the exclusive lock file path for a specific target file within a workspace.
20
+ *
21
+ * Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
22
+ * the workspace tree so locking never interferes with workspace file content or git status.
23
+ *
24
+ * @param workingDirectory - Absolute workspace root path.
25
+ * @param relativeFilePath - Normalized relative path within the workspace.
26
+ * @param homeDirectory - Optional explicit storage home directory override.
27
+ * @returns Absolute path to the lock file.
28
+ */
29
+ export function getWorkspaceLockPath(workingDirectory, relativeFilePath, homeDirectory) {
30
+ const canonicalWorkspace = path.resolve(workingDirectory);
31
+ const normalizedRelative = path.normalize(relativeFilePath);
32
+ const workspaceHash = hashPathSegment(canonicalWorkspace);
33
+ const fileHash = hashPathSegment(normalizedRelative);
34
+ const storageHome = resolveHomeDirectory({ homeDirectory });
35
+ return path.join(storageHome, "locks", "workspaces", workspaceHash, `${fileHash}.lock`);
36
+ }
37
+ /**
38
+ * Executes an operation under exclusive file locks for one or more workspace target files.
39
+ *
40
+ * Invariants enforced:
41
+ * - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
42
+ * - Multi-file locks are acquired in strictly deterministic lexicographical order.
43
+ * This mathematically prevents lock inversion and deadlocks across concurrent mutations.
44
+ * - Holds locks across the entire transaction boundary (before pre-state capture/reading,
45
+ * through mutation, and through post-state checkpoint finalization).
46
+ * - All acquired locks are safely released in reverse order upon completion or failure.
47
+ *
48
+ * @typeParam T - The return type of the executed operation.
49
+ * @param workingDirectory - Absolute workspace root path.
50
+ * @param targetPaths - One or more target file paths relative to or within the workspace.
51
+ * @param operation - The asynchronous transaction callback to execute.
52
+ * @param options - Optional file lock and home directory configuration.
53
+ * @returns The resolved result of the executed operation.
54
+ */
55
+ export async function withWorkspaceFileLock(workingDirectory, targetPaths, operation, options) {
56
+ const rawList = Array.isArray(targetPaths) ? targetPaths : [targetPaths];
57
+ if (rawList.length === 0) {
58
+ return await operation();
59
+ }
60
+ const canonicalWorkspace = path.resolve(workingDirectory);
61
+ const normalizedPaths = Array.from(new Set(rawList.map((p) => {
62
+ const resolved = path.isAbsolute(p)
63
+ ? path.resolve(p)
64
+ : path.resolve(canonicalWorkspace, p);
65
+ return path.relative(canonicalWorkspace, resolved);
66
+ }))).sort();
67
+ const acquireRecursive = async (index) => {
68
+ if (index >= normalizedPaths.length) {
69
+ return await operation();
70
+ }
71
+ const relPath = normalizedPaths[index];
72
+ const lockPath = getWorkspaceLockPath(canonicalWorkspace, relPath, options?.homeDirectory);
73
+ return await withFileLock(lockPath, () => acquireRecursive(index + 1), options);
74
+ };
75
+ return await acquireRecursive(0);
76
+ }
77
+ //# sourceMappingURL=workspaceLock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workspaceLock.js","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAC;AAE/D;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,gBAAwB,EACxB,gBAAwB,EACxB,aAAsB;IAEtB,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAErD,MAAM,WAAW,GAAG,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,IAAI,CACd,WAAW,EACX,OAAO,EACP,YAAY,EACZ,aAAa,EACb,GAAG,QAAQ,OAAO,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,gBAAwB,EACxB,WAAuC,EACvC,SAA2B,EAC3B,OAAuD;IAEvD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,CAChC,IAAI,GAAG,CACL,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACjB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC,CACH,CACF,CAAC,IAAI,EAAE,CAAC;IAET,MAAM,gBAAgB,GAAG,KAAK,EAAE,KAAa,EAAc,EAAE;QAC3D,IAAI,KAAK,IAAI,eAAe,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,oBAAoB,CACnC,kBAAkB,EAClB,OAAO,EACP,OAAO,EAAE,aAAa,CACvB,CAAC;QACF,OAAO,MAAM,YAAY,CACvB,QAAQ,EACR,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC,EACjC,OAAO,CACR,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,MAAM,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC"}
@@ -0,0 +1,155 @@
1
+ /**
2
+ * @fileoverview Subprocess task manager handling live disk output streaming,
3
+ * line-paged inspection, stdin interaction, and process group lifecycle controls.
4
+ * Single owner of subprocess spawning, signalling, waiting, and deletion.
5
+ * @packageDocumentation
6
+ */
7
+ import type { CreateTaskInput, ShellTaskMetadata, TaskCreateOptions, TaskManagerOptions, TaskReadResult, TaskSendInputResult, TaskStopResult, TaskSummary, TaskWaitResult } from "./types.js";
8
+ /** Default retention time for terminated tasks (10 minutes). */
9
+ export declare const defaultRetentionTtlMs: number;
10
+ /** Default capacity limit for completed tasks before pruning (50 tasks). */
11
+ export declare const defaultMaxRetainedTasks = 50;
12
+ /** Default maximum output bytes persisted to disk log before truncation (1MB). */
13
+ export declare const defaultMaxOutputBytes = 1000000;
14
+ /** Default termination grace period before escalating from SIGTERM to SIGKILL (3000ms). */
15
+ export declare const defaultTerminationGraceMs = 3000;
16
+ /**
17
+ * Manages background shell executions, live logging, and line-paged retrieval.
18
+ * Sole owner of process spawning, signalling, output persistence, and termination.
19
+ */
20
+ export declare class TaskManager {
21
+ private readonly rootDir;
22
+ private readonly threadId;
23
+ private readonly workingDirectory;
24
+ private readonly isPersist;
25
+ private readonly retentionTtlMs;
26
+ private readonly maxRetainedTasks;
27
+ private readonly maxOutputBytes;
28
+ private readonly terminationGraceMs;
29
+ private readonly tasks;
30
+ private readonly evictedReasons;
31
+ private isDisposed;
32
+ /**
33
+ * Initializes a new TaskManager instance.
34
+ *
35
+ * @param options - Configuration options for directory resolution, retention, and thread identity.
36
+ * @throws Error if threadId is provided and fails safe identifier validation.
37
+ */
38
+ constructor(options: TaskManagerOptions);
39
+ /**
40
+ * Validates that a task identifier conforms to the safe identifier specification.
41
+ *
42
+ * @param taskId - The task identifier to validate.
43
+ * @throws Error if the identifier is malformed.
44
+ */
45
+ private assertValidTaskId;
46
+ /**
47
+ * Generates a unique task identifier using UUIDv4.
48
+ *
49
+ * @returns Formatted task identifier string.
50
+ */
51
+ private createUniqueTaskId;
52
+ /**
53
+ * Resolves the on-disk storage directory for a specific task.
54
+ *
55
+ * @param taskId - The validated task identifier.
56
+ * @returns Fully resolved directory path.
57
+ */
58
+ private getTaskDirectory;
59
+ /**
60
+ * Spawns and registers a new shell process as a managed task.
61
+ * This is the sole execution owner for subprocess spawning across Hernex.
62
+ *
63
+ * @param input - Process parameters including command string, cwd, timeout, and environment allowlist.
64
+ * @param options - Optional observers such as streaming onOutput callback.
65
+ * @returns Snapshot metadata of the newly created task.
66
+ * @throws Error if the task manager has been shut down or command is invalid.
67
+ */
68
+ createTask(input: CreateTaskInput, options?: TaskCreateOptions): Promise<ShellTaskMetadata>;
69
+ /**
70
+ * Retrieves current metadata for a task, or undefined if unknown or expired.
71
+ *
72
+ * @param taskId - Unique task identifier.
73
+ * @returns Snapshot metadata of the task, or undefined if not found.
74
+ */
75
+ getTask(taskId: string): ShellTaskMetadata | undefined;
76
+ /**
77
+ * Lists lightweight summaries of all active and recently completed tasks.
78
+ *
79
+ * @returns Readonly array of task summaries.
80
+ */
81
+ listTasks(): readonly TaskSummary[];
82
+ /**
83
+ * Reads a line-paged slice from a task's log output file on disk.
84
+ *
85
+ * @param taskId - The unique task identifier.
86
+ * @param offset - 1-based starting line number (required).
87
+ * @param limit - Maximum lines to read in this slice (capped at 500).
88
+ * @returns Promise resolving to the paged task log slice.
89
+ * @throws Error if the task is not found, expired, or parameters are out of range.
90
+ */
91
+ readTask(taskId: string, offset: number, limit: number): Promise<TaskReadResult>;
92
+ /**
93
+ * Delivers text into a running task's standard input stream.
94
+ *
95
+ * @param taskId - The unique task identifier.
96
+ * @param input - Text payload to write.
97
+ * @param options - Optional parameters, such as appending a newline.
98
+ * @returns Promise resolving to input delivery confirmation.
99
+ * @throws Error if the task is not found, not running, or stdin is closed.
100
+ */
101
+ sendTaskInput(taskId: string, input: string, options?: {
102
+ readonly newline?: boolean | undefined;
103
+ }): Promise<TaskSendInputResult>;
104
+ /**
105
+ * Terminates a task process gracefully with SIGTERM, escalating to SIGKILL after grace period.
106
+ * Blocks until child close is observed to guarantee complete termination.
107
+ *
108
+ * @param taskId - The unique task identifier to terminate.
109
+ * @param options - Signal to dispatch and termination grace timeout before escalating to SIGKILL.
110
+ * @returns Promise resolving to final termination details.
111
+ * @throws Error if the task is not found.
112
+ */
113
+ stopTask(taskId: string, options?: {
114
+ readonly signal?: "SIGTERM" | "SIGKILL" | undefined;
115
+ readonly graceMs?: number | undefined;
116
+ }): Promise<TaskStopResult>;
117
+ /**
118
+ * Waits for a task to terminate or for the specified wait timeout to expire.
119
+ *
120
+ * @param taskId - The unique task identifier.
121
+ * @param options - Timeout in milliseconds and optional abort signal.
122
+ * @returns Snapshot metadata and whether the wait timed out.
123
+ * @throws Error if the task is not found or abort signal triggers.
124
+ */
125
+ waitForTask(taskId: string, options?: {
126
+ readonly timeoutMs?: number | undefined;
127
+ readonly signal?: AbortSignal | undefined;
128
+ }): Promise<TaskWaitResult>;
129
+ /**
130
+ * Deletes a terminal task record and cleans up its directory and log assets.
131
+ *
132
+ * @param taskId - The unique task identifier to remove.
133
+ * @returns True if deleted, false if task was not found.
134
+ * @throws Error if the task is still running or stopping.
135
+ */
136
+ deleteTask(taskId: string): Promise<boolean>;
137
+ /**
138
+ * Scans and loads persisted tasks from the persistent thread storage root.
139
+ * Any previously active task is marked as orphaned without signalling stale PIDs.
140
+ */
141
+ private loadPersistedTasks;
142
+ /**
143
+ * Evicts completed tasks that exceed retention TTL or capacity limits.
144
+ */
145
+ private evictExpiredTasks;
146
+ /**
147
+ * Prunes a single task from memory and cleans up on-disk assets.
148
+ */
149
+ private pruneTask;
150
+ /**
151
+ * Terminates all active running tasks and frees resources on engine shutdown.
152
+ */
153
+ shutdown(): Promise<void>;
154
+ }
155
+ //# sourceMappingURL=TaskManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TaskManager.d.ts","sources":["../../src/tasks/TaskManager.ts"],"names":[],"mappings":"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"}