@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,157 @@
1
+ /**
2
+ * @fileoverview Checkpoint, delta snapshot, and rollback type definitions.
3
+ * @packageDocumentation
4
+ */
5
+ /**
6
+ * File mutation state captured inside a checkpoint snapshot.
7
+ */
8
+ export interface CheckpointFileRecord {
9
+ /** Relative workspace path. */
10
+ readonly relativePath: string;
11
+ /** SHA-256 hash of the file content before mutation, or null if the file did not exist. */
12
+ readonly beforeHash: string | null;
13
+ /** SHA-256 hash of the file content after mutation, or null if the file was deleted. */
14
+ readonly afterHash: string | null;
15
+ }
16
+ /**
17
+ * Persisted snapshot record capturing a state transition for specific workspace files.
18
+ */
19
+ export interface CheckpointRecord {
20
+ /** Unique safe checkpoint identifier. */
21
+ readonly id: string;
22
+ /** Monotonically increasing sequence number within the thread's checkpoint log. */
23
+ readonly sequence: number;
24
+ /** Safe thread identifier that owns this checkpoint. */
25
+ readonly threadId: string;
26
+ /** One-based agent turn index during which this checkpoint was recorded, or undefined if created outside an active engine turn. */
27
+ readonly turnIndex?: number | undefined;
28
+ /** Descriptive human-readable label for the checkpoint. */
29
+ readonly label: string;
30
+ /** Source attributing creation to manual product code or a specific tool execution. */
31
+ readonly source: "manual" | {
32
+ readonly toolName: string;
33
+ };
34
+ /** Unix timestamp in milliseconds when the checkpoint was created. */
35
+ readonly timestamp: number;
36
+ /** Explicitly captured file records with before and after state hashes. */
37
+ readonly files: readonly CheckpointFileRecord[];
38
+ }
39
+ /**
40
+ * Input parameters for creating a new checkpoint snapshot prior to mutation.
41
+ */
42
+ export interface CreateCheckpointInput {
43
+ /** Canonical workspace root directory. */
44
+ readonly workingDirectory: string;
45
+ /** Optional one-based agent turn index. Omit when recorded outside an active agent turn. */
46
+ readonly turnIndex?: number | undefined;
47
+ /** Descriptive label. */
48
+ readonly label: string;
49
+ /** Explicit relative file paths to capture. Must contain at least one path. */
50
+ readonly files: readonly string[];
51
+ /** Optional source attribution. Defaults to "manual". */
52
+ readonly source?: "manual" | {
53
+ readonly toolName: string;
54
+ } | undefined;
55
+ }
56
+ /**
57
+ * Planned file restoration action evaluated against current workspace content.
58
+ */
59
+ export interface RestoreFileAction {
60
+ /** Relative workspace path. */
61
+ readonly relativePath: string;
62
+ /** Action required to restore the file to its beforeHash state. */
63
+ readonly action: "unchanged" | "create" | "modify" | "delete";
64
+ /** Whether the current file content conflicts with both before and after recorded states. */
65
+ readonly isConflict: boolean;
66
+ }
67
+ /**
68
+ * Detailed restoration plan containing file actions and conflict status.
69
+ */
70
+ export interface RestorePlan {
71
+ /** Checkpoint identifier being evaluated. */
72
+ readonly checkpointId: string;
73
+ /** Actions required for each file in the snapshot. */
74
+ readonly actions: readonly RestoreFileAction[];
75
+ /** Whether any uncommitted external modifications conflict with the rollback. */
76
+ readonly hasConflicts: boolean;
77
+ }
78
+ /**
79
+ * Summary outcome of executing a checkpoint restoration plan.
80
+ */
81
+ export interface RestoreResult {
82
+ /** Checkpoint identifier that was restored. */
83
+ readonly checkpointId: string;
84
+ /** Number of files created or modified back to their pre-state. */
85
+ readonly filesRestored: number;
86
+ /** Number of files deleted because they were newly created by the tool. */
87
+ readonly filesDeleted: number;
88
+ /** Number of conflicting files overwritten when force was true. */
89
+ readonly conflictsOverwritten: number;
90
+ }
91
+ /**
92
+ * Store interface managing checkpoint recording, delta blobs, and safe restoration.
93
+ */
94
+ export interface CheckpointStore {
95
+ /**
96
+ * Records a pre-mutation snapshot of the specified workspace files.
97
+ *
98
+ * @param threadId - Safe thread identifier.
99
+ * @param input - Checkpoint creation parameters.
100
+ * @returns Newly recorded CheckpointRecord.
101
+ */
102
+ createCheckpoint(threadId: string, input: CreateCheckpointInput): Promise<CheckpointRecord>;
103
+ /**
104
+ * Retrieves a checkpoint record by thread and checkpoint identifier.
105
+ *
106
+ * @param threadId - Safe thread identifier.
107
+ * @param checkpointId - Safe checkpoint identifier.
108
+ * @returns Checkpoint record or undefined if not found.
109
+ */
110
+ getCheckpoint(threadId: string, checkpointId: string): Promise<CheckpointRecord | undefined>;
111
+ /**
112
+ * Lists all recorded checkpoints for a thread ordered chronologically.
113
+ *
114
+ * @param threadId - Safe thread identifier.
115
+ * @returns Readonly array of checkpoint records.
116
+ */
117
+ listCheckpoints(threadId: string): Promise<readonly CheckpointRecord[]>;
118
+ /**
119
+ * Updates an existing checkpoint after mutation with the post-state file hashes.
120
+ *
121
+ * @param threadId - Safe thread identifier.
122
+ * @param checkpointId - Safe checkpoint identifier.
123
+ * @param workingDirectory - Canonical workspace root directory.
124
+ * @returns Updated CheckpointRecord.
125
+ */
126
+ updateCheckpoint(threadId: string, checkpointId: string, workingDirectory: string): Promise<CheckpointRecord>;
127
+ /**
128
+ * Deletes a checkpoint record from the thread manifest.
129
+ *
130
+ * @param threadId - Safe thread identifier.
131
+ * @param checkpointId - Safe checkpoint identifier.
132
+ * @returns True if checkpoint existed and was removed, false otherwise.
133
+ */
134
+ deleteCheckpoint(threadId: string, checkpointId: string): Promise<boolean>;
135
+ /**
136
+ * Preflights and plans the restoration of a checkpoint without mutating files.
137
+ *
138
+ * @param threadId - Safe thread identifier.
139
+ * @param checkpointId - Safe checkpoint identifier.
140
+ * @param workingDirectory - Canonical workspace root directory.
141
+ * @returns Restore plan detailing actions and conflicts.
142
+ */
143
+ planRestore(threadId: string, checkpointId: string, workingDirectory: string): Promise<RestorePlan>;
144
+ /**
145
+ * Restores workspace files to their recorded pre-mutation state.
146
+ *
147
+ * @param threadId - Safe thread identifier.
148
+ * @param checkpointId - Safe checkpoint identifier.
149
+ * @param workingDirectory - Canonical workspace root directory.
150
+ * @param options - Optional restoration options including force flag.
151
+ * @returns Restore result summary.
152
+ */
153
+ restoreCheckpoint(threadId: string, checkpointId: string, workingDirectory: string, options?: {
154
+ readonly force?: boolean;
155
+ } | undefined): Promise<RestoreResult>;
156
+ }
157
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sources":["../../src/checkpoints/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * @fileoverview Checkpoint, delta snapshot, and rollback type definitions.
3
+ * @packageDocumentation
4
+ */
5
+ export {};
6
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sources":["../../src/checkpoints/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
@@ -0,0 +1,156 @@
1
+ /**
2
+ * @fileoverview Stateful microkernel class orchestrating turns, tools, and lifecycle hooks.
3
+ * @packageDocumentation
4
+ */
5
+ import type { HernexModelInput, ModelMessage } from "../model/types.js";
6
+ import type { ProviderRegistry } from "../model/ProviderRegistry.js";
7
+ import type { AgentEvent } from "../events/index.js";
8
+ import { type AgentReasoningLevel, type ThreadStore } from "../threads/index.js";
9
+ import { type CheckpointStore } from "../checkpoints/index.js";
10
+ import type { ToolRegistry } from "../tools/index.js";
11
+ import { TaskManager } from "../tools/index.js";
12
+ import type { AgentEngineConfig, RunTurnOptions } from "./engineConfig.js";
13
+ /**
14
+ * The core agent engine microkernel.
15
+ *
16
+ * Encapsulates thread state, conversational message history, tool registry access,
17
+ * autonomous multi-step turn execution, and checkpoint/rollback management.
18
+ */
19
+ export declare class AgentEngine {
20
+ private readonly config;
21
+ private readonly conversationMessages;
22
+ private readonly resolvedThreadStore;
23
+ private readonly resolvedCheckpointStore;
24
+ private readonly resolvedTaskManager;
25
+ private readonly isPersistActive;
26
+ private readonly isCheckpointActive;
27
+ private turnCounter;
28
+ private isTurnRunning;
29
+ private currentTurnAbortController;
30
+ /**
31
+ * Instantiates a new AgentEngine.
32
+ *
33
+ * @param config - Static engine configuration options.
34
+ * @param initialMessages - Optional previous conversation messages to seed or resume the thread.
35
+ * @param initialTurnCount - Optional initial turn count (e.g. from persisted thread metadata).
36
+ */
37
+ constructor(config: AgentEngineConfig, initialMessages?: readonly ModelMessage[], initialTurnCount?: number);
38
+ /**
39
+ * Resumes an engine instance from an existing thread in a ThreadStore.
40
+ *
41
+ * @param threadId - The identifier of the thread to load.
42
+ * @param options - Configuration options for resuming.
43
+ * @returns An instantiated AgentEngine loaded with the thread's messages and metadata.
44
+ */
45
+ static fromThread(threadId: string, options: {
46
+ readonly threadStore: ThreadStore;
47
+ readonly checkpointStore?: CheckpointStore;
48
+ readonly tools: ToolRegistry;
49
+ readonly apiKey: string;
50
+ readonly baseUrl: string;
51
+ readonly model?: HernexModelInput;
52
+ readonly providerRegistry?: ProviderRegistry;
53
+ readonly taskManager?: TaskManager;
54
+ readonly instructions?: string;
55
+ readonly reasoning?: AgentReasoningLevel;
56
+ readonly maxSteps?: number;
57
+ readonly abortSignal?: AbortSignal;
58
+ readonly checkpoint?: boolean;
59
+ }): Promise<AgentEngine>;
60
+ /**
61
+ * Creates a new thread in the thread store and initializes a corresponding AgentEngine.
62
+ *
63
+ * @param options - Thread creation and engine configuration options.
64
+ * @returns An instantiated AgentEngine for the newly created thread.
65
+ */
66
+ static create(options: {
67
+ readonly threadStore: ThreadStore;
68
+ readonly checkpointStore?: CheckpointStore;
69
+ readonly workingDirectory: string;
70
+ readonly model: HernexModelInput;
71
+ readonly apiKey: string;
72
+ readonly baseUrl: string;
73
+ readonly providerRegistry?: ProviderRegistry;
74
+ readonly taskManager?: TaskManager;
75
+ readonly title?: string;
76
+ readonly tags?: readonly string[];
77
+ readonly instructions?: string;
78
+ readonly tools: ToolRegistry;
79
+ readonly reasoning?: AgentReasoningLevel;
80
+ readonly maxSteps?: number;
81
+ readonly abortSignal?: AbortSignal;
82
+ readonly checkpoint?: boolean;
83
+ }): Promise<AgentEngine>;
84
+ /**
85
+ * Gets the thread identifier.
86
+ */
87
+ get threadId(): string;
88
+ /**
89
+ * Gets the active workspace root directory path.
90
+ */
91
+ get workingDirectory(): string;
92
+ /**
93
+ * Gets the tool registry bound to this engine instance.
94
+ */
95
+ get tools(): ToolRegistry;
96
+ /**
97
+ * Gets a readonly snapshot of the current conversational messages.
98
+ */
99
+ get messages(): readonly ModelMessage[];
100
+ /**
101
+ * Gets the number of completed or executed turns in this thread.
102
+ */
103
+ get currentTurn(): number;
104
+ /**
105
+ * Gets the top-level reasoning level configured on the engine, if any.
106
+ */
107
+ get reasoning(): AgentReasoningLevel | undefined;
108
+ /**
109
+ * Whether thread state and transcripts are actively persisted to disk.
110
+ */
111
+ get isPersisted(): boolean;
112
+ /**
113
+ * Whether content-addressed file delta checkpointing is actively enabled.
114
+ */
115
+ get isCheckpointEnabled(): boolean;
116
+ /**
117
+ * Gets the TaskManager instance associated with this engine instance.
118
+ */
119
+ get taskManager(): TaskManager;
120
+ /**
121
+ * Gets the persistent ThreadStore attached to this engine, if any.
122
+ */
123
+ get threadStore(): ThreadStore | undefined;
124
+ /**
125
+ * Gets the CheckpointStore attached to this engine, if any.
126
+ */
127
+ get checkpointStore(): CheckpointStore | undefined;
128
+ /**
129
+ * Aborts the currently active turn, if any.
130
+ *
131
+ * @param reason - Optional cancellation reason.
132
+ */
133
+ abort(reason?: string): void;
134
+ /**
135
+ * Appends an external message into the conversation history.
136
+ * If threadStore is present, appends to the persistent transcript first.
137
+ *
138
+ * @param message - The ModelMessage to append.
139
+ */
140
+ addMessage(message: ModelMessage): Promise<void>;
141
+ /**
142
+ * Executes a single autonomous agent turn.
143
+ *
144
+ * Turn reservation occurs lazily when the returned async generator is first consumed.
145
+ *
146
+ * @param promptOrOptions - User prompt string or full turn execution options.
147
+ * @returns An async generator yielding stream deltas, tool lifecycle, and turn events.
148
+ * @throws Error if another turn is actively running on this engine instance when iteration begins.
149
+ */
150
+ runTurn(promptOrOptions: string | RunTurnOptions): AsyncGenerator<AgentEvent, void, void>;
151
+ /**
152
+ * Internal generator driving turn execution and tracking concurrency state lazily on consumption.
153
+ */
154
+ private executeTurn;
155
+ }
156
+ //# sourceMappingURL=AgentEngine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentEngine.d.ts","sources":["../../src/engine/AgentEngine.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,290 @@
1
+ /**
2
+ * @fileoverview Stateful microkernel class orchestrating turns, tools, and lifecycle hooks.
3
+ * @packageDocumentation
4
+ */
5
+ import { FileThreadStore, CURRENT_TRANSCRIPT_VERSION, } from "../threads/index.js";
6
+ import { FileCheckpointStore, } from "../checkpoints/index.js";
7
+ import { TaskManager } from "../tools/index.js";
8
+ import { runTurn } from "./runTurn.js";
9
+ /**
10
+ * The core agent engine microkernel.
11
+ *
12
+ * Encapsulates thread state, conversational message history, tool registry access,
13
+ * autonomous multi-step turn execution, and checkpoint/rollback management.
14
+ */
15
+ export class AgentEngine {
16
+ config;
17
+ conversationMessages;
18
+ resolvedThreadStore;
19
+ resolvedCheckpointStore;
20
+ resolvedTaskManager;
21
+ isPersistActive;
22
+ isCheckpointActive;
23
+ turnCounter = 0;
24
+ isTurnRunning = false;
25
+ currentTurnAbortController = null;
26
+ /**
27
+ * Instantiates a new AgentEngine.
28
+ *
29
+ * @param config - Static engine configuration options.
30
+ * @param initialMessages - Optional previous conversation messages to seed or resume the thread.
31
+ * @param initialTurnCount - Optional initial turn count (e.g. from persisted thread metadata).
32
+ */
33
+ constructor(config, initialMessages, initialTurnCount) {
34
+ this.conversationMessages = initialMessages ? [...initialMessages] : [];
35
+ this.turnCounter = initialTurnCount ?? 0;
36
+ // Evaluate persistence: default is false (ephemeral) unless explicitly set or store provided
37
+ this.isPersistActive = Boolean(config.persist ?? Boolean(config.threadStore));
38
+ // Enforce invariant: checkpoints require persistent thread storage
39
+ if (config.checkpoint && !this.isPersistActive) {
40
+ throw new Error("Checkpoints require persistent thread storage (`persist: true` or `threadStore`). Checkpointing cannot be enabled for ephemeral threads.");
41
+ }
42
+ // Resolve checkpoint active state
43
+ this.isCheckpointActive =
44
+ this.isPersistActive &&
45
+ Boolean(config.checkpoint ?? Boolean(config.checkpointStore));
46
+ // Resolve stores according to persistence flags
47
+ if (this.isPersistActive) {
48
+ this.resolvedThreadStore = config.threadStore ?? new FileThreadStore();
49
+ }
50
+ else {
51
+ this.resolvedThreadStore = undefined;
52
+ }
53
+ if (this.isCheckpointActive) {
54
+ this.resolvedCheckpointStore =
55
+ config.checkpointStore ?? new FileCheckpointStore();
56
+ }
57
+ else {
58
+ this.resolvedCheckpointStore = undefined;
59
+ }
60
+ this.resolvedTaskManager =
61
+ config.taskManager ??
62
+ new TaskManager({
63
+ threadId: config.threadId,
64
+ workingDirectory: config.workingDirectory,
65
+ persist: this.isPersistActive,
66
+ });
67
+ this.config = {
68
+ ...config,
69
+ threadStore: this.resolvedThreadStore,
70
+ checkpointStore: this.resolvedCheckpointStore,
71
+ taskManager: this.resolvedTaskManager,
72
+ persist: this.isPersistActive,
73
+ checkpoint: this.isCheckpointActive,
74
+ };
75
+ }
76
+ /**
77
+ * Resumes an engine instance from an existing thread in a ThreadStore.
78
+ *
79
+ * @param threadId - The identifier of the thread to load.
80
+ * @param options - Configuration options for resuming.
81
+ * @returns An instantiated AgentEngine loaded with the thread's messages and metadata.
82
+ */
83
+ static async fromThread(threadId, options) {
84
+ const metadata = await options.threadStore.getThread(threadId);
85
+ if (!metadata) {
86
+ throw new Error(`Thread not found: "${threadId}"`);
87
+ }
88
+ const messages = await options.threadStore.getMessages(threadId);
89
+ const resolvedModel = options.model ?? metadata.model;
90
+ if (!resolvedModel) {
91
+ throw new Error(`Thread "${threadId}" was stored without a model string identifier. An explicit model must be provided in fromThread options.`);
92
+ }
93
+ return new AgentEngine({
94
+ threadId,
95
+ workingDirectory: metadata.workingDirectory,
96
+ model: resolvedModel,
97
+ apiKey: options.apiKey,
98
+ baseUrl: options.baseUrl,
99
+ instructions: options.instructions,
100
+ tools: options.tools,
101
+ providerRegistry: options.providerRegistry,
102
+ taskManager: options.taskManager,
103
+ reasoning: metadata.reasoning ?? options.reasoning,
104
+ maxSteps: options.maxSteps,
105
+ persist: true,
106
+ checkpoint: options.checkpoint ?? Boolean(options.checkpointStore),
107
+ threadStore: options.threadStore,
108
+ checkpointStore: options.checkpointStore,
109
+ abortSignal: options.abortSignal,
110
+ }, messages, metadata.turnCount);
111
+ }
112
+ /**
113
+ * Creates a new thread in the thread store and initializes a corresponding AgentEngine.
114
+ *
115
+ * @param options - Thread creation and engine configuration options.
116
+ * @returns An instantiated AgentEngine for the newly created thread.
117
+ */
118
+ static async create(options) {
119
+ const metadata = await options.threadStore.createThread({
120
+ workingDirectory: options.workingDirectory,
121
+ model: typeof options.model === "string" ? options.model : undefined,
122
+ reasoning: options.reasoning,
123
+ title: options.title,
124
+ tags: options.tags,
125
+ });
126
+ return new AgentEngine({
127
+ threadId: metadata.id,
128
+ workingDirectory: options.workingDirectory,
129
+ model: options.model,
130
+ apiKey: options.apiKey,
131
+ baseUrl: options.baseUrl,
132
+ providerRegistry: options.providerRegistry,
133
+ taskManager: options.taskManager,
134
+ instructions: options.instructions,
135
+ tools: options.tools,
136
+ reasoning: options.reasoning,
137
+ maxSteps: options.maxSteps,
138
+ persist: true,
139
+ checkpoint: options.checkpoint ?? Boolean(options.checkpointStore),
140
+ threadStore: options.threadStore,
141
+ checkpointStore: options.checkpointStore,
142
+ abortSignal: options.abortSignal,
143
+ }, [], 0);
144
+ }
145
+ /**
146
+ * Gets the thread identifier.
147
+ */
148
+ get threadId() {
149
+ return this.config.threadId;
150
+ }
151
+ /**
152
+ * Gets the active workspace root directory path.
153
+ */
154
+ get workingDirectory() {
155
+ return this.config.workingDirectory;
156
+ }
157
+ /**
158
+ * Gets the tool registry bound to this engine instance.
159
+ */
160
+ get tools() {
161
+ return this.config.tools;
162
+ }
163
+ /**
164
+ * Gets a readonly snapshot of the current conversational messages.
165
+ */
166
+ get messages() {
167
+ return [...this.conversationMessages];
168
+ }
169
+ /**
170
+ * Gets the number of completed or executed turns in this thread.
171
+ */
172
+ get currentTurn() {
173
+ return this.turnCounter;
174
+ }
175
+ /**
176
+ * Gets the top-level reasoning level configured on the engine, if any.
177
+ */
178
+ get reasoning() {
179
+ return this.config.reasoning;
180
+ }
181
+ /**
182
+ * Whether thread state and transcripts are actively persisted to disk.
183
+ */
184
+ get isPersisted() {
185
+ return this.isPersistActive;
186
+ }
187
+ /**
188
+ * Whether content-addressed file delta checkpointing is actively enabled.
189
+ */
190
+ get isCheckpointEnabled() {
191
+ return this.isCheckpointActive;
192
+ }
193
+ /**
194
+ * Gets the TaskManager instance associated with this engine instance.
195
+ */
196
+ get taskManager() {
197
+ return this.resolvedTaskManager;
198
+ }
199
+ /**
200
+ * Gets the persistent ThreadStore attached to this engine, if any.
201
+ */
202
+ get threadStore() {
203
+ return this.resolvedThreadStore;
204
+ }
205
+ /**
206
+ * Gets the CheckpointStore attached to this engine, if any.
207
+ */
208
+ get checkpointStore() {
209
+ return this.resolvedCheckpointStore;
210
+ }
211
+ /**
212
+ * Aborts the currently active turn, if any.
213
+ *
214
+ * @param reason - Optional cancellation reason.
215
+ */
216
+ abort(reason) {
217
+ if (this.currentTurnAbortController && this.isTurnRunning) {
218
+ this.currentTurnAbortController.abort(reason ?? "Turn aborted by caller");
219
+ }
220
+ }
221
+ /**
222
+ * Appends an external message into the conversation history.
223
+ * If threadStore is present, appends to the persistent transcript first.
224
+ *
225
+ * @param message - The ModelMessage to append.
226
+ */
227
+ async addMessage(message) {
228
+ if (this.isTurnRunning) {
229
+ throw new Error("Cannot add messages to conversation history while an active turn is running.");
230
+ }
231
+ if (this.resolvedThreadStore) {
232
+ await this.resolvedThreadStore.appendTranscript(this.threadId, {
233
+ version: CURRENT_TRANSCRIPT_VERSION,
234
+ type: "modelMessage",
235
+ message,
236
+ timestamp: Date.now(),
237
+ });
238
+ }
239
+ this.conversationMessages.push(message);
240
+ }
241
+ /**
242
+ * Executes a single autonomous agent turn.
243
+ *
244
+ * Turn reservation occurs lazily when the returned async generator is first consumed.
245
+ *
246
+ * @param promptOrOptions - User prompt string or full turn execution options.
247
+ * @returns An async generator yielding stream deltas, tool lifecycle, and turn events.
248
+ * @throws Error if another turn is actively running on this engine instance when iteration begins.
249
+ */
250
+ runTurn(promptOrOptions) {
251
+ const rawOptions = typeof promptOrOptions === "string"
252
+ ? { userPrompt: promptOrOptions }
253
+ : promptOrOptions;
254
+ return this.executeTurn(rawOptions);
255
+ }
256
+ /**
257
+ * Internal generator driving turn execution and tracking concurrency state lazily on consumption.
258
+ */
259
+ async *executeTurn(rawOptions) {
260
+ if (this.isTurnRunning) {
261
+ throw new Error(`AgentEngine for thread "${this.threadId}" is already running an active turn. Simultaneous turns on a single engine instance are not permitted.`);
262
+ }
263
+ this.isTurnRunning = true;
264
+ this.turnCounter++;
265
+ this.currentTurnAbortController = new AbortController();
266
+ const turnAbortSignals = [
267
+ this.currentTurnAbortController.signal,
268
+ ];
269
+ if (this.config.abortSignal) {
270
+ turnAbortSignals.push(this.config.abortSignal);
271
+ }
272
+ if (rawOptions.abortSignal) {
273
+ turnAbortSignals.push(rawOptions.abortSignal);
274
+ }
275
+ const combinedSignal = AbortSignal.any(turnAbortSignals);
276
+ const options = {
277
+ ...rawOptions,
278
+ turnIndex: rawOptions.turnIndex ?? this.turnCounter,
279
+ abortSignal: combinedSignal,
280
+ };
281
+ try {
282
+ yield* runTurn(this.config, options, this.conversationMessages);
283
+ }
284
+ finally {
285
+ this.isTurnRunning = false;
286
+ this.currentTurnAbortController = null;
287
+ }
288
+ }
289
+ }
290
+ //# sourceMappingURL=AgentEngine.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentEngine.js","sources":["../../src/engine/AgentEngine.ts"],"names":[],"mappings":"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"}