Handle empty filters in ListDirectoryTool and add associated test cases (#1285)

denis-domanskii · web-flow · commit 3c0cca2e91fe · 2025-12-18T20:29:14.000+01:00
## Motivation and Context  [KG-628](https://youtrack.jetbrains.com/issue/KG-628) ListDirectoryTool: filter="" excludes files from the output ## Breaking Changes  --- #### Type of the changes - [ ] New feature (non-breaking change which adds functionality) - [x ] Bug fix (non-breaking change which fixes an issue) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Tests improvement - [ ] Refactoring #### Checklist - [ x] The pull request has a description of the proposed change - [x ] I read the [Contributing Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md) before opening the pull request - [x ] The pull request uses **`develop`** as the base branch - [ x] Tests for the changes have been added - [ x] All new and existing tests passed ##### Additional steps for pull requests adding a new feature - [ ] An issue describing the proposed change exists - [ ] The pull request includes a link to the issue - [ ] The change was discussed and approved in the issue - [ ] Docs have been added / updated
diff --git a/agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/tool/file/ListDirectoryTool.kt b/agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/tool/file/ListDirectoryTool.kt
@@ -26,31 +26,85 @@ public class ListDirectoryTool<Path>(private val fs: FileSystemProvider.ReadOnly
         resultSerializer = Result.serializer(),
         name = "__list_directory__",
         description = """
-            Lists files and subdirectories in a directory. READ-ONLY - never modifies anything.
+            List a directory as a tree so an agent can *orient itself* in an unknown filesystem/repo and decide what to read next.
 
-            Use this to:
-            - See what files exist before reading or creating
-            - Understand project structure
-            - Find specific files with patterns
+            This is usually the first tool to call:
+            - Find where code, configs, and docs live
+            - Confirm filenames and exact paths before reading/editing
+            - Narrow the search space with a glob instead of dumping huge directory listings
 
-            Returns a tree showing all contents with sizes and metadata.
+            Recommended agent workflow:
+            1) Call with a small `depth` (often `1` or `2`) to understand the top-level layout.
+            2) If you need to locate specific files, add a `filter` (glob) and increase `depth` to '5' or more.
+            3) Once you see the exact path(s), switch to other tools to work with content.
+
+            This tool does NOT:
+            - Return file contents
+            - Search inside files (it only matches on paths via `filter`)
+            - Modify the filesystem (read-only)
+
+            Common pitfalls:
+            - `filter="*.js"` only matches files directly under `absolutePath`. For “any depth”, use `filter="**/*.js"`.
+            - Glob does not override `depth`. If files exist deeper than the traversal can reach, you’ll get “no matches”.
+
+            Returns a structured tree rooted at the requested directory.
         """.trimIndent()
     ) {
 
     /**
      * Specifies which directory to list and how to traverse its contents.
      *
-     * @property path absolute filesystem path to the target directory
-     * @property depth how many levels deep to traverse (1 = direct children only, 2 = include subdirectories, etc.), defaults to 1
-     * @property filter glob pattern to match specific files/folders (e.g., "*.kt" for Kotlin files), defaults to null
+     * @property absolutePath absolute filesystem path to the target directory
+     * @property depth how many levels deep to traverse (1 = direct children only, 2 = include subdirectories, etc.),
+     *   defaults to 1; single-child directory chains may be collapsed without consuming depth
+     * @property filter optional glob pattern (case-insensitive) matched against normalized relative paths (from
+     *   [absolutePath]) using `/` as a separator; defaults to null (no filtering)
      */
     @Serializable
     public data class Args(
-        @property:LLMDescription("Absolute path to the directory you want to list (e.g., /home/user/project)")
-        val path: String,
-        @property:LLMDescription("How many levels deep to go. 1 = only direct contents, 2 = include subdirectories, etc. Default is 1")
+        @property:LLMDescription(
+            """
+            Absolute path to the directory to list.
+            Requirements:
+            - Must be an absolute path (not relative)
+            - Must point to a directory (not a file)
+            """
+        )
+        val absolutePath: String,
+        @property:LLMDescription(
+            """
+            Maximum traversal depth (> 0). Default is `1`.
+            Guidance:
+            - Start with `1` to avoid large outputs.
+            - Increase when you need to see inside subfolders, but prefer adding a `filter` to keep results small.
+            """
+        )
         val depth: Int = 1,
-        @property:LLMDescription("Glob pattern to match files/folders. Examples: '*.txt' for text files, '**/*.kt' for all Kotlin files at any depth")
+        @property:LLMDescription(
+            """
+            Optional glob filter for narrowing results (case-insensitive). Use `null` or `""` to disable filtering.
+
+            What it matches:
+            - The pattern is matched against each entry’s *relative path* from `absolutePath` (normalized to `/`, even on Windows).
+              Example relative paths: `README.md`, `src/main/kotlin/App.kt`, `tests/__init__.py`.
+
+            What you get back:
+            - Matching files are included.
+            - Directories are included when they contain matching entries (to preserve structure).
+            - If `depth` is too small to reach matches, you may get a “no matches” error even if the files exist deeper.
+
+            Supported syntax:
+            - `*` matches within a single path segment (does not cross `/`)
+            - `**` can cross `/` (any depth)
+            - `?`, `[...]`, `[!...]`, `{a,b}` alternatives are supported
+
+            Practical examples:
+            - `"**/*.java"`: all Java files anywhere under `absolutePath`
+            - `"*/*.ts"`: TypeScript files exactly 1 folder below `absolutePath`
+            - `"*/Test*"`: test files like `test/TestMain.cs`
+            - `"**/{build.gradle.kts,settings.gradle.kts}"`: find Gradle build entrypoints
+            """
+        )
         val filter: String? = null
     )
 
@@ -82,23 +136,25 @@ public class ListDirectoryTool<Path>(private val fs: FileSystemProvider.ReadOnly
     override suspend fun execute(args: Args): Result {
         validate(args.depth > 0) { "Depth must be at least 1 (got ${args.depth})" }
 
-        val path = fs.fromAbsolutePathString(args.path)
-        val metadata = validateNotNull(fs.metadata(path)) { "Path does not exist: ${args.path}" }
+        val path = fs.fromAbsolutePathString(args.absolutePath)
+        val metadata = validateNotNull(fs.metadata(path)) { "Path does not exist: ${args.absolutePath}" }
 
         validate(metadata.type == FileMetadata.FileType.Directory) {
-            "Path is not a directory: ${args.path} (it's a ${metadata.type})"
+            "Path is not a directory: ${args.absolutePath} (it's a ${metadata.type})"
         }
 
         val entry = buildDirectoryTree(
             fs = fs,
             start = path,
             startMetadata = metadata,
             maxDepth = args.depth,
-            filter = args.filter?.let { GlobPattern(it, caseSensitive = false) }
+            filter = args.filter?.ifEmpty { null }?.let {
+                GlobPattern(pattern = it, caseSensitive = false)
+            }
         )
 
         validate(entry != null) {
-            "No files or directories match the pattern '${args.filter}' in ${args.path}"
+            "No files or directories match the pattern '${args.filter}' in ${args.absolutePath}"
         }
 
         return Result(entry as FileSystemEntry.Folder)
diff --git a/agents/agents-ext/src/jvmTest/kotlin/ai/koog/agents/ext/tool/file/ListDirectoryToolJvmTest.kt b/agents/agents-ext/src/jvmTest/kotlin/ai/koog/agents/ext/tool/file/ListDirectoryToolJvmTest.kt
@@ -33,7 +33,7 @@ class ListDirectoryToolJvmTest {
     @Test
     fun `Args uses correct defaults`() {
         val args = ListDirectoryTool.Args("/tmp/test")
-        assertEquals("/tmp/test", args.path)
+        assertEquals("/tmp/test", args.absolutePath)
         assertEquals(1, args.depth)
         assertNull(args.filter)
     }
@@ -43,7 +43,7 @@ class ListDirectoryToolJvmTest {
         val descriptor = tool.descriptor
         assertEquals("__list_directory__", descriptor.name)
         assertTrue(descriptor.description.isNotEmpty())
-        assertEquals(listOf("path"), descriptor.requiredParameters.map { it.name })
+        assertEquals(listOf("absolutePath"), descriptor.requiredParameters.map { it.name })
         assertEquals(setOf("depth", "filter"), descriptor.optionalParameters.map { it.name }.toSet())
     }
 
@@ -105,7 +105,7 @@ class ListDirectoryToolJvmTest {
         dir.resolve("README.md").createFile().writeText("hello") // 5 bytes
         dir.resolve("LICENSE.txt").createFile().writeText("MIT") // 3 bytes
 
-        val resultText = tool.encodeResultToString(list(dir, depth = 2))
+        val resultText = tool.encodeResultToString(list(dir, depth = 1))
 
         // Expected:
         // /path/to/project/
@@ -454,6 +454,50 @@ class ListDirectoryToolJvmTest {
         assertEquals(expectedText, resultText)
     }
 
+    @Test
+    fun `empty filter outputs all files`() = runBlocking {
+        // Structure:
+        // project/
+        // ├── LICENSE.txt
+        // └── README.md
+        val dir = createDir("project")
+        dir.resolve("README.md").createFile().writeText("hello") // 5 bytes
+        dir.resolve("LICENSE.txt").createFile().writeText("MIT") // 3 bytes
+
+        val resultText = tool.encodeResultToString(list(dir, depth = 1, filter = ""))
+
+        // Expected:
+        // /path/to/project/
+        //   LICENSE.txt (<0.1 KiB, 1 line)
+        //   README.md (<0.1 KiB, 1 line)
+        val expectedText = """
+            ${dir.toAbsolutePath().toString().norm()}/
+              LICENSE.txt (<0.1 KiB, 1 line)
+              README.md (<0.1 KiB, 1 line)
+        """.trimIndent()
+
+        assertEquals(expectedText, resultText)
+    }
+
+    @Test
+    fun `filter is case insensitive`() = runBlocking {
+        // Structure:
+        // project/
+        // ├── LICENSE.txt
+        // └── README.md
+        val dir = createDir("project")
+        dir.resolve("README.md").createFile().writeText("hello") // 5 bytes
+        dir.resolve("LICENSE.txt").createFile().writeText("MIT") // 3 bytes
+
+        val resultText = tool.encodeResultToString(list(dir, depth = 1, filter = "read*"))
+
+        // Expected:
+        // /path/to/project/README.md (<0.1 KiB, 1 line)
+        val expectedText = "${dir.toAbsolutePath().toString().norm()}/README.md (<0.1 KiB, 1 line)"
+
+        assertEquals(expectedText, resultText)
+    }
+
     @Test
     fun `complex nested structure with mixed content`() = runBlocking {
         // Structure:
