@amaranthic/hernex 0.0.0-stage → 0.2.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 (259) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +66 -2
  3. package/dist/ai.d.ts +11 -0
  4. package/dist/ai.d.ts.map +1 -0
  5. package/dist/ai.js +11 -0
  6. package/dist/ai.js.map +1 -0
  7. package/dist/checkpoints/FileCheckpointStore.d.ts +95 -0
  8. package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -0
  9. package/dist/checkpoints/FileCheckpointStore.js +412 -0
  10. package/dist/checkpoints/FileCheckpointStore.js.map +1 -0
  11. package/dist/checkpoints/index.d.ts +7 -0
  12. package/dist/checkpoints/index.d.ts.map +1 -0
  13. package/dist/checkpoints/index.js +7 -0
  14. package/dist/checkpoints/index.js.map +1 -0
  15. package/dist/checkpoints/types.d.ts +157 -0
  16. package/dist/checkpoints/types.d.ts.map +1 -0
  17. package/dist/checkpoints/types.js +6 -0
  18. package/dist/checkpoints/types.js.map +1 -0
  19. package/dist/engine/AgentEngine.d.ts +156 -0
  20. package/dist/engine/AgentEngine.d.ts.map +1 -0
  21. package/dist/engine/AgentEngine.js +288 -0
  22. package/dist/engine/AgentEngine.js.map +1 -0
  23. package/dist/engine/engineConfig.d.ts +138 -0
  24. package/dist/engine/engineConfig.d.ts.map +1 -0
  25. package/dist/engine/engineConfig.js +6 -0
  26. package/dist/engine/engineConfig.js.map +1 -0
  27. package/dist/engine/eventQueue.d.ts +42 -0
  28. package/dist/engine/eventQueue.d.ts.map +1 -0
  29. package/dist/engine/eventQueue.js +93 -0
  30. package/dist/engine/eventQueue.js.map +1 -0
  31. package/dist/engine/index.d.ts +7 -0
  32. package/dist/engine/index.d.ts.map +1 -0
  33. package/dist/engine/index.js +6 -0
  34. package/dist/engine/index.js.map +1 -0
  35. package/dist/engine/runTurn.d.ts +17 -0
  36. package/dist/engine/runTurn.d.ts.map +1 -0
  37. package/dist/engine/runTurn.js +684 -0
  38. package/dist/engine/runTurn.js.map +1 -0
  39. package/dist/errors.d.ts +142 -0
  40. package/dist/errors.d.ts.map +1 -0
  41. package/dist/errors.js +174 -0
  42. package/dist/errors.js.map +1 -0
  43. package/dist/events/checkpointEvents.d.ts +20 -0
  44. package/dist/events/checkpointEvents.d.ts.map +1 -0
  45. package/dist/events/checkpointEvents.js +6 -0
  46. package/dist/events/checkpointEvents.js.map +1 -0
  47. package/dist/events/errorEvents.d.ts +23 -0
  48. package/dist/events/errorEvents.d.ts.map +1 -0
  49. package/dist/events/errorEvents.js +6 -0
  50. package/dist/events/errorEvents.js.map +1 -0
  51. package/dist/events/index.d.ts +11 -0
  52. package/dist/events/index.d.ts.map +1 -0
  53. package/dist/events/index.js +6 -0
  54. package/dist/events/index.js.map +1 -0
  55. package/dist/events/stepEvents.d.ts +68 -0
  56. package/dist/events/stepEvents.d.ts.map +1 -0
  57. package/dist/events/stepEvents.js +6 -0
  58. package/dist/events/stepEvents.js.map +1 -0
  59. package/dist/events/streamEvents.d.ts +41 -0
  60. package/dist/events/streamEvents.d.ts.map +1 -0
  61. package/dist/events/streamEvents.js +6 -0
  62. package/dist/events/streamEvents.js.map +1 -0
  63. package/dist/events/toolEvents.d.ts +62 -0
  64. package/dist/events/toolEvents.d.ts.map +1 -0
  65. package/dist/events/toolEvents.js +6 -0
  66. package/dist/events/toolEvents.js.map +1 -0
  67. package/dist/events/types.d.ts +37 -0
  68. package/dist/events/types.d.ts.map +1 -0
  69. package/dist/events/types.js +6 -0
  70. package/dist/events/types.js.map +1 -0
  71. package/dist/hooks/composeAgentHooks.d.ts +14 -0
  72. package/dist/hooks/composeAgentHooks.d.ts.map +1 -0
  73. package/dist/hooks/composeAgentHooks.js +142 -0
  74. package/dist/hooks/composeAgentHooks.js.map +1 -0
  75. package/dist/hooks/index.d.ts +7 -0
  76. package/dist/hooks/index.d.ts.map +1 -0
  77. package/dist/hooks/index.js +6 -0
  78. package/dist/hooks/index.js.map +1 -0
  79. package/dist/hooks/types.d.ts +133 -0
  80. package/dist/hooks/types.d.ts.map +1 -0
  81. package/dist/hooks/types.js +6 -0
  82. package/dist/hooks/types.js.map +1 -0
  83. package/dist/index.d.ts +26 -0
  84. package/dist/index.d.ts.map +1 -0
  85. package/dist/index.js +25 -0
  86. package/dist/index.js.map +1 -0
  87. package/dist/model/ProviderRegistry.d.ts +62 -0
  88. package/dist/model/ProviderRegistry.d.ts.map +1 -0
  89. package/dist/model/ProviderRegistry.js +114 -0
  90. package/dist/model/ProviderRegistry.js.map +1 -0
  91. package/dist/model/providers/alibaba.d.ts +11 -0
  92. package/dist/model/providers/alibaba.d.ts.map +1 -0
  93. package/dist/model/providers/alibaba.js +16 -0
  94. package/dist/model/providers/alibaba.js.map +1 -0
  95. package/dist/model/providers/anthropic.d.ts +11 -0
  96. package/dist/model/providers/anthropic.d.ts.map +1 -0
  97. package/dist/model/providers/anthropic.js +16 -0
  98. package/dist/model/providers/anthropic.js.map +1 -0
  99. package/dist/model/providers/cohere.d.ts +11 -0
  100. package/dist/model/providers/cohere.d.ts.map +1 -0
  101. package/dist/model/providers/cohere.js +16 -0
  102. package/dist/model/providers/cohere.js.map +1 -0
  103. package/dist/model/providers/compatible.d.ts +11 -0
  104. package/dist/model/providers/compatible.d.ts.map +1 -0
  105. package/dist/model/providers/compatible.js +17 -0
  106. package/dist/model/providers/compatible.js.map +1 -0
  107. package/dist/model/providers/deepseek.d.ts +11 -0
  108. package/dist/model/providers/deepseek.d.ts.map +1 -0
  109. package/dist/model/providers/deepseek.js +16 -0
  110. package/dist/model/providers/deepseek.js.map +1 -0
  111. package/dist/model/providers/google.d.ts +11 -0
  112. package/dist/model/providers/google.d.ts.map +1 -0
  113. package/dist/model/providers/google.js +16 -0
  114. package/dist/model/providers/google.js.map +1 -0
  115. package/dist/model/providers/groq.d.ts +11 -0
  116. package/dist/model/providers/groq.d.ts.map +1 -0
  117. package/dist/model/providers/groq.js +16 -0
  118. package/dist/model/providers/groq.js.map +1 -0
  119. package/dist/model/providers/mistral.d.ts +11 -0
  120. package/dist/model/providers/mistral.d.ts.map +1 -0
  121. package/dist/model/providers/mistral.js +16 -0
  122. package/dist/model/providers/mistral.js.map +1 -0
  123. package/dist/model/providers/openai.d.ts +11 -0
  124. package/dist/model/providers/openai.d.ts.map +1 -0
  125. package/dist/model/providers/openai.js +16 -0
  126. package/dist/model/providers/openai.js.map +1 -0
  127. package/dist/model/providers/openrouter.d.ts +14 -0
  128. package/dist/model/providers/openrouter.d.ts.map +1 -0
  129. package/dist/model/providers/openrouter.js +20 -0
  130. package/dist/model/providers/openrouter.js.map +1 -0
  131. package/dist/model/providers/togetherai.d.ts +11 -0
  132. package/dist/model/providers/togetherai.d.ts.map +1 -0
  133. package/dist/model/providers/togetherai.js +16 -0
  134. package/dist/model/providers/togetherai.js.map +1 -0
  135. package/dist/model/providers/vercelGateway.d.ts +14 -0
  136. package/dist/model/providers/vercelGateway.d.ts.map +1 -0
  137. package/dist/model/providers/vercelGateway.js +19 -0
  138. package/dist/model/providers/vercelGateway.js.map +1 -0
  139. package/dist/model/providers/xai.d.ts +11 -0
  140. package/dist/model/providers/xai.d.ts.map +1 -0
  141. package/dist/model/providers/xai.js +16 -0
  142. package/dist/model/providers/xai.js.map +1 -0
  143. package/dist/model/resolveModel.d.ts +45 -0
  144. package/dist/model/resolveModel.d.ts.map +1 -0
  145. package/dist/model/resolveModel.js +109 -0
  146. package/dist/model/resolveModel.js.map +1 -0
  147. package/dist/model/types.d.ts +98 -0
  148. package/dist/model/types.d.ts.map +1 -0
  149. package/dist/model/types.js +6 -0
  150. package/dist/model/types.js.map +1 -0
  151. package/dist/runtime.d.ts +74 -0
  152. package/dist/runtime.d.ts.map +1 -0
  153. package/dist/runtime.js +41 -0
  154. package/dist/runtime.js.map +1 -0
  155. package/dist/storage/atomicFile.d.ts +28 -0
  156. package/dist/storage/atomicFile.d.ts.map +1 -0
  157. package/dist/storage/atomicFile.js +56 -0
  158. package/dist/storage/atomicFile.js.map +1 -0
  159. package/dist/storage/homeDirectory.d.ts +21 -0
  160. package/dist/storage/homeDirectory.d.ts.map +1 -0
  161. package/dist/storage/homeDirectory.js +36 -0
  162. package/dist/storage/homeDirectory.js.map +1 -0
  163. package/dist/storage/index.d.ts +10 -0
  164. package/dist/storage/index.d.ts.map +1 -0
  165. package/dist/storage/index.js +10 -0
  166. package/dist/storage/index.js.map +1 -0
  167. package/dist/storage/jsonl.d.ts +46 -0
  168. package/dist/storage/jsonl.d.ts.map +1 -0
  169. package/dist/storage/jsonl.js +121 -0
  170. package/dist/storage/jsonl.js.map +1 -0
  171. package/dist/storage/lock.d.ts +47 -0
  172. package/dist/storage/lock.d.ts.map +1 -0
  173. package/dist/storage/lock.js +126 -0
  174. package/dist/storage/lock.js.map +1 -0
  175. package/dist/storage/valueCodec.d.ts +68 -0
  176. package/dist/storage/valueCodec.d.ts.map +1 -0
  177. package/dist/storage/valueCodec.js +140 -0
  178. package/dist/storage/valueCodec.js.map +1 -0
  179. package/dist/tasks/TaskManager.d.ts +155 -0
  180. package/dist/tasks/TaskManager.d.ts.map +1 -0
  181. package/dist/tasks/TaskManager.js +774 -0
  182. package/dist/tasks/TaskManager.js.map +1 -0
  183. package/dist/tasks/index.d.ts +7 -0
  184. package/dist/tasks/index.d.ts.map +1 -0
  185. package/dist/tasks/index.js +6 -0
  186. package/dist/tasks/index.js.map +1 -0
  187. package/dist/tasks/types.d.ts +160 -0
  188. package/dist/tasks/types.d.ts.map +1 -0
  189. package/dist/tasks/types.js +8 -0
  190. package/dist/tasks/types.js.map +1 -0
  191. package/dist/threads/FileThreadStore.d.ts +118 -0
  192. package/dist/threads/FileThreadStore.d.ts.map +1 -0
  193. package/dist/threads/FileThreadStore.js +320 -0
  194. package/dist/threads/FileThreadStore.js.map +1 -0
  195. package/dist/threads/index.d.ts +7 -0
  196. package/dist/threads/index.d.ts.map +1 -0
  197. package/dist/threads/index.js +7 -0
  198. package/dist/threads/index.js.map +1 -0
  199. package/dist/threads/types.d.ts +230 -0
  200. package/dist/threads/types.d.ts.map +1 -0
  201. package/dist/threads/types.js +6 -0
  202. package/dist/threads/types.js.map +1 -0
  203. package/dist/tools/AgentTool.d.ts +38 -0
  204. package/dist/tools/AgentTool.d.ts.map +1 -0
  205. package/dist/tools/AgentTool.js +6 -0
  206. package/dist/tools/AgentTool.js.map +1 -0
  207. package/dist/tools/BashTool.d.ts +61 -0
  208. package/dist/tools/BashTool.d.ts.map +1 -0
  209. package/dist/tools/BashTool.js +142 -0
  210. package/dist/tools/BashTool.js.map +1 -0
  211. package/dist/tools/EditFileTool.d.ts +49 -0
  212. package/dist/tools/EditFileTool.d.ts.map +1 -0
  213. package/dist/tools/EditFileTool.js +114 -0
  214. package/dist/tools/EditFileTool.js.map +1 -0
  215. package/dist/tools/GlobTool.d.ts +48 -0
  216. package/dist/tools/GlobTool.d.ts.map +1 -0
  217. package/dist/tools/GlobTool.js +117 -0
  218. package/dist/tools/GlobTool.js.map +1 -0
  219. package/dist/tools/GrepTool.d.ts +73 -0
  220. package/dist/tools/GrepTool.d.ts.map +1 -0
  221. package/dist/tools/GrepTool.js +250 -0
  222. package/dist/tools/GrepTool.js.map +1 -0
  223. package/dist/tools/ReadFileTool.d.ts +51 -0
  224. package/dist/tools/ReadFileTool.d.ts.map +1 -0
  225. package/dist/tools/ReadFileTool.js +153 -0
  226. package/dist/tools/ReadFileTool.js.map +1 -0
  227. package/dist/tools/TaskManagerTool.d.ts +102 -0
  228. package/dist/tools/TaskManagerTool.d.ts.map +1 -0
  229. package/dist/tools/TaskManagerTool.js +130 -0
  230. package/dist/tools/TaskManagerTool.js.map +1 -0
  231. package/dist/tools/ToolExecutionContext.d.ts +61 -0
  232. package/dist/tools/ToolExecutionContext.d.ts.map +1 -0
  233. package/dist/tools/ToolExecutionContext.js +8 -0
  234. package/dist/tools/ToolExecutionContext.js.map +1 -0
  235. package/dist/tools/ToolRegistry.d.ts +82 -0
  236. package/dist/tools/ToolRegistry.d.ts.map +1 -0
  237. package/dist/tools/ToolRegistry.js +116 -0
  238. package/dist/tools/ToolRegistry.js.map +1 -0
  239. package/dist/tools/WriteFileTool.d.ts +46 -0
  240. package/dist/tools/WriteFileTool.d.ts.map +1 -0
  241. package/dist/tools/WriteFileTool.js +87 -0
  242. package/dist/tools/WriteFileTool.js.map +1 -0
  243. package/dist/tools/index.d.ts +17 -0
  244. package/dist/tools/index.d.ts.map +1 -0
  245. package/dist/tools/index.js +17 -0
  246. package/dist/tools/index.js.map +1 -0
  247. package/dist/tools/internal/bashEnvironment.d.ts +20 -0
  248. package/dist/tools/internal/bashEnvironment.d.ts.map +1 -0
  249. package/dist/tools/internal/bashEnvironment.js +65 -0
  250. package/dist/tools/internal/bashEnvironment.js.map +1 -0
  251. package/dist/tools/internal/pathGuard.d.ts +27 -0
  252. package/dist/tools/internal/pathGuard.d.ts.map +1 -0
  253. package/dist/tools/internal/pathGuard.js +99 -0
  254. package/dist/tools/internal/pathGuard.js.map +1 -0
  255. package/dist/tools/prompts.d.ts +33 -0
  256. package/dist/tools/prompts.d.ts.map +1 -0
  257. package/dist/tools/prompts.js +48 -0
  258. package/dist/tools/prompts.js.map +1 -0
  259. package/package.json +64 -4
@@ -0,0 +1 @@
1
+ {"version":3,"file":"xai.js","sources":["../../../src/model/providers/xai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACpB,UAAU,GAAG,KAAK,CAAC;IAE5B,WAAW,CAAC,OAAe,EAAE,WAA8B;QACzD,MAAM,QAAQ,GAAG,SAAS,CAAC;YACzB,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,OAAO,EAAE,WAAW,CAAC,OAAO;SAC7B,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,kBAAkB,EAAE,CAAC"}
@@ -0,0 +1,45 @@
1
+ /**
2
+ * @fileoverview Single-string model resolution with mandatory credentials and first-slash routing.
3
+ * @packageDocumentation
4
+ */
5
+ import type { LanguageModel } from "ai";
6
+ import type { HernexCredentials, HernexModelInput, ParsedModelString } from "./types.js";
7
+ import { ProviderRegistry } from "./ProviderRegistry.js";
8
+ /**
9
+ * Parses a Hernex model string according to the strict first-slash rule.
10
+ *
11
+ * Segments before the first slash represent the provider identifier, and all segments
12
+ * after the first slash (including subsequent slashes) represent the model identifier.
13
+ *
14
+ * @param modelString - The model string to parse (e.g. "openai/gpt-4o", "openrouter/openrouter/free").
15
+ * @returns The parsed model representation containing provider and modelId.
16
+ * @throws {HernexInvalidModelStringError} If the string is malformed, lacks a slash, or contains an empty provider or modelId.
17
+ */
18
+ export declare function parseModelString(modelString: string): ParsedModelString;
19
+ /**
20
+ * Validates mandatory credentials for a Hernex request.
21
+ *
22
+ * Every Hernex request mandates non-empty `apiKey` and `baseUrl` strings.
23
+ *
24
+ * @param credentials - The credentials object to validate.
25
+ * @param provider - The target provider name for descriptive error messaging.
26
+ * @throws {HernexMissingCredentialsError} If either `apiKey` or `baseUrl` is missing or empty.
27
+ */
28
+ export declare function validateCredentials(credentials: HernexCredentials, provider: string): void;
29
+ /**
30
+ * Resolves a Hernex model input (either a `provider/model_id` string or an existing LanguageModel)
31
+ * into an instantiated AI SDK LanguageModel.
32
+ *
33
+ * Completely avoids fallthrough to default AI Gateway resolution by directly routing
34
+ * through Hernex's provider registry.
35
+ *
36
+ * @param model - A `provider/model_id` string or an existing LanguageModel instance.
37
+ * @param credentials - Mandatory credentials containing non-empty apiKey and baseUrl.
38
+ * @param providerRegistry - Optional isolated ProviderRegistry instance.
39
+ * @returns A concrete AI SDK LanguageModel instance ready for execution.
40
+ * @throws {HernexInvalidModelStringError} If the model string is malformed.
41
+ * @throws {HernexMissingCredentialsError} If apiKey or baseUrl are missing.
42
+ * @throws {HernexUnsupportedProviderError} If the provider is unknown.
43
+ */
44
+ export declare function resolveModel(model: HernexModelInput, credentials: HernexCredentials, providerRegistry?: ProviderRegistry): LanguageModel;
45
+ //# sourceMappingURL=resolveModel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveModel.d.ts","sources":["../../src/model/resolveModel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAA2B,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAElF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAuCvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,iBAAiB,EAC9B,QAAQ,EAAE,MAAM,GACf,IAAI,CAqBN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,iBAAiB,EAC9B,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,aAAa,CAsBf"}
@@ -0,0 +1,109 @@
1
+ /**
2
+ * @fileoverview Single-string model resolution with mandatory credentials and first-slash routing.
3
+ * @packageDocumentation
4
+ */
5
+ import { HernexInvalidModelStringError, HernexMissingCredentialsError, } from "../errors.js";
6
+ import { defaultProviderRegistry, ProviderRegistry } from "./ProviderRegistry.js";
7
+ /**
8
+ * Parses a Hernex model string according to the strict first-slash rule.
9
+ *
10
+ * Segments before the first slash represent the provider identifier, and all segments
11
+ * after the first slash (including subsequent slashes) represent the model identifier.
12
+ *
13
+ * @param modelString - The model string to parse (e.g. "openai/gpt-4o", "openrouter/openrouter/free").
14
+ * @returns The parsed model representation containing provider and modelId.
15
+ * @throws {HernexInvalidModelStringError} If the string is malformed, lacks a slash, or contains an empty provider or modelId.
16
+ */
17
+ export function parseModelString(modelString) {
18
+ if (typeof modelString !== "string") {
19
+ throw new HernexInvalidModelStringError({
20
+ modelString: String(modelString),
21
+ reason: "Model identifier must be a string",
22
+ });
23
+ }
24
+ const firstSlashIndex = modelString.indexOf("/");
25
+ if (firstSlashIndex === -1) {
26
+ throw new HernexInvalidModelStringError({
27
+ modelString,
28
+ reason: "No '/' delimiter found",
29
+ });
30
+ }
31
+ const provider = modelString.slice(0, firstSlashIndex).trim();
32
+ if (provider.length === 0) {
33
+ throw new HernexInvalidModelStringError({
34
+ modelString,
35
+ reason: "Provider identifier before '/' is empty",
36
+ });
37
+ }
38
+ const modelId = modelString.slice(firstSlashIndex + 1).trim();
39
+ if (modelId.length === 0) {
40
+ throw new HernexInvalidModelStringError({
41
+ modelString,
42
+ reason: "Model identifier after '/' is empty",
43
+ });
44
+ }
45
+ return {
46
+ provider,
47
+ modelId,
48
+ };
49
+ }
50
+ /**
51
+ * Validates mandatory credentials for a Hernex request.
52
+ *
53
+ * Every Hernex request mandates non-empty `apiKey` and `baseUrl` strings.
54
+ *
55
+ * @param credentials - The credentials object to validate.
56
+ * @param provider - The target provider name for descriptive error messaging.
57
+ * @throws {HernexMissingCredentialsError} If either `apiKey` or `baseUrl` is missing or empty.
58
+ */
59
+ export function validateCredentials(credentials, provider) {
60
+ if (!credentials ||
61
+ typeof credentials.apiKey !== "string" ||
62
+ credentials.apiKey.trim().length === 0) {
63
+ throw new HernexMissingCredentialsError({
64
+ missingField: "apiKey",
65
+ provider,
66
+ });
67
+ }
68
+ if (typeof credentials.baseUrl !== "string" ||
69
+ credentials.baseUrl.trim().length === 0) {
70
+ throw new HernexMissingCredentialsError({
71
+ missingField: "baseUrl",
72
+ provider,
73
+ });
74
+ }
75
+ }
76
+ /**
77
+ * Resolves a Hernex model input (either a `provider/model_id` string or an existing LanguageModel)
78
+ * into an instantiated AI SDK LanguageModel.
79
+ *
80
+ * Completely avoids fallthrough to default AI Gateway resolution by directly routing
81
+ * through Hernex's provider registry.
82
+ *
83
+ * @param model - A `provider/model_id` string or an existing LanguageModel instance.
84
+ * @param credentials - Mandatory credentials containing non-empty apiKey and baseUrl.
85
+ * @param providerRegistry - Optional isolated ProviderRegistry instance.
86
+ * @returns A concrete AI SDK LanguageModel instance ready for execution.
87
+ * @throws {HernexInvalidModelStringError} If the model string is malformed.
88
+ * @throws {HernexMissingCredentialsError} If apiKey or baseUrl are missing.
89
+ * @throws {HernexUnsupportedProviderError} If the provider is unknown.
90
+ */
91
+ export function resolveModel(model, credentials, providerRegistry) {
92
+ // If model is an object, treat as an existing pre-instantiated LanguageModel
93
+ if (typeof model !== "string") {
94
+ if (model && typeof model === "object") {
95
+ validateCredentials(credentials, "custom");
96
+ return model;
97
+ }
98
+ throw new HernexInvalidModelStringError({
99
+ modelString: String(model),
100
+ reason: "Model must be a valid 'provider/model_id' string or an instantiated LanguageModel",
101
+ });
102
+ }
103
+ const { provider, modelId } = parseModelString(model);
104
+ validateCredentials(credentials, provider);
105
+ const registry = providerRegistry ?? defaultProviderRegistry;
106
+ const adapter = registry.resolve(provider);
107
+ return adapter.createModel(modelId, credentials);
108
+ }
109
+ //# sourceMappingURL=resolveModel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveModel.js","sources":["../../src/model/resolveModel.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,98 @@
1
+ /**
2
+ * @fileoverview Canonical types and contracts for Hernex models and provider adapters.
3
+ * @packageDocumentation
4
+ */
5
+ import type { LanguageModel, ModelMessage, generateText, streamText } from "ai";
6
+ import type { ProviderRegistry } from "./ProviderRegistry.js";
7
+ export type { LanguageModel, ModelMessage };
8
+ /**
9
+ * Parsed representation of a Hernex model specification.
10
+ */
11
+ export interface ParsedModelString {
12
+ /**
13
+ * The provider segment extracted from before the first slash.
14
+ *
15
+ * @example "openai", "anthropic", "compatible"
16
+ */
17
+ readonly provider: string;
18
+ /**
19
+ * The model identifier segment extracted from after the first slash.
20
+ * Preserves all subsequent slashes intact.
21
+ *
22
+ * @example "gpt-4o", "openrouter/free"
23
+ */
24
+ readonly modelId: string;
25
+ }
26
+ /**
27
+ * Mandatory credentials required for all Hernex requests.
28
+ *
29
+ * Every Hernex execution mandates both `apiKey` and `baseUrl`.
30
+ */
31
+ export interface HernexCredentials {
32
+ /**
33
+ * The authentication key for the target model or provider.
34
+ * Where an endpoint requires no authentication, a non-empty placeholder may be provided.
35
+ */
36
+ readonly apiKey: string;
37
+ /**
38
+ * The base URL endpoint for the target provider or proxy.
39
+ */
40
+ readonly baseUrl: string;
41
+ }
42
+ /**
43
+ * Contract implemented by each dedicated provider adapter in Hernex.
44
+ */
45
+ export interface ProviderAdapter {
46
+ /**
47
+ * Unique identifier of the provider handled by this adapter.
48
+ *
49
+ * @example "openai", "anthropic", "google", "compatible"
50
+ */
51
+ readonly providerId: string;
52
+ /**
53
+ * Instantiates a concrete AI SDK LanguageModel using the provided model ID and credentials.
54
+ *
55
+ * @param modelId - The provider-specific model identifier.
56
+ * @param credentials - Mandatory apiKey and baseUrl credentials.
57
+ * @returns A concrete AI SDK LanguageModel instance.
58
+ */
59
+ createModel(modelId: string, credentials: HernexCredentials): LanguageModel;
60
+ }
61
+ /**
62
+ * Form of a Hernex model reference: either a `provider/model_id` string or an existing LanguageModel instance.
63
+ */
64
+ export type HernexModelInput = string | LanguageModel;
65
+ /**
66
+ * Wrapper utility type transforming native AI SDK call options into Hernex request options.
67
+ *
68
+ * Replaces the `model` property with `HernexModelInput` and mandates `apiKey` and `baseUrl`.
69
+ */
70
+ export type HernexRequest<TNativeParams> = Omit<TNativeParams, "model"> & {
71
+ /**
72
+ * The model to use, expressed as a "provider/model_id" string or a pre-instantiated LanguageModel.
73
+ *
74
+ * @example "openai/gpt-4o", "anthropic/claude-3-7-sonnet", "compatible/meta-llama/llama-3-8b"
75
+ */
76
+ readonly model: HernexModelInput;
77
+ /**
78
+ * API key used to authenticate with the model endpoint.
79
+ */
80
+ readonly apiKey: string;
81
+ /**
82
+ * Base URL endpoint for the provider.
83
+ */
84
+ readonly baseUrl: string;
85
+ /**
86
+ * Optional custom provider registry for isolated resolution.
87
+ */
88
+ readonly providerRegistry?: ProviderRegistry;
89
+ };
90
+ /**
91
+ * Hernex parameters for `generateText`, derived directly from AI SDK's `generateText` parameters.
92
+ */
93
+ export type HernexGenerateTextParameters = HernexRequest<Parameters<typeof generateText>[0]>;
94
+ /**
95
+ * Hernex parameters for `streamText`, derived directly from AI SDK's `streamText` parameters.
96
+ */
97
+ export type HernexStreamTextParameters = HernexRequest<Parameters<typeof streamText>[0]>;
98
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sources":["../../src/model/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACX,MAAM,IAAI,CAAC;AACZ,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,aAAa,CAAC;CAC7E;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,aAAa,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG;IACxE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,aAAa,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7F;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,aAAa,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * @fileoverview Canonical types and contracts for Hernex models and provider adapters.
3
+ * @packageDocumentation
4
+ */
5
+ export {};
6
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sources":["../../src/model/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
@@ -0,0 +1,74 @@
1
+ /**
2
+ * @fileoverview Curated Hernex runtime wrappers around Vercel AI SDK functions.
3
+ * @packageDocumentation
4
+ */
5
+ import { generateText as aiGenerateText, streamText as aiStreamText } from "ai";
6
+ import type { ProviderRegistry } from "./model/ProviderRegistry.js";
7
+ import type { HernexModelInput } from "./model/types.js";
8
+ /**
9
+ * Parameters for Hernex generateText runtime call, requiring model, apiKey, and baseUrl
10
+ * while forwarding all native AI SDK options.
11
+ */
12
+ export type HernexGenerateTextOptions = Omit<Parameters<typeof aiGenerateText>[0], "model"> & {
13
+ /**
14
+ * The model specification, formatted as "provider/model_id" (e.g. "openai/gpt-4o")
15
+ * or a pre-instantiated LanguageModel.
16
+ */
17
+ readonly model: HernexModelInput;
18
+ /**
19
+ * The mandatory API key for the target model or provider.
20
+ */
21
+ readonly apiKey: string;
22
+ /**
23
+ * The mandatory base URL for the target model or provider endpoint.
24
+ */
25
+ readonly baseUrl: string;
26
+ /**
27
+ * Optional custom provider registry for isolated resolution.
28
+ */
29
+ readonly providerRegistry?: ProviderRegistry;
30
+ };
31
+ /**
32
+ * Generates text using the specified model and credentials.
33
+ *
34
+ * Dynamically resolves the provider and model according to the first-slash rule,
35
+ * applies credentials, and forwards all options to Vercel AI SDK's native `generateText`.
36
+ *
37
+ * @param options - Generation options with required model, apiKey, and baseUrl.
38
+ * @returns The native AI SDK GenerateTextResult promise.
39
+ */
40
+ export declare function generateText(options: HernexGenerateTextOptions): ReturnType<typeof aiGenerateText>;
41
+ /**
42
+ * Parameters for Hernex streamText runtime call, requiring model, apiKey, and baseUrl
43
+ * while forwarding all native AI SDK options.
44
+ */
45
+ export type HernexStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], "model"> & {
46
+ /**
47
+ * The model specification, formatted as "provider/model_id" (e.g. "openai/gpt-4o")
48
+ * or a pre-instantiated LanguageModel.
49
+ */
50
+ readonly model: HernexModelInput;
51
+ /**
52
+ * The mandatory API key for the target model or provider.
53
+ */
54
+ readonly apiKey: string;
55
+ /**
56
+ * The mandatory base URL for the target model or provider endpoint.
57
+ */
58
+ readonly baseUrl: string;
59
+ /**
60
+ * Optional custom provider registry for isolated resolution.
61
+ */
62
+ readonly providerRegistry?: ProviderRegistry;
63
+ };
64
+ /**
65
+ * Streams text from the specified model and credentials.
66
+ *
67
+ * Dynamically resolves the provider and model, applies credentials,
68
+ * and delegates to Vercel AI SDK's native `streamText`.
69
+ *
70
+ * @param options - Streaming generation options with required model, apiKey, and baseUrl.
71
+ * @returns The native AI SDK StreamTextResult instance.
72
+ */
73
+ export declare function streamText(options: HernexStreamTextOptions): ReturnType<typeof aiStreamText>;
74
+ //# sourceMappingURL=runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.d.ts","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,IAAI,cAAc,EAC9B,UAAU,IAAI,YAAY,EAC3B,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,EACpC,OAAO,CACR,GAAG;IACF;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,yBAAyB,GACjC,UAAU,CAAC,OAAO,cAAc,CAAC,CASnC;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CACxC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAClC,OAAO,CACR,GAAG;IACF;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,uBAAuB,GAC/B,UAAU,CAAC,OAAO,YAAY,CAAC,CASjC"}
@@ -0,0 +1,41 @@
1
+ /**
2
+ * @fileoverview Curated Hernex runtime wrappers around Vercel AI SDK functions.
3
+ * @packageDocumentation
4
+ */
5
+ import { generateText as aiGenerateText, streamText as aiStreamText, } from "ai";
6
+ import { resolveModel } from "./model/resolveModel.js";
7
+ /**
8
+ * Generates text using the specified model and credentials.
9
+ *
10
+ * Dynamically resolves the provider and model according to the first-slash rule,
11
+ * applies credentials, and forwards all options to Vercel AI SDK's native `generateText`.
12
+ *
13
+ * @param options - Generation options with required model, apiKey, and baseUrl.
14
+ * @returns The native AI SDK GenerateTextResult promise.
15
+ */
16
+ export async function generateText(options) {
17
+ const { model, apiKey, baseUrl, providerRegistry, ...rest } = options;
18
+ const resolvedModel = resolveModel(model, { apiKey, baseUrl }, providerRegistry);
19
+ return aiGenerateText({
20
+ ...rest,
21
+ model: resolvedModel,
22
+ });
23
+ }
24
+ /**
25
+ * Streams text from the specified model and credentials.
26
+ *
27
+ * Dynamically resolves the provider and model, applies credentials,
28
+ * and delegates to Vercel AI SDK's native `streamText`.
29
+ *
30
+ * @param options - Streaming generation options with required model, apiKey, and baseUrl.
31
+ * @returns The native AI SDK StreamTextResult instance.
32
+ */
33
+ export function streamText(options) {
34
+ const { model, apiKey, baseUrl, providerRegistry, ...rest } = options;
35
+ const resolvedModel = resolveModel(model, { apiKey, baseUrl }, providerRegistry);
36
+ return aiStreamText({
37
+ ...rest,
38
+ model: resolvedModel,
39
+ });
40
+ }
41
+ //# sourceMappingURL=runtime.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.js","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,IAAI,cAAc,EAC9B,UAAU,IAAI,YAAY,GAC3B,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAkCvD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAkC;IAElC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEtE,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAEjF,OAAO,cAAc,CAAC;QACpB,GAAG,IAAI;QACP,KAAK,EAAE,aAAa;KACmB,CAAC,CAAC;AAC7C,CAAC;AAgCD;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CACxB,OAAgC;IAEhC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEtE,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAEjF,OAAO,YAAY,CAAC;QAClB,GAAG,IAAI;QACP,KAAK,EAAE,aAAa;KACiB,CAAC,CAAC;AAC3C,CAAC"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @fileoverview Atomic file write operations with temporary sibling staging.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * Options for configuring atomic file write behavior.
7
+ */
8
+ export interface AtomicWriteOptions {
9
+ /** File mode permission bits. */
10
+ readonly mode?: number;
11
+ }
12
+ /**
13
+ * Writes data to a file atomically by writing to an exclusive sibling temporary file
14
+ * and then renaming it over the destination.
15
+ *
16
+ * Sibling temp files use a cryptographically random UUID to prevent collision across
17
+ * concurrent writers. If an error occurs during write or rename and temp file cleanup
18
+ * also fails, an AggregateError preserving both failures is thrown.
19
+ *
20
+ * @param filePath - The destination file path.
21
+ * @param content - Data string or Uint8Array buffer to write.
22
+ * @param options - Optional file mode options.
23
+ * @returns Total bytes written.
24
+ * @throws {AggregateError} If writing/renaming fails and cleanup also encounters an error.
25
+ * @throws {Error} If write or rename fails and cleanup succeeds.
26
+ */
27
+ export declare function atomicWriteFile(filePath: string, content: string | Uint8Array, options?: AtomicWriteOptions): Promise<number>;
28
+ //# sourceMappingURL=atomicFile.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"atomicFile.d.ts","sources":["../../src/storage/atomicFile.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAsCjB"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * @fileoverview Atomic file write operations with temporary sibling staging.
3
+ * @packageDocumentation
4
+ */
5
+ import { randomUUID } from "node:crypto";
6
+ import { existsSync } from "node:fs";
7
+ import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
8
+ import path from "node:path";
9
+ /**
10
+ * Writes data to a file atomically by writing to an exclusive sibling temporary file
11
+ * and then renaming it over the destination.
12
+ *
13
+ * Sibling temp files use a cryptographically random UUID to prevent collision across
14
+ * concurrent writers. If an error occurs during write or rename and temp file cleanup
15
+ * also fails, an AggregateError preserving both failures is thrown.
16
+ *
17
+ * @param filePath - The destination file path.
18
+ * @param content - Data string or Uint8Array buffer to write.
19
+ * @param options - Optional file mode options.
20
+ * @returns Total bytes written.
21
+ * @throws {AggregateError} If writing/renaming fails and cleanup also encounters an error.
22
+ * @throws {Error} If write or rename fails and cleanup succeeds.
23
+ */
24
+ export async function atomicWriteFile(filePath, content, options) {
25
+ const absolutePath = path.resolve(filePath);
26
+ const parentDir = path.dirname(absolutePath);
27
+ if (!existsSync(parentDir)) {
28
+ await mkdir(parentDir, { recursive: true });
29
+ }
30
+ const tempPath = `${absolutePath}.tmp.${randomUUID()}`;
31
+ const buffer = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
32
+ try {
33
+ await writeFile(tempPath, buffer, {
34
+ mode: options?.mode,
35
+ flag: "wx",
36
+ });
37
+ await rename(tempPath, absolutePath);
38
+ return buffer.length;
39
+ }
40
+ catch (primaryError) {
41
+ let cleanupError = null;
42
+ try {
43
+ await unlink(tempPath);
44
+ }
45
+ catch (error) {
46
+ if (error?.code !== "ENOENT") {
47
+ cleanupError = error;
48
+ }
49
+ }
50
+ if (cleanupError) {
51
+ throw new AggregateError([primaryError, cleanupError], `Failed to atomically write "${absolutePath}" and failed to clean up temporary file "${tempPath}".`);
52
+ }
53
+ throw primaryError;
54
+ }
55
+ }
56
+ //# sourceMappingURL=atomicFile.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"atomicFile.js","sources":["../../src/storage/atomicFile.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAA4B,EAC5B,OAA4B;IAE5B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAE7C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,YAAY,QAAQ,UAAU,EAAE,EAAE,CAAC;IACvD,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAExE,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE;YAChC,IAAI,EAAE,OAAO,EAAE,IAAI;YACnB,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAAC,OAAO,YAAY,EAAE,CAAC;QACtB,IAAI,YAAY,GAAY,IAAI,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxD,YAAY,GAAG,KAAK,CAAC;YACvB,CAAC;QACH,CAAC;QAED,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,IAAI,cAAc,CACtB,CAAC,YAAY,EAAE,YAAY,CAAC,EAC5B,+BAA+B,YAAY,4CAA4C,QAAQ,IAAI,CACpG,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,CAAC;IACrB,CAAC;AACH,CAAC"}
@@ -0,0 +1,21 @@
1
+ /**
2
+ * @fileoverview Resolves home directory configuration for Hernex state storage.
3
+ * @packageDocumentation
4
+ */
5
+ export interface ResolveHomeDirectoryOptions {
6
+ /** Explicit override for the storage home directory. */
7
+ readonly homeDirectory?: string;
8
+ }
9
+ /**
10
+ * Resolves the authoritative home directory for Hernex threads and checkpoints.
11
+ *
12
+ * Precedence:
13
+ * 1. Explicit `options.homeDirectory`
14
+ * 2. `process.env.HERNEX_HOME`
15
+ * 3. Default fallback: `path.join(os.homedir(), '.greg')`
16
+ *
17
+ * @param options - Optional configuration parameters.
18
+ * @returns Fully normalized absolute directory path.
19
+ */
20
+ export declare function resolveHomeDirectory(options?: ResolveHomeDirectoryOptions): string;
21
+ //# sourceMappingURL=homeDirectory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"homeDirectory.d.ts","sources":["../../src/storage/homeDirectory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,2BAA2B;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,2BAA2B,GACpC,MAAM,CAoBR"}
@@ -0,0 +1,36 @@
1
+ /**
2
+ * @fileoverview Resolves home directory configuration for Hernex state storage.
3
+ * @packageDocumentation
4
+ */
5
+ import os from "node:os";
6
+ import path from "node:path";
7
+ /**
8
+ * Resolves the authoritative home directory for Hernex threads and checkpoints.
9
+ *
10
+ * Precedence:
11
+ * 1. Explicit `options.homeDirectory`
12
+ * 2. `process.env.HERNEX_HOME`
13
+ * 3. Default fallback: `path.join(os.homedir(), '.greg')`
14
+ *
15
+ * @param options - Optional configuration parameters.
16
+ * @returns Fully normalized absolute directory path.
17
+ */
18
+ export function resolveHomeDirectory(options) {
19
+ let resolved;
20
+ if (options?.homeDirectory && options.homeDirectory.trim().length > 0) {
21
+ resolved = options.homeDirectory.trim();
22
+ }
23
+ else if (process.env.HERNEX_HOME &&
24
+ process.env.HERNEX_HOME.trim().length > 0) {
25
+ resolved = process.env.HERNEX_HOME.trim();
26
+ }
27
+ else {
28
+ resolved = path.join(os.homedir(), ".greg");
29
+ }
30
+ // Expand leading tilde
31
+ if (resolved === "~" || resolved.startsWith("~" + path.sep)) {
32
+ resolved = path.join(os.homedir(), resolved.slice(1));
33
+ }
34
+ return path.resolve(resolved);
35
+ }
36
+ //# sourceMappingURL=homeDirectory.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"homeDirectory.js","sources":["../../src/storage/homeDirectory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAqC;IAErC,IAAI,QAAgB,CAAC;IAErB,IAAI,OAAO,EAAE,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;SAAM,IACL,OAAO,CAAC,GAAG,CAAC,WAAW;QACvB,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EACzC,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,uBAAuB;IACvB,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * @fileoverview Storage primitives export barrel for Hernex.
3
+ * @packageDocumentation
4
+ */
5
+ export * from "./homeDirectory.js";
6
+ export * from "./atomicFile.js";
7
+ export * from "./lock.js";
8
+ export * from "./jsonl.js";
9
+ export * from "./valueCodec.js";
10
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * @fileoverview Storage primitives export barrel for Hernex.
3
+ * @packageDocumentation
4
+ */
5
+ export * from "./homeDirectory.js";
6
+ export * from "./atomicFile.js";
7
+ export * from "./lock.js";
8
+ export * from "./jsonl.js";
9
+ export * from "./valueCodec.js";
10
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
@@ -0,0 +1,46 @@
1
+ /**
2
+ * @fileoverview Robust append-only JSONL parser and appender with torn-tail recovery and tagged value codec.
3
+ * @packageDocumentation
4
+ */
5
+ import { type EncodedValue } from "./valueCodec.js";
6
+ /**
7
+ * Versioned envelope wrapper used to store encoded values in JSONL streams.
8
+ */
9
+ export interface JsonlEnvelope {
10
+ /** Format schema version. */
11
+ readonly version: 1;
12
+ /** Encoded value payload. */
13
+ readonly value: EncodedValue;
14
+ }
15
+ /**
16
+ * Type guard for checking if a parsed JSON object is a JsonlEnvelope.
17
+ *
18
+ * @param value - Value to inspect.
19
+ * @returns True if value conforms to JsonlEnvelope shape.
20
+ */
21
+ export declare function isJsonlEnvelope(value: unknown): value is JsonlEnvelope;
22
+ /**
23
+ * Appends a record to a JSONL file with trailing newline using a versioned tagged envelope.
24
+ *
25
+ * Before appending, if the file contains a torn non-newline-terminated final line,
26
+ * it is verified and repaired under the caller's lock before appending. Truncate
27
+ * failures propagate fail-closed.
28
+ *
29
+ * @param filePath - The target JSONL file.
30
+ * @param record - Record or value to serialize and append.
31
+ * @throws {TypeError} If record contains non-serializable values (e.g. functions, cycles).
32
+ * @throws {Error} If torn-tail repair or write fails.
33
+ */
34
+ export declare function appendJsonl<T>(filePath: string, record: T): Promise<void>;
35
+ /**
36
+ * Reads all records from a JSONL file, recovering only from torn non-newline-terminated final lines.
37
+ *
38
+ * Malformed middle lines or newline-terminated malformed lines remain fatal and throw.
39
+ * Truncate failures propagate immediately. Legacy untagged raw JSON lines are parsed as fallback.
40
+ *
41
+ * @param filePath - The JSONL file to read.
42
+ * @returns Array of parsed records.
43
+ * @throws {Error} When encountering corrupted middle or newline-terminated records.
44
+ */
45
+ export declare function readJsonl<T>(filePath: string): Promise<T[]>;
46
+ //# sourceMappingURL=jsonl.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jsonl.d.ts","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAA4B,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAUtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C/E;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CA+CjE"}