@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,276 @@
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 { existsSync } from "node:fs";
8
+ import { glob, lstat, readFile } from "node:fs/promises";
9
+ import { relative } from "node:path";
10
+ import { z } from "zod";
11
+ import { resolvePathWithinWorkspace } from "./internal/pathGuard.js";
12
+ import { grepDescription } from "./prompts.js";
13
+ /**
14
+ * Default maximum number of matching lines returned.
15
+ */
16
+ const defaultGrepLimit = 250;
17
+ /**
18
+ * Common binary file extensions to skip during content searching.
19
+ */
20
+ const binaryExtensions = new Set([
21
+ ".zip",
22
+ ".tar",
23
+ ".gz",
24
+ ".7z",
25
+ ".rar",
26
+ ".png",
27
+ ".jpg",
28
+ ".jpeg",
29
+ ".gif",
30
+ ".ico",
31
+ ".pdf",
32
+ ".exe",
33
+ ".dll",
34
+ ".so",
35
+ ".dylib",
36
+ ".bin",
37
+ ".wasm",
38
+ ".pyc",
39
+ ".lock",
40
+ ]);
41
+ /**
42
+ * Directory segments excluded from searching.
43
+ */
44
+ const excludedDirectorySegments = [
45
+ "node_modules",
46
+ ".git",
47
+ ".turbo",
48
+ ".next",
49
+ "dist",
50
+ "build",
51
+ ".cache",
52
+ ];
53
+ /**
54
+ * Input parameter schema for GrepTool.
55
+ */
56
+ export const grepInputSchema = z
57
+ .object({
58
+ pattern: z
59
+ .string()
60
+ .describe("The regular expression pattern to search for."),
61
+ filePath: z
62
+ .string()
63
+ .optional()
64
+ .describe("Optional single file path to search within. Mutually exclusive with directoryPath."),
65
+ directoryPath: z
66
+ .string()
67
+ .optional()
68
+ .describe("Optional directory path to search within. Mutually exclusive with filePath. Defaults to workspace root directory if neither is specified."),
69
+ glob: z
70
+ .string()
71
+ .optional()
72
+ .describe("Optional glob pattern to filter search files within a directory (e.g. '*.ts', '*.json')."),
73
+ caseInsensitive: z
74
+ .boolean()
75
+ .optional()
76
+ .describe("Whether to perform case-insensitive matching. Defaults to false."),
77
+ headLimit: z
78
+ .number()
79
+ .int()
80
+ .positive()
81
+ .optional()
82
+ .describe("Maximum number of match entries to return. Defaults to 250."),
83
+ })
84
+ .refine((data) => !(data.filePath && data.directoryPath), {
85
+ message: "Cannot specify both filePath and directoryPath. Choose one target scope.",
86
+ path: ["filePath"],
87
+ });
88
+ /**
89
+ * Built-in tool for regex searching across workspace files.
90
+ */
91
+ export class GrepTool {
92
+ static toolName = "grep";
93
+ name = GrepTool.toolName;
94
+ description = grepDescription;
95
+ inputSchema = grepInputSchema;
96
+ /**
97
+ * Executes the grep content search.
98
+ *
99
+ * @param parameters - Validated parameters containing pattern, filePath, directoryPath, glob, etc.
100
+ * @param context - The execution context with workingDirectory.
101
+ * @returns A promise resolving to the structured grep output.
102
+ */
103
+ async execute(parameters, context) {
104
+ const startTime = Date.now();
105
+ const flags = parameters.caseInsensitive ? "i" : "";
106
+ let regex;
107
+ try {
108
+ regex = new RegExp(parameters.pattern, flags);
109
+ }
110
+ catch (error) {
111
+ throw new Error(`Invalid regular expression pattern "${parameters.pattern}": ${error instanceof Error ? error.message : String(error)}`);
112
+ }
113
+ const matches = [];
114
+ let isTruncated = false;
115
+ const limit = parameters.headLimit ?? defaultGrepLimit;
116
+ if (parameters.filePath) {
117
+ const targetPath = resolvePathWithinWorkspace(parameters.filePath, context.workingDirectory);
118
+ if (!existsSync(targetPath)) {
119
+ throw new Error(`Target file not found: ${parameters.filePath}`);
120
+ }
121
+ const targetStats = await lstat(targetPath);
122
+ if (targetStats.isSymbolicLink()) {
123
+ throw new Error(`Target path is a symbolic link: ${parameters.filePath}`);
124
+ }
125
+ if (targetStats.isDirectory()) {
126
+ throw new Error(`Target filePath is a directory: ${parameters.filePath}. Use directoryPath instead.`);
127
+ }
128
+ isTruncated = await this.searchFile(targetPath, context.workingDirectory, regex, matches, limit);
129
+ }
130
+ else {
131
+ const dirScope = parameters.directoryPath ?? ".";
132
+ const targetPath = resolvePathWithinWorkspace(dirScope, context.workingDirectory);
133
+ if (!existsSync(targetPath)) {
134
+ throw new Error(`Target directory not found: ${dirScope}`);
135
+ }
136
+ const targetStats = await lstat(targetPath);
137
+ if (targetStats.isSymbolicLink()) {
138
+ throw new Error(`Target path is a symbolic link: ${dirScope}`);
139
+ }
140
+ if (targetStats.isFile()) {
141
+ throw new Error(`Target directoryPath is a file: ${dirScope}. Use filePath instead.`);
142
+ }
143
+ const filePattern = parameters.glob ?? "**/*";
144
+ const globIterator = glob(filePattern, { cwd: targetPath });
145
+ for await (const entry of globIterator) {
146
+ if (context.abortSignal?.aborted) {
147
+ throw new Error(`Grep search aborted: ${context.abortSignal.reason ?? "Aborted by signal"}`);
148
+ }
149
+ const normalized = entry.replace(/\\/g, "/");
150
+ const isExcluded = excludedDirectorySegments.some((segment) => normalized.split("/").includes(segment));
151
+ if (isExcluded) {
152
+ continue;
153
+ }
154
+ let fullFilePath;
155
+ try {
156
+ fullFilePath = resolvePathWithinWorkspace(entry, targetPath);
157
+ }
158
+ catch (error) {
159
+ if (error instanceof Error &&
160
+ (error.message.includes("symbolic link") ||
161
+ error.message.includes("resolves outside"))) {
162
+ // Deliberately skip symlinks and outside paths during file enumeration
163
+ continue;
164
+ }
165
+ throw error;
166
+ }
167
+ let fileStat;
168
+ try {
169
+ fileStat = await lstat(fullFilePath);
170
+ }
171
+ catch (error) {
172
+ if (typeof error === "object" &&
173
+ error !== null &&
174
+ "code" in error &&
175
+ error.code === "ENOENT") {
176
+ // File vanished between glob enumeration and lstat
177
+ continue;
178
+ }
179
+ throw error;
180
+ }
181
+ if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
182
+ continue;
183
+ }
184
+ const reachedLimit = await this.searchFile(fullFilePath, context.workingDirectory, regex, matches, limit);
185
+ if (reachedLimit) {
186
+ isTruncated = true;
187
+ break;
188
+ }
189
+ }
190
+ }
191
+ const durationMs = Date.now() - startTime;
192
+ return {
193
+ pattern: parameters.pattern,
194
+ ...(parameters.filePath
195
+ ? { filePath: parameters.filePath }
196
+ : { directoryPath: parameters.directoryPath ?? "." }),
197
+ matches,
198
+ totalMatches: matches.length,
199
+ durationMs,
200
+ isTruncated,
201
+ };
202
+ }
203
+ /**
204
+ * Helper that searches a single file for regex line matches.
205
+ *
206
+ * @param fullFilePath - Absolute path of file to read.
207
+ * @param workingDirectory - Workspace root for relative path derivation.
208
+ * @param regex - Compiled regex pattern to test against each line.
209
+ * @param matches - Output array to push matching items into.
210
+ * @param limit - Maximum match count.
211
+ * @returns True if limit is reached, false otherwise.
212
+ */
213
+ async searchFile(fullFilePath, workingDirectory, regex, matches, limit) {
214
+ const lower = fullFilePath.toLowerCase();
215
+ for (const ext of binaryExtensions) {
216
+ if (lower.endsWith(ext)) {
217
+ return false;
218
+ }
219
+ }
220
+ let fileStat;
221
+ try {
222
+ fileStat = await lstat(fullFilePath);
223
+ }
224
+ catch (error) {
225
+ if (typeof error === "object" &&
226
+ error !== null &&
227
+ "code" in error &&
228
+ error.code === "ENOENT") {
229
+ return false;
230
+ }
231
+ throw error;
232
+ }
233
+ if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
234
+ return false;
235
+ }
236
+ // Skip excessively large files (>10MB) to protect memory
237
+ if (fileStat.size > 10 * 1024 * 1024) {
238
+ return false;
239
+ }
240
+ let buffer;
241
+ try {
242
+ buffer = await readFile(fullFilePath);
243
+ }
244
+ catch (error) {
245
+ if (typeof error === "object" &&
246
+ error !== null &&
247
+ "code" in error &&
248
+ error.code === "ENOENT") {
249
+ return false;
250
+ }
251
+ throw error;
252
+ }
253
+ // Skip binary files containing null bytes
254
+ if (buffer.includes(0)) {
255
+ return false;
256
+ }
257
+ const relPath = relative(workingDirectory, fullFilePath).replace(/\\/g, "/");
258
+ const content = buffer.toString("utf-8");
259
+ const lines = content.split("\n");
260
+ for (let i = 0; i < lines.length; i++) {
261
+ const line = lines[i];
262
+ if (regex.test(line)) {
263
+ matches.push({
264
+ filePath: relPath || fullFilePath,
265
+ lineNumber: i + 1,
266
+ line: line.trimEnd(),
267
+ });
268
+ if (matches.length >= limit) {
269
+ return true;
270
+ }
271
+ }
272
+ }
273
+ return false;
274
+ }
275
+ }
276
+ //# sourceMappingURL=GrepTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"GrepTool.js","sources":["../../src/tools/GrepTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,51 @@
1
+ /**
2
+ * @fileoverview Built-in tool for safely reading file contents.
3
+ * Incorporates binary rejection, device file protection, line-based pagination,
4
+ * and output truncation 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 ReadFileTool.
12
+ */
13
+ export declare const readFileInputSchema: z.ZodObject<{
14
+ filePath: z.ZodString;
15
+ offset: z.ZodOptional<z.ZodNumber>;
16
+ limit: z.ZodOptional<z.ZodNumber>;
17
+ }, z.core.$strip>;
18
+ /**
19
+ * Result structure produced by ReadFileTool.
20
+ */
21
+ export interface ReadFileOutput {
22
+ readonly filePath: string;
23
+ readonly totalLines: number;
24
+ readonly startLine: number;
25
+ readonly linesReturned: number;
26
+ readonly content: string;
27
+ readonly isTruncated: boolean;
28
+ readonly hint?: string | undefined;
29
+ }
30
+ /**
31
+ * Built-in tool for inspecting file contents.
32
+ */
33
+ export declare class ReadFileTool implements AgentTool<typeof readFileInputSchema, ReadFileOutput> {
34
+ static readonly toolName = "readFile";
35
+ readonly name = "readFile";
36
+ readonly description: string;
37
+ readonly inputSchema: z.ZodObject<{
38
+ filePath: z.ZodString;
39
+ offset: z.ZodOptional<z.ZodNumber>;
40
+ limit: z.ZodOptional<z.ZodNumber>;
41
+ }, z.core.$strip>;
42
+ /**
43
+ * Executes the file reading operation with safety checks and pagination.
44
+ *
45
+ * @param parameters - Validated parameters containing filePath, offset, and limit.
46
+ * @param context - The execution context with workingDirectory and fileReadState.
47
+ * @returns A promise resolving to the structured file read output.
48
+ */
49
+ execute(parameters: z.infer<typeof readFileInputSchema>, context: ToolExecutionContext): Promise<ReadFileOutput>;
50
+ }
51
+ //# sourceMappingURL=ReadFileTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ReadFileTool.d.ts","sources":["../../src/tools/ReadFileTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,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;AAgDtE;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;iBAgB9B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;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;;;;;;OAMG;IACU,OAAO,CAClB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,EAC/C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA6FzB;CACF"}
@@ -0,0 +1,153 @@
1
+ /**
2
+ * @fileoverview Built-in tool for safely reading file contents.
3
+ * Incorporates binary rejection, device file protection, line-based pagination,
4
+ * and output truncation limits.
5
+ * @packageDocumentation
6
+ */
7
+ import { existsSync } from "node:fs";
8
+ import { lstat, readFile } from "node:fs/promises";
9
+ import { z } from "zod";
10
+ import { resolvePathWithinWorkspace } from "./internal/pathGuard.js";
11
+ import { readFileDescription } from "./prompts.js";
12
+ /**
13
+ * Maximum character count returned before truncating file output.
14
+ */
15
+ const maxReadOutputCharacters = 30000;
16
+ /**
17
+ * Maximum lines returned in a single unpaginated read.
18
+ */
19
+ const maxReadOutputLines = 2000;
20
+ /**
21
+ * Maximum file size cap before loading buffer into memory (20MB).
22
+ */
23
+ const maxFileSizeBytes = 20 * 1024 * 1024;
24
+ /**
25
+ * Common binary file extensions rejected without disk I/O.
26
+ */
27
+ const binaryExtensions = new Set([
28
+ ".zip",
29
+ ".tar",
30
+ ".gz",
31
+ ".7z",
32
+ ".rar",
33
+ ".png",
34
+ ".jpg",
35
+ ".jpeg",
36
+ ".gif",
37
+ ".ico",
38
+ ".pdf",
39
+ ".exe",
40
+ ".dll",
41
+ ".so",
42
+ ".dylib",
43
+ ".bin",
44
+ ".wasm",
45
+ ".pyc",
46
+ ]);
47
+ /**
48
+ * Device paths that would block or hang indefinitely.
49
+ */
50
+ const blockingDevicePrefixes = ["/dev/zero", "/dev/urandom", "/dev/random"];
51
+ /**
52
+ * Input parameter schema for ReadFileTool.
53
+ */
54
+ export const readFileInputSchema = z.object({
55
+ filePath: z
56
+ .string()
57
+ .describe("The relative or absolute file path to read from."),
58
+ offset: z
59
+ .number()
60
+ .int()
61
+ .min(1)
62
+ .optional()
63
+ .describe("1-based line number to begin reading from."),
64
+ limit: z
65
+ .number()
66
+ .int()
67
+ .min(1)
68
+ .optional()
69
+ .describe("Maximum number of lines to return."),
70
+ });
71
+ /**
72
+ * Built-in tool for inspecting file contents.
73
+ */
74
+ export class ReadFileTool {
75
+ static toolName = "readFile";
76
+ name = ReadFileTool.toolName;
77
+ description = readFileDescription;
78
+ inputSchema = readFileInputSchema;
79
+ /**
80
+ * Executes the file reading operation with safety checks and pagination.
81
+ *
82
+ * @param parameters - Validated parameters containing filePath, offset, and limit.
83
+ * @param context - The execution context with workingDirectory and fileReadState.
84
+ * @returns A promise resolving to the structured file read output.
85
+ */
86
+ async execute(parameters, context) {
87
+ const fullPath = resolvePathWithinWorkspace(parameters.filePath, context.workingDirectory);
88
+ for (const prefix of blockingDevicePrefixes) {
89
+ if (fullPath.startsWith(prefix)) {
90
+ throw new Error(`Cannot read device file '${parameters.filePath}': device causes infinite or blocking stream.`);
91
+ }
92
+ }
93
+ const lowerPath = fullPath.toLowerCase();
94
+ for (const ext of binaryExtensions) {
95
+ if (lowerPath.endsWith(ext)) {
96
+ throw new Error(`Cannot read binary file '${parameters.filePath}' (${ext}). Use specialized binary or extraction tools.`);
97
+ }
98
+ }
99
+ if (!existsSync(fullPath)) {
100
+ throw new Error(`File not found: ${parameters.filePath}`);
101
+ }
102
+ const fileStats = await lstat(fullPath);
103
+ if (fileStats.isSymbolicLink() || !fileStats.isFile()) {
104
+ throw new Error(`Path '${parameters.filePath}' is not a regular file. Directory, symlink, device, socket, or non-regular paths cannot be read as text.`);
105
+ }
106
+ if (fileStats.size > maxFileSizeBytes) {
107
+ throw new Error(`File '${parameters.filePath}' is too large to read into memory (${(fileStats.size / (1024 * 1024)).toFixed(1)}MB exceeds limit of 20MB).`);
108
+ }
109
+ const buffer = await readFile(fullPath);
110
+ // Null byte detection for binary files
111
+ if (buffer.includes(0)) {
112
+ throw new Error(`Cannot read binary file '${parameters.filePath}': file contains null bytes.`);
113
+ }
114
+ const rawContent = buffer.toString("utf-8");
115
+ const rawLines = rawContent
116
+ .split("\n")
117
+ .map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
118
+ if (rawContent.endsWith("\n") && rawLines.length > 0) {
119
+ rawLines.pop();
120
+ }
121
+ const startLineIndex = parameters.offset ? parameters.offset - 1 : 0;
122
+ const endLineIndex = parameters.limit
123
+ ? startLineIndex + parameters.limit
124
+ : rawLines.length;
125
+ let selectedLines = rawLines.slice(startLineIndex, endLineIndex);
126
+ let isTruncated = false;
127
+ if (selectedLines.length > maxReadOutputLines) {
128
+ selectedLines = selectedLines.slice(0, maxReadOutputLines);
129
+ isTruncated = true;
130
+ }
131
+ let formattedContent = selectedLines
132
+ .map((line, index) => `${startLineIndex + index + 1}: ${line}`)
133
+ .join("\n");
134
+ if (formattedContent.length > maxReadOutputCharacters) {
135
+ formattedContent =
136
+ formattedContent.slice(0, maxReadOutputCharacters) +
137
+ "\n... [output truncated at 30,000 characters]";
138
+ isTruncated = true;
139
+ }
140
+ return {
141
+ filePath: parameters.filePath,
142
+ totalLines: rawLines.length,
143
+ startLine: startLineIndex + 1,
144
+ linesReturned: selectedLines.length,
145
+ content: formattedContent,
146
+ isTruncated,
147
+ hint: isTruncated
148
+ ? "Use offset and limit parameters to inspect specific sections."
149
+ : undefined,
150
+ };
151
+ }
152
+ }
153
+ //# sourceMappingURL=ReadFileTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ReadFileTool.js","sources":["../../src/tools/ReadFileTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,102 @@
1
+ /**
2
+ * @fileoverview Built-in tool for managing background shell tasks spawned by BashTool.
3
+ * Restricts model actions to inspecting and managing active/recent tasks:
4
+ * listing tasks, line-paged log inspection, interactive stdin delivery,
5
+ * process termination, and deleting completed task logs.
6
+ * @packageDocumentation
7
+ */
8
+ import { z } from "zod";
9
+ import type { AgentTool } from "./AgentTool.js";
10
+ import type { ToolExecutionContext } from "./ToolExecutionContext.js";
11
+ import type { TaskReadResult, TaskSendInputResult, TaskStopResult, TaskSummary } from "../tasks/index.js";
12
+ /**
13
+ * Zod schema for TaskManagerTool inputs using a discriminated union on the "action" field.
14
+ * Restricts model actions to inspecting and managing existing tasks (list, read, sendInput, stop, delete).
15
+ * Task creation is performed exclusively by the model via BashTool.
16
+ */
17
+ export declare const taskManagerInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
18
+ action: z.ZodLiteral<"list">;
19
+ }, z.core.$strip>, z.ZodObject<{
20
+ action: z.ZodLiteral<"read">;
21
+ taskId: z.ZodString;
22
+ offset: z.ZodNumber;
23
+ limit: z.ZodNumber;
24
+ }, z.core.$strip>, z.ZodObject<{
25
+ action: z.ZodLiteral<"sendInput">;
26
+ taskId: z.ZodString;
27
+ input: z.ZodString;
28
+ newline: z.ZodOptional<z.ZodBoolean>;
29
+ }, z.core.$strip>, z.ZodObject<{
30
+ action: z.ZodLiteral<"stop">;
31
+ taskId: z.ZodString;
32
+ signal: z.ZodOptional<z.ZodEnum<{
33
+ SIGKILL: "SIGKILL";
34
+ SIGTERM: "SIGTERM";
35
+ }>>;
36
+ }, z.core.$strip>, z.ZodObject<{
37
+ action: z.ZodLiteral<"delete">;
38
+ taskId: z.ZodString;
39
+ }, z.core.$strip>], "action">;
40
+ /**
41
+ * TypeScript type inferred from taskManagerInputSchema.
42
+ */
43
+ export type TaskManagerInput = z.infer<typeof taskManagerInputSchema>;
44
+ /**
45
+ * Result structure produced by TaskManagerTool operations.
46
+ */
47
+ export type TaskManagerOutput = {
48
+ readonly action: "list";
49
+ readonly tasks: readonly TaskSummary[];
50
+ readonly count: number;
51
+ } | ({
52
+ readonly action: "read";
53
+ } & TaskReadResult) | ({
54
+ readonly action: "sendInput";
55
+ } & TaskSendInputResult) | ({
56
+ readonly action: "stop";
57
+ } & TaskStopResult) | {
58
+ readonly action: "delete";
59
+ readonly taskId: string;
60
+ readonly deleted: boolean;
61
+ };
62
+ /**
63
+ * Built-in tool for managing background shell tasks.
64
+ */
65
+ export declare class TaskManagerTool implements AgentTool<typeof taskManagerInputSchema, TaskManagerOutput> {
66
+ static readonly toolName = "taskManager";
67
+ readonly name = "taskManager";
68
+ readonly description: string;
69
+ readonly inputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
70
+ action: z.ZodLiteral<"list">;
71
+ }, z.core.$strip>, z.ZodObject<{
72
+ action: z.ZodLiteral<"read">;
73
+ taskId: z.ZodString;
74
+ offset: z.ZodNumber;
75
+ limit: z.ZodNumber;
76
+ }, z.core.$strip>, z.ZodObject<{
77
+ action: z.ZodLiteral<"sendInput">;
78
+ taskId: z.ZodString;
79
+ input: z.ZodString;
80
+ newline: z.ZodOptional<z.ZodBoolean>;
81
+ }, z.core.$strip>, z.ZodObject<{
82
+ action: z.ZodLiteral<"stop">;
83
+ taskId: z.ZodString;
84
+ signal: z.ZodOptional<z.ZodEnum<{
85
+ SIGKILL: "SIGKILL";
86
+ SIGTERM: "SIGTERM";
87
+ }>>;
88
+ }, z.core.$strip>, z.ZodObject<{
89
+ action: z.ZodLiteral<"delete">;
90
+ taskId: z.ZodString;
91
+ }, z.core.$strip>], "action">;
92
+ /**
93
+ * Executes task management actions against background processes.
94
+ *
95
+ * @param parameters - Discriminated union of task management parameters (list, read, sendInput, stop, delete).
96
+ * @param context - The execution context containing taskManager.
97
+ * @returns The action-specific execution output.
98
+ * @throws Error if taskManager is not configured in the execution context.
99
+ */
100
+ execute(parameters: TaskManagerInput, context: ToolExecutionContext): Promise<TaskManagerOutput>;
101
+ }
102
+ //# sourceMappingURL=TaskManagerTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TaskManagerTool.d.ts","sources":["../../src/tools/TaskManagerTool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,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;AAEtE,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;6BAsDjC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD,CAAC;IACC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,cAAc,CAAC,GACnB,CAAC;IACC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,GAAG,mBAAmB,CAAC,GACxB,CAAC;IACC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,cAAc,CAAC,GACnB;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEN;;GAEG;AACH,qBAAa,eAAgB,YAAW,SAAS,CAC/C,OAAO,sBAAsB,EAC7B,iBAAiB,CAClB;IACC,gBAAuB,QAAQ,iBAAiB;IAEhD,SAAgB,IAAI,iBAA4B;IAChD,SAAgB,WAAW,SAA0B;IACrD,SAAgB,WAAW;;;;;;;;;;;;;;;;;;;;;;kCAA0B;IAErD;;;;;;;OAOG;IACU,OAAO,CAClB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CA6D5B;CACF"}