@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,158 @@
1
+ /**
2
+ * @fileoverview Built-in tool for executing shell commands in the workspace.
3
+ * Delegates process creation, streaming output, timeouts, and lifecycle management
4
+ * directly to the TaskManager instance injected in ToolExecutionContext.
5
+ * @packageDocumentation
6
+ */
7
+ import { z } from "zod";
8
+ import { bashDescription } from "./prompts.js";
9
+ /**
10
+ * Maximum character length captured in foreground memory before truncating output preview.
11
+ */
12
+ const maxBashOutputCharacters = 50000;
13
+ /**
14
+ * Default command timeout in milliseconds (60 seconds) when not specified.
15
+ */
16
+ const defaultBashTimeoutMs = 60000;
17
+ /**
18
+ * Default duration to wait in the foreground before detaching to background task (10 seconds).
19
+ */
20
+ const defaultWaitMsBeforeAsync = 10000;
21
+ /**
22
+ * Input parameter schema for BashTool.
23
+ */
24
+ export const bashInputSchema = z.object({
25
+ command: z
26
+ .string()
27
+ .min(1)
28
+ .describe("The shell command string to execute in the workspace directory."),
29
+ timeoutMs: z
30
+ .number()
31
+ .int()
32
+ .positive()
33
+ .optional()
34
+ .describe("Hard task lifetime in milliseconds before terminating the command (defaults to 60000)."),
35
+ waitMsBeforeAsync: z
36
+ .number()
37
+ .int()
38
+ .min(0)
39
+ .max(60000)
40
+ .optional()
41
+ .describe("Milliseconds to wait in foreground before detaching as a background task. " +
42
+ "0 moves immediately to background; default is 10000ms (10s); max is 60000ms (1m)."),
43
+ });
44
+ /**
45
+ * Built-in tool for executing shell commands.
46
+ * Commands run with the current operating system user's privileges in the workspace directory.
47
+ * The environment is filtered to avoid credential leakage, but execution is not an isolated sandbox.
48
+ */
49
+ export class BashTool {
50
+ static toolName = "bash";
51
+ name = BashTool.toolName;
52
+ description = bashDescription;
53
+ inputSchema = bashInputSchema;
54
+ /**
55
+ * Executes a shell command by delegating to the context TaskManager.
56
+ *
57
+ * @param parameters - Validated parameters containing command, timeoutMs, and waitMsBeforeAsync.
58
+ * @param context - The execution context with workingDirectory, taskManager, and emitProgress.
59
+ * @returns A promise resolving to the command execution output.
60
+ * @throws Error if context.taskManager is not configured.
61
+ */
62
+ async execute(parameters, context) {
63
+ if (context.abortSignal?.aborted) {
64
+ throw new Error(`Command aborted before execution: ${context.abortSignal.reason ?? "Aborted by signal"}`);
65
+ }
66
+ const taskManager = context.taskManager;
67
+ if (!taskManager) {
68
+ throw new Error("TaskManager is required in ToolExecutionContext to execute Bash commands.");
69
+ }
70
+ const startTime = Date.now();
71
+ const waitMsBeforeAsync = parameters.waitMsBeforeAsync ?? defaultWaitMsBeforeAsync;
72
+ const timeoutMs = parameters.timeoutMs ?? defaultBashTimeoutMs;
73
+ let observedOutput = "";
74
+ let isOutputTruncated = false;
75
+ let isObserving = true;
76
+ const onOutput = (chunk) => {
77
+ if (!isObserving)
78
+ return;
79
+ context.emitProgress?.(chunk);
80
+ if (observedOutput.length < maxBashOutputCharacters) {
81
+ const remaining = maxBashOutputCharacters - observedOutput.length;
82
+ if (chunk.length <= remaining) {
83
+ observedOutput += chunk;
84
+ }
85
+ else {
86
+ observedOutput += chunk.slice(0, remaining);
87
+ isOutputTruncated = true;
88
+ }
89
+ }
90
+ else {
91
+ isOutputTruncated = true;
92
+ }
93
+ };
94
+ const task = await taskManager.createTask({
95
+ command: parameters.command,
96
+ cwd: context.workingDirectory,
97
+ timeoutMs,
98
+ }, { onOutput });
99
+ if (waitMsBeforeAsync === 0) {
100
+ isObserving = false;
101
+ return {
102
+ status: "running",
103
+ command: parameters.command,
104
+ taskId: task.id,
105
+ output: observedOutput,
106
+ exitCode: null,
107
+ durationMs: Date.now() - startTime,
108
+ outputTruncated: isOutputTruncated,
109
+ };
110
+ }
111
+ try {
112
+ const waitResult = await taskManager.waitForTask(task.id, {
113
+ timeoutMs: waitMsBeforeAsync,
114
+ signal: context.abortSignal,
115
+ });
116
+ const durationMs = Date.now() - startTime;
117
+ if (waitResult.timedOut) {
118
+ return {
119
+ status: "running",
120
+ command: parameters.command,
121
+ taskId: task.id,
122
+ output: observedOutput,
123
+ exitCode: null,
124
+ durationMs,
125
+ outputTruncated: isOutputTruncated || waitResult.task.outputTruncated,
126
+ };
127
+ }
128
+ const finalStatus = waitResult.task.status === "orphaned"
129
+ ? "exited"
130
+ : waitResult.task.status;
131
+ return {
132
+ status: finalStatus,
133
+ command: parameters.command,
134
+ taskId: task.id,
135
+ output: observedOutput,
136
+ exitCode: waitResult.task.exitCode,
137
+ durationMs,
138
+ outputTruncated: isOutputTruncated || waitResult.task.outputTruncated,
139
+ };
140
+ }
141
+ catch (waitError) {
142
+ if (context.abortSignal?.aborted) {
143
+ // Foreground task was aborted: terminate the process tree and await terminal state
144
+ try {
145
+ await taskManager.stopTask(task.id);
146
+ }
147
+ catch {
148
+ // Process may have already exited
149
+ }
150
+ }
151
+ throw waitError;
152
+ }
153
+ finally {
154
+ isObserving = false;
155
+ }
156
+ }
157
+ }
158
+ //# sourceMappingURL=BashTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"BashTool.js","sources":["../../src/tools/BashTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,49 @@
1
+ /**
2
+ * @fileoverview Built-in tool for making targeted replacements within existing files.
3
+ * Validates match uniqueness and performs atomic file replacement with snapshot support.
4
+ * @packageDocumentation
5
+ */
6
+ import { z } from "zod";
7
+ import type { AgentTool } from "./AgentTool.js";
8
+ import type { ToolExecutionContext } from "./ToolExecutionContext.js";
9
+ /**
10
+ * Input parameter schema for EditFileTool.
11
+ */
12
+ export declare const editFileInputSchema: z.ZodObject<{
13
+ filePath: z.ZodString;
14
+ oldString: z.ZodString;
15
+ newString: z.ZodString;
16
+ replaceAll: z.ZodOptional<z.ZodBoolean>;
17
+ }, z.core.$strip>;
18
+ /**
19
+ * Result structure produced by EditFileTool.
20
+ */
21
+ export interface EditFileOutput {
22
+ readonly filePath: string;
23
+ readonly replacementsApplied: number;
24
+ readonly bytesWritten: number;
25
+ }
26
+ /**
27
+ * Built-in tool for targeted file editing.
28
+ */
29
+ export declare class EditFileTool implements AgentTool<typeof editFileInputSchema, EditFileOutput> {
30
+ static readonly toolName = "editFile";
31
+ readonly name = "editFile";
32
+ readonly description: string;
33
+ readonly inputSchema: z.ZodObject<{
34
+ filePath: z.ZodString;
35
+ oldString: z.ZodString;
36
+ newString: z.ZodString;
37
+ replaceAll: z.ZodOptional<z.ZodBoolean>;
38
+ }, z.core.$strip>;
39
+ /**
40
+ * Executes the edit operation atomically, capturing a content-addressed checkpoint
41
+ * snapshot before and after the replacement if checkpointing is enabled.
42
+ *
43
+ * @param parameters - Validated parameters containing filePath, oldString, newString, and replaceAll.
44
+ * @param context - The execution context with workingDirectory and checkpoint store.
45
+ * @returns A promise resolving to the structured edit result.
46
+ */
47
+ execute(parameters: z.infer<typeof editFileInputSchema>, context: ToolExecutionContext): Promise<EditFileOutput>;
48
+ }
49
+ //# sourceMappingURL=EditFileTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"EditFileTool.d.ts","sources":["../../src/tools/EditFileTool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAMtE;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;iBAkB9B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,YAAa,YAAW,SAAS,CAC5C,OAAO,mBAAmB,EAC1B,cAAc,CACf;IACC,gBAAuB,QAAQ,cAAc;IAE7C,SAAgB,IAAI,cAAyB;IAC7C,SAAgB,WAAW,SAAuB;IAClD,SAAgB,WAAW;;;;;sBAAuB;IAElD;;;;;;;OAOG;IACU,OAAO,CAClB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,EAC/C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA8GzB;CACF"}
@@ -0,0 +1,119 @@
1
+ /**
2
+ * @fileoverview Built-in tool for making targeted replacements within existing files.
3
+ * Validates match uniqueness and performs atomic file replacement with snapshot support.
4
+ * @packageDocumentation
5
+ */
6
+ import { existsSync } from "node:fs";
7
+ import { readFile } from "node:fs/promises";
8
+ import path from "node:path";
9
+ import { z } from "zod";
10
+ import { resolvePathWithinWorkspace } from "./internal/pathGuard.js";
11
+ import { atomicWriteFile } from "../storage/atomicFile.js";
12
+ import { withWorkspaceFileLock } from "../storage/workspaceLock.js";
13
+ import { editFileDescription } from "./prompts.js";
14
+ /**
15
+ * Input parameter schema for EditFileTool.
16
+ */
17
+ export const editFileInputSchema = z.object({
18
+ filePath: z
19
+ .string()
20
+ .describe("The relative or absolute file path of the file to modify."),
21
+ oldString: z
22
+ .string()
23
+ .describe("The exact string to find and replace. Must match the file content identically including whitespace."),
24
+ newString: z
25
+ .string()
26
+ .describe("The replacement string to insert in place of oldString."),
27
+ replaceAll: z
28
+ .boolean()
29
+ .optional()
30
+ .describe("If true, replace every occurrence of oldString. If false (default), oldString must appear exactly once."),
31
+ });
32
+ /**
33
+ * Built-in tool for targeted file editing.
34
+ */
35
+ export class EditFileTool {
36
+ static toolName = "editFile";
37
+ name = EditFileTool.toolName;
38
+ description = editFileDescription;
39
+ inputSchema = editFileInputSchema;
40
+ /**
41
+ * Executes the edit operation atomically, capturing a content-addressed checkpoint
42
+ * snapshot before and after the replacement if checkpointing is enabled.
43
+ *
44
+ * @param parameters - Validated parameters containing filePath, oldString, newString, and replaceAll.
45
+ * @param context - The execution context with workingDirectory and checkpoint store.
46
+ * @returns A promise resolving to the structured edit result.
47
+ */
48
+ async execute(parameters, context) {
49
+ if (parameters.oldString === parameters.newString) {
50
+ throw new Error("No changes to make: oldString and newString are identical.");
51
+ }
52
+ return await withWorkspaceFileLock(context.workingDirectory, parameters.filePath, async () => {
53
+ const fullPath = resolvePathWithinWorkspace(parameters.filePath, context.workingDirectory);
54
+ if (!existsSync(fullPath)) {
55
+ throw new Error(`File not found: ${parameters.filePath}`);
56
+ }
57
+ const rawContent = await readFile(fullPath, "utf-8");
58
+ if (!rawContent.includes(parameters.oldString)) {
59
+ throw new Error(`String to replace not found in file '${parameters.filePath}'. ` +
60
+ "Ensure whitespace, indentation, and newlines match the file exactly.");
61
+ }
62
+ const occurrences = rawContent.split(parameters.oldString).length - 1;
63
+ if (occurrences > 1 && !parameters.replaceAll) {
64
+ throw new Error(`Found ${occurrences} matches of the string to replace, but replaceAll is false. ` +
65
+ "To replace all occurrences, set replaceAll to true. " +
66
+ "To replace only one occurrence, provide more surrounding context to uniquely identify the instance.");
67
+ }
68
+ const relativeFilePath = path.relative(context.workingDirectory, fullPath);
69
+ let checkpointId;
70
+ // 1. Pre-mutation checkpoint capture
71
+ if (context.isCheckpointEnabled && context.checkpointStore) {
72
+ try {
73
+ const cpRecord = await context.checkpointStore.createCheckpoint(context.threadId, {
74
+ workingDirectory: context.workingDirectory,
75
+ turnIndex: context.turnIndex,
76
+ label: `editFile: ${parameters.filePath}`,
77
+ files: [relativeFilePath],
78
+ source: { toolName: EditFileTool.toolName },
79
+ });
80
+ checkpointId = cpRecord.id;
81
+ }
82
+ catch (error) {
83
+ throw new Error(`Failed to record pre-mutation checkpoint for '${parameters.filePath}': ${error instanceof Error ? error.message : String(error)}`);
84
+ }
85
+ }
86
+ // Function replacer avoids interpreting $&, $1, $$, etc. as special substitution patterns
87
+ const replacer = () => parameters.newString;
88
+ const updatedContent = parameters.replaceAll
89
+ ? rawContent.replaceAll(parameters.oldString, replacer)
90
+ : rawContent.replace(parameters.oldString, replacer);
91
+ const buffer = Buffer.from(updatedContent, "utf-8");
92
+ // 2. Perform file write atomically
93
+ await atomicWriteFile(fullPath, buffer);
94
+ // 3. Post-mutation checkpoint finalization
95
+ if (context.isCheckpointEnabled &&
96
+ context.checkpointStore &&
97
+ checkpointId) {
98
+ try {
99
+ const updatedRecord = await context.checkpointStore.updateCheckpoint(context.threadId, checkpointId, context.workingDirectory);
100
+ context.onCheckpointCreated?.({
101
+ checkpointId: updatedRecord.id,
102
+ sequence: updatedRecord.sequence,
103
+ label: updatedRecord.label,
104
+ filesTouched: [relativeFilePath],
105
+ });
106
+ }
107
+ catch (error) {
108
+ throw new Error(`Failed to record post-mutation checkpoint for '${parameters.filePath}': ${error instanceof Error ? error.message : String(error)}`);
109
+ }
110
+ }
111
+ return {
112
+ filePath: parameters.filePath,
113
+ replacementsApplied: parameters.replaceAll ? occurrences : 1,
114
+ bytesWritten: buffer.length,
115
+ };
116
+ });
117
+ }
118
+ }
119
+ //# sourceMappingURL=EditFileTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"EditFileTool.js","sources":["../../src/tools/EditFileTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,48 @@
1
+ /**
2
+ * @fileoverview Built-in tool for fast pattern-based file discovery in the workspace.
3
+ * Leverages native globbing, filters out noise directories (.git, node_modules),
4
+ * and enforces result size caps to protect LLM context limits.
5
+ * @packageDocumentation
6
+ */
7
+ import { z } from "zod";
8
+ import type { AgentTool } from "./AgentTool.js";
9
+ import type { ToolExecutionContext } from "./ToolExecutionContext.js";
10
+ /**
11
+ * Input parameter schema for GlobTool.
12
+ */
13
+ export declare const globInputSchema: z.ZodObject<{
14
+ pattern: z.ZodString;
15
+ directoryPath: z.ZodOptional<z.ZodString>;
16
+ }, z.core.$strip>;
17
+ /**
18
+ * Result structure produced by GlobTool.
19
+ */
20
+ export interface GlobOutput {
21
+ readonly pattern: string;
22
+ readonly directoryPath: string;
23
+ readonly matches: readonly string[];
24
+ readonly count: number;
25
+ readonly durationMs: number;
26
+ readonly isTruncated: boolean;
27
+ }
28
+ /**
29
+ * Built-in tool for finding workspace files using glob patterns.
30
+ */
31
+ export declare class GlobTool implements AgentTool<typeof globInputSchema, GlobOutput> {
32
+ static readonly toolName = "glob";
33
+ readonly name = "glob";
34
+ readonly description: string;
35
+ readonly inputSchema: z.ZodObject<{
36
+ pattern: z.ZodString;
37
+ directoryPath: z.ZodOptional<z.ZodString>;
38
+ }, z.core.$strip>;
39
+ /**
40
+ * Executes the glob search operation.
41
+ *
42
+ * @param parameters - Validated parameters containing pattern and optional directoryPath.
43
+ * @param context - The execution context with workingDirectory.
44
+ * @returns A promise resolving to the structured glob output.
45
+ */
46
+ execute(parameters: z.infer<typeof globInputSchema>, context: ToolExecutionContext): Promise<GlobOutput>;
47
+ }
48
+ //# sourceMappingURL=GlobTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GlobTool.d.ts","sources":["../../src/tools/GlobTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAsBtE;;GAEG;AACH,eAAO,MAAM,eAAe;;;iBAY1B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,QAAS,YAAW,SAAS,CAAC,OAAO,eAAe,EAAE,UAAU,CAAC;IAC5E,gBAAuB,QAAQ,UAAU;IAEzC,SAAgB,IAAI,UAAqB;IACzC,SAAgB,WAAW,SAAmB;IAC9C,SAAgB,WAAW;;;sBAAmB;IAE9C;;;;;;OAMG;IACU,OAAO,CAClB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,EAC3C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAwFrB;CACF"}
@@ -0,0 +1,117 @@
1
+ /**
2
+ * @fileoverview Built-in tool for fast pattern-based file discovery in the workspace.
3
+ * Leverages native globbing, filters out noise directories (.git, node_modules),
4
+ * and enforces result size caps to protect LLM context limits.
5
+ * @packageDocumentation
6
+ */
7
+ import { existsSync } from "node:fs";
8
+ import { glob, lstat } from "node:fs/promises";
9
+ import { relative } from "node:path";
10
+ import { z } from "zod";
11
+ import { resolvePathWithinWorkspace } from "./internal/pathGuard.js";
12
+ import { globDescription } from "./prompts.js";
13
+ /**
14
+ * Maximum number of file paths returned before truncating results.
15
+ */
16
+ const maxGlobResults = 250;
17
+ /**
18
+ * Directories excluded from search results by default.
19
+ */
20
+ const excludedDirectorySegments = [
21
+ "node_modules",
22
+ ".git",
23
+ ".turbo",
24
+ ".next",
25
+ "dist",
26
+ "build",
27
+ ".cache",
28
+ ];
29
+ /**
30
+ * Input parameter schema for GlobTool.
31
+ */
32
+ export const globInputSchema = z.object({
33
+ pattern: z
34
+ .string()
35
+ .describe("The glob pattern to match files against (e.g. '**/*.ts', 'packages/*/package.json')."),
36
+ directoryPath: z
37
+ .string()
38
+ .optional()
39
+ .describe("Optional directory path to search within. Defaults to the workspace root directory."),
40
+ });
41
+ /**
42
+ * Built-in tool for finding workspace files using glob patterns.
43
+ */
44
+ export class GlobTool {
45
+ static toolName = "glob";
46
+ name = GlobTool.toolName;
47
+ description = globDescription;
48
+ inputSchema = globInputSchema;
49
+ /**
50
+ * Executes the glob search operation.
51
+ *
52
+ * @param parameters - Validated parameters containing pattern and optional directoryPath.
53
+ * @param context - The execution context with workingDirectory.
54
+ * @returns A promise resolving to the structured glob output.
55
+ */
56
+ async execute(parameters, context) {
57
+ const startTime = Date.now();
58
+ const searchDir = resolvePathWithinWorkspace(parameters.directoryPath ?? ".", context.workingDirectory);
59
+ if (!existsSync(searchDir)) {
60
+ throw new Error(`Search directory not found: ${parameters.directoryPath ?? searchDir}`);
61
+ }
62
+ const rootStats = await lstat(searchDir);
63
+ if (!rootStats.isDirectory()) {
64
+ throw new Error(`Search path is not a directory: ${parameters.directoryPath ?? searchDir}`);
65
+ }
66
+ const matchedFiles = [];
67
+ let isTruncated = false;
68
+ // Use native Node 22+ / Bun fs.glob
69
+ const globIterator = glob(parameters.pattern, {
70
+ cwd: searchDir,
71
+ });
72
+ for await (const entry of globIterator) {
73
+ if (context.abortSignal?.aborted) {
74
+ throw new Error(`Glob search aborted: ${context.abortSignal.reason ?? "Aborted by signal"}`);
75
+ }
76
+ const normalizedEntry = entry.replace(/\\/g, "/");
77
+ // Check if any path segment matches an excluded directory
78
+ const isExcluded = excludedDirectorySegments.some((segment) => normalizedEntry.split("/").includes(segment));
79
+ if (isExcluded) {
80
+ continue;
81
+ }
82
+ let fullPath;
83
+ try {
84
+ fullPath = resolvePathWithinWorkspace(entry, searchDir);
85
+ const entryStats = await lstat(fullPath);
86
+ if (entryStats.isSymbolicLink()) {
87
+ continue;
88
+ }
89
+ }
90
+ catch (error) {
91
+ if (error instanceof Error &&
92
+ (error.message.includes("symbolic link") ||
93
+ error.message.includes("resolves outside"))) {
94
+ continue;
95
+ }
96
+ throw error;
97
+ }
98
+ if (matchedFiles.length >= maxGlobResults) {
99
+ isTruncated = true;
100
+ break;
101
+ }
102
+ // Convert to relative path from workspace root for clean representation
103
+ const relativePath = relative(context.workingDirectory, fullPath).replace(/\\/g, "/");
104
+ matchedFiles.push(relativePath || entry);
105
+ }
106
+ const durationMs = Date.now() - startTime;
107
+ return {
108
+ pattern: parameters.pattern,
109
+ directoryPath: parameters.directoryPath ?? ".",
110
+ matches: matchedFiles,
111
+ count: matchedFiles.length,
112
+ durationMs,
113
+ isTruncated,
114
+ };
115
+ }
116
+ }
117
+ //# sourceMappingURL=GlobTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GlobTool.js","sources":["../../src/tools/GlobTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,76 @@
1
+ /**
2
+ * @fileoverview Built-in tool for fast regex and substring content search in workspace files.
3
+ * Traverses targeted files, matches regex patterns line-by-line, ignores binary and vendor files,
4
+ * and caps output to avoid blowing LLM context windows.
5
+ * @packageDocumentation
6
+ */
7
+ import { z } from "zod";
8
+ import type { AgentTool } from "./AgentTool.js";
9
+ import type { ToolExecutionContext } from "./ToolExecutionContext.js";
10
+ /**
11
+ * Input parameter schema for GrepTool.
12
+ */
13
+ export declare const grepInputSchema: z.ZodObject<{
14
+ pattern: z.ZodString;
15
+ filePath: z.ZodOptional<z.ZodString>;
16
+ directoryPath: z.ZodOptional<z.ZodString>;
17
+ glob: z.ZodOptional<z.ZodString>;
18
+ caseInsensitive: z.ZodOptional<z.ZodBoolean>;
19
+ headLimit: z.ZodOptional<z.ZodNumber>;
20
+ }, z.core.$strip>;
21
+ /**
22
+ * Structure of a single grep line match.
23
+ */
24
+ export interface GrepMatch {
25
+ readonly filePath: string;
26
+ readonly lineNumber: number;
27
+ readonly line: string;
28
+ }
29
+ /**
30
+ * Result structure produced by GrepTool.
31
+ */
32
+ export interface GrepOutput {
33
+ readonly pattern: string;
34
+ readonly filePath?: string | undefined;
35
+ readonly directoryPath?: string | undefined;
36
+ readonly matches: readonly GrepMatch[];
37
+ readonly totalMatches: number;
38
+ readonly durationMs: number;
39
+ readonly isTruncated: boolean;
40
+ }
41
+ /**
42
+ * Built-in tool for regex searching across workspace files.
43
+ */
44
+ export declare class GrepTool implements AgentTool<typeof grepInputSchema, GrepOutput> {
45
+ static readonly toolName = "grep";
46
+ readonly name = "grep";
47
+ readonly description: string;
48
+ readonly inputSchema: z.ZodObject<{
49
+ pattern: z.ZodString;
50
+ filePath: z.ZodOptional<z.ZodString>;
51
+ directoryPath: z.ZodOptional<z.ZodString>;
52
+ glob: z.ZodOptional<z.ZodString>;
53
+ caseInsensitive: z.ZodOptional<z.ZodBoolean>;
54
+ headLimit: z.ZodOptional<z.ZodNumber>;
55
+ }, z.core.$strip>;
56
+ /**
57
+ * Executes the grep content search.
58
+ *
59
+ * @param parameters - Validated parameters containing pattern, filePath, directoryPath, glob, etc.
60
+ * @param context - The execution context with workingDirectory.
61
+ * @returns A promise resolving to the structured grep output.
62
+ */
63
+ execute(parameters: z.infer<typeof grepInputSchema>, context: ToolExecutionContext): Promise<GrepOutput>;
64
+ /**
65
+ * Helper that searches a single file for regex line matches.
66
+ *
67
+ * @param fullFilePath - Absolute path of file to read.
68
+ * @param workingDirectory - Workspace root for relative path derivation.
69
+ * @param regex - Compiled regex pattern to test against each line.
70
+ * @param matches - Output array to push matching items into.
71
+ * @param limit - Maximum match count.
72
+ * @returns True if limit is reached, false otherwise.
73
+ */
74
+ private searchFile;
75
+ }
76
+ //# sourceMappingURL=GrepTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GrepTool.d.ts","sources":["../../src/tools/GrepTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AA+CtE;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;iBAwCxB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,QAAS,YAAW,SAAS,CAAC,OAAO,eAAe,EAAE,UAAU,CAAC;IAC5E,gBAAuB,QAAQ,UAAU;IAEzC,SAAgB,IAAI,UAAqB;IACzC,SAAgB,WAAW,SAAmB;IAC9C,SAAgB,WAAW;;;;;;;sBAAmB;IAE9C;;;;;;OAMG;IACU,OAAO,CAClB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,EAC3C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAmJrB;IAED;;;;;;;;;OASG;YACW,UAAU;CAkFzB"}