1use std::fs;
2use std::str::FromStr;
3
4use futures_util::stream;
5use globset::{Glob, GlobMatcher};
6use ignore::{DirEntry, WalkBuilder};
7use regex::{Regex, RegexBuilder};
8use serde_json::{Value, json};
9use tea_control::CancellationScope;
10use tea_protocol::ToolIdempotency;
11use tea_tools::{
12 BoxToolExecutionStream, ToolConcurrency, ToolEffect, ToolExecutionEvent, ToolExecutionFailure,
13 ToolExecutionSemantics, ToolExecutor, ToolName, ToolRetrySafety, ToolSpec, ToolSpecError,
14 ToolTimeout, ToolVersion, ValidatedToolInvocation,
15};
16
17use crate::file::read_utf8;
18use crate::output::{failure, success};
19use crate::read::string_argument;
20use crate::{FileToolError, FileToolErrorCode, WorkspaceRoot};
21
22pub const DEFAULT_SEARCH_RESULT_LIMIT: usize = 100;
24pub const MAX_SEARCH_RESULT_LIMIT: usize = 1_000;
26pub const MAX_SEARCH_DEPTH: usize = 8;
28
29const MAX_SEARCH_PATTERN_BYTES: usize = 1_024;
30const MAX_SEARCH_FILE_BYTES: usize = 1024 * 1024;
31const MAX_SEARCH_SCANNED_BYTES: usize = 16 * 1024 * 1024;
32const MAX_SEARCH_ENTRIES: usize = 20_000;
33const MAX_SEARCH_OUTPUT_BYTES: usize = 128 * 1024;
34const MAX_VISIBLE_OUTPUT_BYTES: usize = 32 * 1024;
35const MAX_MATCH_LINE_BYTES: usize = 1_024;
36
37#[derive(Debug, Clone)]
39pub struct GrepTool {
40 workspace: WorkspaceRoot,
41}
42
43impl GrepTool {
44 #[must_use]
46 pub const fn new(workspace: WorkspaceRoot) -> Self {
47 Self { workspace }
48 }
49
50 pub fn spec() -> Result<ToolSpec, ToolSpecError> {
56 search_spec(
57 "grep",
58 "Search bounded UTF-8 workspace files with a regular expression.",
59 json!({
60 "type":"object",
61 "properties":{
62 "pattern":{"type":"string","minLength":1,"maxLength":MAX_SEARCH_PATTERN_BYTES},
63 "path":{"type":"string","minLength":1,"maxLength":4096},
64 "glob":{"type":"string","minLength":1,"maxLength":MAX_SEARCH_PATTERN_BYTES},
65 "caseSensitive":{"type":"boolean"},
66 "limit":{"type":"integer","minimum":1,"maximum":MAX_SEARCH_RESULT_LIMIT}
67 },
68 "required":["pattern"],
69 "additionalProperties":false
70 }),
71 json!({
72 "type":"object",
73 "properties":{
74 "matches":{"type":"array","items":{"type":"object"}},
75 "scannedFiles":{"type":"integer","minimum":0},
76 "truncated":{"type":"boolean"}
77 },
78 "required":["matches","scannedFiles","truncated"],
79 "additionalProperties":false
80 }),
81 "Use grep for regex content search; path defaults to the workspace root and glob filters files.",
82 )
83 }
84
85 fn run(
86 &self,
87 invocation: &ValidatedToolInvocation,
88 cancellation: &CancellationScope,
89 ) -> Result<ToolExecutionEvent, SearchRunError> {
90 let pattern = string_argument(invocation, "pattern")?;
91 let case_sensitive = bool_argument(invocation, "caseSensitive")?.unwrap_or(true);
92 let regex = RegexBuilder::new(pattern)
93 .case_insensitive(!case_sensitive)
94 .size_limit(1024 * 1024)
95 .build()
96 .map_err(|_| FileToolError::new(FileToolErrorCode::InvalidArguments))?;
97 let glob = optional_glob(invocation, "glob")?;
98 let limit = result_limit(invocation)?;
99 let root = self.search_root(invocation)?;
100 let mut matches = Vec::new();
101 let mut visible = String::new();
102 let mut scanned_files = 0_usize;
103 let mut scanned_bytes = 0_usize;
104 let mut output_bytes = 0_usize;
105 let mut truncated = false;
106
107 for entry in walker(root.host_path(), None) {
108 check_cancelled(cancellation)?;
109 let entry =
110 entry.map_err(|_| FileToolError::new(FileToolErrorCode::FilesystemFailure))?;
111 if !is_regular_file(&entry) {
112 continue;
113 }
114 let Some(relative) = relative_path(&self.workspace, entry.path()) else {
115 continue;
116 };
117 if glob
118 .as_ref()
119 .is_some_and(|glob| !glob_matches(glob, &relative))
120 {
121 continue;
122 }
123 let metadata = fs::metadata(entry.path())
124 .map_err(|_| FileToolError::new(FileToolErrorCode::FilesystemFailure))?;
125 let file_bytes = usize::try_from(metadata.len()).unwrap_or(usize::MAX);
126 if file_bytes > MAX_SEARCH_FILE_BYTES {
127 continue;
128 }
129 if scanned_files >= MAX_SEARCH_ENTRIES
130 || scanned_bytes.saturating_add(file_bytes) > MAX_SEARCH_SCANNED_BYTES
131 {
132 truncated = true;
133 break;
134 }
135 scanned_files += 1;
136 scanned_bytes += file_bytes;
137 let Ok(target) = self.workspace.resolve_existing(&relative) else {
138 continue;
139 };
140 let source = match read_utf8(&self.workspace, &target, MAX_SEARCH_FILE_BYTES) {
141 Ok(source) => source,
142 Err(error)
143 if matches!(
144 error.code(),
145 FileToolErrorCode::BinaryFile
146 | FileToolErrorCode::InvalidUtf8
147 | FileToolErrorCode::TooLarge
148 ) =>
149 {
150 continue;
151 }
152 Err(error) => return Err(error.into()),
153 };
154 if collect_file_matches(
155 ®ex,
156 &relative,
157 &source,
158 limit,
159 &mut matches,
160 &mut visible,
161 &mut output_bytes,
162 ) {
163 truncated = true;
164 break;
165 }
166 }
167 if visible.is_empty() {
168 visible.push_str("No matches found.");
169 }
170 Ok(success(
171 visible,
172 json!({
173 "matches": matches,
174 "scannedFiles": scanned_files,
175 "truncated": truncated
176 }),
177 ))
178 }
179
180 fn search_root(
181 &self,
182 invocation: &ValidatedToolInvocation,
183 ) -> Result<crate::ResolvedExistingPath, FileToolError> {
184 let path = optional_string_argument(invocation, "path")?.unwrap_or(".");
185 self.workspace.resolve_existing(path).map_err(Into::into)
186 }
187}
188
189impl ToolExecutor for GrepTool {
190 fn execute(
191 &self,
192 invocation: ValidatedToolInvocation,
193 cancellation: CancellationScope,
194 ) -> BoxToolExecutionStream {
195 let executor = self.clone();
196 Box::pin(stream::once(async move {
197 terminal(executor.run(&invocation, &cancellation))
198 }))
199 }
200}
201
202#[derive(Debug, Clone)]
204pub struct FindTool {
205 workspace: WorkspaceRoot,
206}
207
208impl FindTool {
209 #[must_use]
211 pub const fn new(workspace: WorkspaceRoot) -> Self {
212 Self { workspace }
213 }
214
215 pub fn spec() -> Result<ToolSpec, ToolSpecError> {
221 search_spec(
222 "find",
223 "Find workspace paths with a bounded glob pattern.",
224 json!({
225 "type":"object",
226 "properties":{
227 "pattern":{"type":"string","minLength":1,"maxLength":MAX_SEARCH_PATTERN_BYTES},
228 "path":{"type":"string","minLength":1,"maxLength":4096},
229 "limit":{"type":"integer","minimum":1,"maximum":MAX_SEARCH_RESULT_LIMIT}
230 },
231 "required":["pattern"],
232 "additionalProperties":false
233 }),
234 list_output_schema("paths"),
235 "Use find for glob path search; path defaults to the workspace root.",
236 )
237 }
238
239 fn run(
240 &self,
241 invocation: &ValidatedToolInvocation,
242 cancellation: &CancellationScope,
243 ) -> Result<ToolExecutionEvent, SearchRunError> {
244 let pattern = string_argument(invocation, "pattern")?;
245 let matcher = compile_glob(pattern)?;
246 let limit = result_limit(invocation)?;
247 let path = optional_string_argument(invocation, "path")?.unwrap_or(".");
248 let root = self
249 .workspace
250 .resolve_existing(path)
251 .map_err(FileToolError::from)?;
252 let mut paths = Vec::new();
253 let mut output_bytes = 0_usize;
254 let mut truncated = false;
255 for (visited, entry) in walker(root.host_path(), None).enumerate() {
256 check_cancelled(cancellation)?;
257 if visited >= MAX_SEARCH_ENTRIES {
258 truncated = true;
259 break;
260 }
261 let entry =
262 entry.map_err(|_| FileToolError::new(FileToolErrorCode::FilesystemFailure))?;
263 if (entry.depth() == 0 && is_directory(&entry)) || is_symlink(&entry) {
264 continue;
265 }
266 let Some(relative) = relative_path(&self.workspace, entry.path()) else {
267 continue;
268 };
269 if !glob_matches(&matcher, &relative) {
270 continue;
271 }
272 if paths.len() >= limit
273 || output_bytes.saturating_add(relative.len()) > MAX_SEARCH_OUTPUT_BYTES
274 {
275 truncated = true;
276 break;
277 }
278 output_bytes += relative.len();
279 paths.push(relative);
280 }
281 let visible = visible_paths(&paths, truncated);
282 Ok(success(
283 visible,
284 json!({"paths":paths,"truncated":truncated}),
285 ))
286 }
287}
288
289impl ToolExecutor for FindTool {
290 fn execute(
291 &self,
292 invocation: ValidatedToolInvocation,
293 cancellation: CancellationScope,
294 ) -> BoxToolExecutionStream {
295 let executor = self.clone();
296 Box::pin(stream::once(async move {
297 terminal(executor.run(&invocation, &cancellation))
298 }))
299 }
300}
301
302#[derive(Debug, Clone)]
304pub struct LsTool {
305 workspace: WorkspaceRoot,
306}
307
308impl LsTool {
309 #[must_use]
311 pub const fn new(workspace: WorkspaceRoot) -> Self {
312 Self { workspace }
313 }
314
315 pub fn spec() -> Result<ToolSpec, ToolSpecError> {
321 search_spec(
322 "ls",
323 "List bounded workspace directory entries.",
324 json!({
325 "type":"object",
326 "properties":{
327 "path":{"type":"string","minLength":1,"maxLength":4096},
328 "depth":{"type":"integer","minimum":1,"maximum":MAX_SEARCH_DEPTH},
329 "limit":{"type":"integer","minimum":1,"maximum":MAX_SEARCH_RESULT_LIMIT}
330 },
331 "additionalProperties":false
332 }),
333 json!({
334 "type":"object",
335 "properties":{
336 "entries":{"type":"array","items":{"type":"object"}},
337 "truncated":{"type":"boolean"}
338 },
339 "required":["entries","truncated"],
340 "additionalProperties":false
341 }),
342 "Use ls for directory structure; path defaults to the workspace root and depth defaults to one.",
343 )
344 }
345
346 fn run(
347 &self,
348 invocation: &ValidatedToolInvocation,
349 cancellation: &CancellationScope,
350 ) -> Result<ToolExecutionEvent, SearchRunError> {
351 let path = optional_string_argument(invocation, "path")?.unwrap_or(".");
352 let depth = usize_argument(invocation, "depth")?.unwrap_or(1);
353 let limit = result_limit(invocation)?;
354 let root = self
355 .workspace
356 .resolve_existing(path)
357 .map_err(FileToolError::from)?;
358 let metadata = fs::metadata(root.host_path())
359 .map_err(|_| FileToolError::new(FileToolErrorCode::FilesystemFailure))?;
360 if !metadata.is_dir() {
361 return Err(FileToolError::new(FileToolErrorCode::NotAFile).into());
362 }
363 let mut entries = Vec::new();
364 let mut visible_lines = Vec::new();
365 let mut output_bytes = 0_usize;
366 let mut truncated = false;
367 for (visited, entry) in walker(root.host_path(), Some(depth)).enumerate() {
368 check_cancelled(cancellation)?;
369 if visited >= MAX_SEARCH_ENTRIES {
370 truncated = true;
371 break;
372 }
373 let entry =
374 entry.map_err(|_| FileToolError::new(FileToolErrorCode::FilesystemFailure))?;
375 if entry.depth() == 0 || is_symlink(&entry) {
376 continue;
377 }
378 let Some(relative) = relative_path(&self.workspace, entry.path()) else {
379 continue;
380 };
381 let kind = if is_directory(&entry) {
382 "directory"
383 } else {
384 "file"
385 };
386 if entries.len() >= limit
387 || output_bytes.saturating_add(relative.len()) > MAX_SEARCH_OUTPUT_BYTES
388 {
389 truncated = true;
390 break;
391 }
392 output_bytes += relative.len();
393 visible_lines.push(format!(
394 "{relative}{}",
395 if kind == "directory" { "/" } else { "" }
396 ));
397 entries.push(json!({"path":relative,"kind":kind}));
398 }
399 let mut visible = bounded_lines(&visible_lines);
400 if visible.is_empty() {
401 visible.push_str("(empty directory)");
402 }
403 if truncated {
404 visible.push_str("\n[results truncated]");
405 }
406 Ok(success(
407 visible,
408 json!({"entries":entries,"truncated":truncated}),
409 ))
410 }
411}
412
413impl ToolExecutor for LsTool {
414 fn execute(
415 &self,
416 invocation: ValidatedToolInvocation,
417 cancellation: CancellationScope,
418 ) -> BoxToolExecutionStream {
419 let executor = self.clone();
420 Box::pin(stream::once(async move {
421 terminal(executor.run(&invocation, &cancellation))
422 }))
423 }
424}
425
426fn search_spec(
427 name: &str,
428 description: &str,
429 input_schema: Value,
430 output_schema: Value,
431 prompt_hint: &str,
432) -> Result<ToolSpec, ToolSpecError> {
433 ToolSpec::new(
434 ToolName::from_str(name).map_err(|_| ToolSpecError::InvalidDescription)?,
435 ToolVersion::from_str("1.0.0").map_err(|_| ToolSpecError::InvalidDescription)?,
436 description,
437 input_schema,
438 output_schema,
439 [ToolEffect::FsRead],
440 ToolExecutionSemantics::new(
441 ToolIdempotency::Idempotent,
442 ToolRetrySafety::Automatic,
443 ToolConcurrency::Parallel,
444 ToolTimeout::from_millis(30_000)?,
445 )?,
446 )?
447 .with_prompt_hint(prompt_hint)
448}
449
450fn list_output_schema(field: &str) -> Value {
451 json!({
452 "type":"object",
453 "properties":{
454 field:{"type":"array","items":{"type":"string"}},
455 "truncated":{"type":"boolean"}
456 },
457 "required":[field,"truncated"],
458 "additionalProperties":false
459 })
460}
461
462fn walker(path: &std::path::Path, max_depth: Option<usize>) -> ignore::Walk {
463 let mut builder = WalkBuilder::new(path);
464 builder
465 .hidden(false)
466 .parents(true)
467 .require_git(false)
468 .git_ignore(true)
469 .git_exclude(true)
470 .git_global(false)
471 .follow_links(false)
472 .same_file_system(true)
473 .max_depth(max_depth)
474 .sort_by_file_path(std::path::Path::cmp);
475 builder.build()
476}
477
478fn relative_path(workspace: &WorkspaceRoot, path: &std::path::Path) -> Option<String> {
479 let relative = path.strip_prefix(workspace.host_path()).ok()?;
480 let relative = relative.to_str()?.replace(std::path::MAIN_SEPARATOR, "/");
481 Some(if relative.is_empty() {
482 ".".to_owned()
483 } else {
484 relative
485 })
486}
487
488fn is_regular_file(entry: &DirEntry) -> bool {
489 entry.file_type().is_some_and(|kind| kind.is_file())
490}
491
492fn is_directory(entry: &DirEntry) -> bool {
493 entry.file_type().is_some_and(|kind| kind.is_dir())
494}
495
496fn is_symlink(entry: &DirEntry) -> bool {
497 entry.file_type().is_some_and(|kind| kind.is_symlink())
498}
499
500fn compile_glob(pattern: &str) -> Result<GlobMatcher, FileToolError> {
501 Glob::new(pattern)
502 .map(|glob| glob.compile_matcher())
503 .map_err(|_| FileToolError::new(FileToolErrorCode::InvalidArguments))
504}
505
506fn optional_glob(
507 invocation: &ValidatedToolInvocation,
508 name: &str,
509) -> Result<Option<GlobMatcher>, FileToolError> {
510 optional_string_argument(invocation, name)?
511 .map(compile_glob)
512 .transpose()
513}
514
515fn glob_matches(matcher: &GlobMatcher, relative: &str) -> bool {
516 matcher.is_match(relative)
517 || relative
518 .rsplit_once('/')
519 .is_some_and(|(_, name)| matcher.is_match(name))
520}
521
522fn collect_file_matches(
523 regex: &Regex,
524 path: &str,
525 source: &str,
526 limit: usize,
527 matches: &mut Vec<Value>,
528 visible: &mut String,
529 output_bytes: &mut usize,
530) -> bool {
531 for (line_index, line) in source.lines().enumerate() {
532 let Some(found) = regex.find(line) else {
533 continue;
534 };
535 let text = truncate_utf8(line, MAX_MATCH_LINE_BYTES);
536 let estimated = path.len().saturating_add(text.len()).saturating_add(64);
537 if matches.len() >= limit
538 || output_bytes.saturating_add(estimated) > MAX_SEARCH_OUTPUT_BYTES
539 {
540 return true;
541 }
542 *output_bytes += estimated;
543 let line_number = line_index + 1;
544 let column = line[..found.start()].chars().count() + 1;
545 matches.push(json!({
546 "path":path,
547 "line":line_number,
548 "column":column,
549 "text":text
550 }));
551 if visible.len() < MAX_VISIBLE_OUTPUT_BYTES {
552 let rendered = format!("{path}:{line_number}:{column}: {text}\n");
553 let remaining = MAX_VISIBLE_OUTPUT_BYTES - visible.len();
554 visible.push_str(truncate_utf8(&rendered, remaining));
555 }
556 }
557 false
558}
559
560fn visible_paths(paths: &[String], truncated: bool) -> String {
561 let mut visible = bounded_lines(paths);
562 if visible.is_empty() {
563 visible.push_str("No paths found.");
564 }
565 if truncated {
566 visible.push_str("\n[results truncated]");
567 }
568 visible
569}
570
571fn bounded_lines(lines: &[String]) -> String {
572 let mut visible = String::new();
573 for line in lines {
574 if visible.len() >= MAX_VISIBLE_OUTPUT_BYTES {
575 break;
576 }
577 let remaining = MAX_VISIBLE_OUTPUT_BYTES - visible.len();
578 let rendered = format!("{line}\n");
579 visible.push_str(truncate_utf8(&rendered, remaining));
580 }
581 visible.trim_end_matches('\n').to_owned()
582}
583
584fn truncate_utf8(text: &str, max_bytes: usize) -> &str {
585 if text.len() <= max_bytes {
586 return text;
587 }
588 let mut end = max_bytes;
589 while end > 0 && !text.is_char_boundary(end) {
590 end -= 1;
591 }
592 &text[..end]
593}
594
595fn optional_string_argument<'a>(
596 invocation: &'a ValidatedToolInvocation,
597 name: &str,
598) -> Result<Option<&'a str>, FileToolError> {
599 invocation
600 .arguments()
601 .get(name)
602 .map(|value| {
603 value
604 .as_str()
605 .ok_or_else(|| FileToolError::new(FileToolErrorCode::InvalidArguments))
606 })
607 .transpose()
608}
609
610fn usize_argument(
611 invocation: &ValidatedToolInvocation,
612 name: &str,
613) -> Result<Option<usize>, FileToolError> {
614 invocation
615 .arguments()
616 .get(name)
617 .map(|value| {
618 value
619 .as_u64()
620 .and_then(|value| usize::try_from(value).ok())
621 .ok_or_else(|| FileToolError::new(FileToolErrorCode::InvalidArguments))
622 })
623 .transpose()
624}
625
626fn bool_argument(
627 invocation: &ValidatedToolInvocation,
628 name: &str,
629) -> Result<Option<bool>, FileToolError> {
630 invocation
631 .arguments()
632 .get(name)
633 .map(|value| {
634 value
635 .as_bool()
636 .ok_or_else(|| FileToolError::new(FileToolErrorCode::InvalidArguments))
637 })
638 .transpose()
639}
640
641fn result_limit(invocation: &ValidatedToolInvocation) -> Result<usize, FileToolError> {
642 Ok(usize_argument(invocation, "limit")?.unwrap_or(DEFAULT_SEARCH_RESULT_LIMIT))
643}
644
645fn check_cancelled(cancellation: &CancellationScope) -> Result<(), SearchRunError> {
646 if cancellation.is_cancelled() {
647 Err(SearchRunError::Cancelled)
648 } else {
649 Ok(())
650 }
651}
652
653fn terminal(result: Result<ToolExecutionEvent, SearchRunError>) -> ToolExecutionEvent {
654 match result {
655 Ok(event) => event,
656 Err(SearchRunError::File(error)) => failure(error),
657 Err(SearchRunError::Cancelled) => {
658 ToolExecutionEvent::Failed(ToolExecutionFailure::cancelled())
659 }
660 }
661}
662
663enum SearchRunError {
664 File(FileToolError),
665 Cancelled,
666}
667
668impl From<FileToolError> for SearchRunError {
669 fn from(error: FileToolError) -> Self {
670 Self::File(error)
671 }
672}