Self-improving AI Employees for everyone
FS Search (fsSearch)
| Field | Value |
|---|---|
| Category | code_fs_process / filesystem |
| Backend handler | server/nodes/filesystem/fs_search/__init__.py::FsSearchNode.search (dispatched via BaseNode.execute() + @Operation("search")) |
| Backend | Native WorkspaceBackend (ls_info, glob_info, grep_raw) in server/nodes/filesystem/_backend.py |
| Tests | server/tests/nodes/test_code_fs_process.py |
| Skill (if any) | server/skills/coding_agent/fs-search-skill/SKILL.md |
| Dual-purpose tool | yes - tool name fs_search |
Purpose
Three-mode filesystem query node confined to the per-workflow workspace.
Dispatches to ls_info(), glob_info(), or grep_raw() on the native
WorkspaceBackend via get_backend() depending on mode. The path is run
through normalize_virtual_path() first, and each filesystem operation
resolves the target beneath the workspace root with symlink containment.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Not consumed |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
mode |
ls | glob | grep (Literal) |
ls |
no | - | ls, glob, or grep |
path |
string | . |
no | - | Directory path to search in (workspace-relative) |
pattern |
string | "" |
yes (when mode != ls) |
- | Glob pattern or literal grep text |
FsSearchParams uses extra="ignore" — there are NO file_filter or
working_directory params; the model drops unknown keys. The grep mode passes
only pattern + path to backend.grep_raw(). (displayOptions are not
declared on these fields in the current Params model.)
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Standard envelope payload (node declares only input-main / output-main; usable_as_tool=True exposes the same payload as the fs_search tool result) |
Output payload
// ls
{ path: string; entries: Array<FileInfo>; count: number }
// glob
{ path: string; pattern: string; matches: Array<FileInfo>; count: number }
// grep
{ path: string; pattern: string; matches: Array<GrepMatch>; count: number }
FileInfo and GrepMatch are JSON-safe dictionaries returned by the native
backend. The node defensively copies each with dict(entry).
node_output_schemas.FsSearchOutput declares path / entries / matches /
pattern / count (extra fields allowed by _OutputBase).
Logic Flow
flowchart TD
A[search] --> C[get_backend + normalize_virtual_path]
C --> D{mode?}
D -- ls --> L[to_thread backend.ls_info path]
L --> Lok[Return dict path, entries, count]
D -- glob --> G{pattern empty?}
G -- yes --> Gp[raise NodeUserError:<br/>pattern is required for glob mode]
G -- no --> Gr[to_thread backend.glob_info pattern, path]
Gr --> Grok[Return dict path, pattern, matches, count]
D -- grep --> Gg{pattern empty?}
Gg -- yes --> Ggp[raise NodeUserError:<br/>pattern is required for grep mode]
Gg -- no --> Gx[to_thread backend.grep_raw pattern, path]
Gx --> Gxt{result type?}
Gxt -- str error --> Gxerr[raise NodeUserError result]
Gxt -- list --> Gxok[Return dict path, pattern, matches, count]
D -- other --> U[raise NodeUserError:<br/>Unknown mode: <mode>]
Decision Logic
mode=lsrequires nothing; defaultspath='.'.mode=globrequirespattern. Missing pattern ->raise NodeUserError.mode=greprequirespattern. No file-filter kwarg is passed (onlypattern+path).grep_rawpolymorphic return: the backend returns either a list ofGrepMatchobjects (success) OR a plain string (error description). The plugin checksisinstance(result, str)andraise NodeUserError(result).- Unknown modes:
raise NodeUserError("Unknown mode: <mode>")(Pydantic Literal already constrains it). - All raises become single-WARN-line
error_type="NodeUserError"envelopes viaBaseNode.execute().
Side Effects
- Database writes: none.
- Broadcasts: none.
- External API calls: none.
- File I/O:
get_backendensures the workspace root exists.- Reads directory listings and file contents under
<root>/<path>.
- Subprocess: none (
grep_rawis a local Python file walk and literal substring search; it does not invokegrep(1)).
External Dependencies
- Python packages: standard library only.
- Environment variables:
WORKSPACE_BASE_DIR.
Edge cases & known limits
grep_rawstring-error path is unique: unlike ls/glob which raise, grep can "succeed" at the Python level but return a string; the plugin converts that to aNodeUserErrorso the final envelope shape is consistent.- Glob patterns match the backend's semantics:
**globs work, but the backend's behaviour for symlinks, hidden files, and case sensitivity is inherited frompathlib. - No maxResults cap: a
**/*glob over a huge workspace returns every match; the handler does not paginate. The caller must truncate. path='.'resolves against the workspace root, not the server CWD.working_directorynot exposed:extra="ignore"means the sandbox cannot be widened via a node param on this node.- Result copying:
dict()makes each native result mapping independent before output validation and serialization.
Related
- Skills using this as a tool:
fs-search-skill/SKILL.md - Sibling nodes:
fileRead,fileModify,shell