Skip to main content

tea_coding_tools/
search.rs

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
22/// Default maximum number of entries returned by a search tool.
23pub const DEFAULT_SEARCH_RESULT_LIMIT: usize = 100;
24/// Maximum result limit accepted by a search tool invocation.
25pub const MAX_SEARCH_RESULT_LIMIT: usize = 1_000;
26/// Maximum recursive depth accepted by `ls`.
27pub 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/// Workspace-confined bounded regular-expression search.
38#[derive(Debug, Clone)]
39pub struct GrepTool {
40    workspace: WorkspaceRoot,
41}
42
43impl GrepTool {
44    /// Creates a grep tool bound to one validated workspace capability.
45    #[must_use]
46    pub const fn new(workspace: WorkspaceRoot) -> Self {
47        Self { workspace }
48    }
49
50    /// Builds the portable `grep` tool contract.
51    ///
52    /// # Errors
53    ///
54    /// Returns an error only if the static contract violates tool bounds.
55    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                &regex,
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/// Workspace-confined bounded path search.
203#[derive(Debug, Clone)]
204pub struct FindTool {
205    workspace: WorkspaceRoot,
206}
207
208impl FindTool {
209    /// Creates a find tool bound to one validated workspace capability.
210    #[must_use]
211    pub const fn new(workspace: WorkspaceRoot) -> Self {
212        Self { workspace }
213    }
214
215    /// Builds the portable `find` tool contract.
216    ///
217    /// # Errors
218    ///
219    /// Returns an error only if the static contract violates tool bounds.
220    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/// Workspace-confined bounded directory listing.
303#[derive(Debug, Clone)]
304pub struct LsTool {
305    workspace: WorkspaceRoot,
306}
307
308impl LsTool {
309    /// Creates an ls tool bound to one validated workspace capability.
310    #[must_use]
311    pub const fn new(workspace: WorkspaceRoot) -> Self {
312        Self { workspace }
313    }
314
315    /// Builds the portable `ls` tool contract.
316    ///
317    /// # Errors
318    ///
319    /// Returns an error only if the static contract violates tool bounds.
320    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}