filesystem

Agent-optimized filesystem operations with constraint-based sandboxing.

Property	Value
Module ID	filesystem
Version	2.0.0
Type	system
Platforms	Linux, macOS, Windows
Dependencies	None (stdlib only). Optional: ripgrep for faster grep.
Permissions	fs.read, fs.write, fs.delete, fs.list

---

Design Philosophy

This module is designed for AI agents, not humans. Key principles:

• Line numbers everywhere — read returns Nline format so the agent can reference exact locations.
• Surgical edits — edit replaces a specific text block, insert adds at a precise line. No need to rewrite whole files.
• Fast search — grep delegates to native tools (ripgrep -- grep -- Python fallback).
• Constraint-aware — applications restrict paths and file sizes via YAML constraints.

---

Actions

read

Read a file with line numbers. Supports partial reads.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to the file
start_line	integer	no	1	First line (1-indexed)
end_line	integer	no	last	Last line (1-indexed)
encoding	string	no	"utf-8"	Text encoding

Returns:

{
  "path": "/workspace/main.py",
  "content": " 1import os\n 2import sys\n",
  "total_lines": 42,
  "start_line": 1,
  "end_line": 2,
  "size_bytes": 1024
}

Permissions: fs.read | Risk: Low | Constraints: paths, max_file_size

---

write

Create or overwrite a file.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to write to
content	string	yes	—	Text content
create_dirs	boolean	no	false	Create parent directories
encoding	string	no	"utf-8"	Text encoding

Permissions: fs.write | Risk: Medium | Side effects: filesystem_write | Constraints: paths, max_file_size

---

edit

Replace a specific text block (old_string -- new_string). Returns a preview with line numbers.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to the file
old_string	string	yes	—	Exact text to find
new_string	string	yes	—	Replacement text
count	integer	no	1	Occurrences to replace (0 = all)

Returns:

{
  "path": "/workspace/main.py",
  "replacements": 1,
  "preview": "10    old_code\n11    NEW_CODE\n12    next_line\n"
}

Permissions: fs.read, fs.write | Risk: Medium | Side effects: filesystem_write | Constraints: paths

---

insert

Insert text at a specific line number.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to the file
line	integer	yes	—	Line number to insert before (1-indexed)
content	string	yes	—	Text to insert

Permissions: fs.read, fs.write | Risk: Medium | Side effects: filesystem_write | Constraints: paths

---

ls

List directory contents with type and size.

Parameter	Type	Required	Default	Description
path	string	no	"."	Directory to list
recursive	boolean	no	false	Recurse into subdirectories
pattern	string	no	null	Glob filter (e.g. "*.py")
include_hidden	boolean	no	false	Include dotfiles

Permissions: fs.list | Risk: Low | Constraints: paths

---

grep

Search file contents for a regex pattern. Uses native tools for speed.

Parameter	Type	Required	Default	Description
pattern	string	yes	—	Regex pattern
path	string	no	"."	File or directory to search
include	string	no	null	Glob filter (e.g. "*.py")
recursive	boolean	no	true	Search subdirectories
max_results	integer	no	100	Maximum matches
case_sensitive	boolean	no	true	Case-sensitive matching

Returns:

{
  "matches": [
    {"file": "/workspace/src/main.py", "line": 42, "text": "    raise ValueError('invalid')"}
  ],
  "count": 1
}

Performance: Tries rg (ripgrep) first, then grep, then Python re fallback.

Permissions: fs.read | Risk: Low | Constraints: paths

---

find

Find files by glob pattern.

Parameter	Type	Required	Default	Description
pattern	string	yes	—	Glob pattern (e.g. "*.py")
path	string	no	"."	Root directory
type	string	no	null	"file" or "dir"
max_results	integer	no	100	Maximum results

Permissions: fs.read | Risk: Low | Constraints: paths

---

mv

Move or rename a file or directory.

Parameter	Type	Required	Default	Description
source	string	yes	—	Source path
destination	string	yes	—	Destination path
overwrite	boolean	no	false	Overwrite if exists

Permissions: fs.read, fs.write | Risk: Medium | Side effects: filesystem_write | Constraints: paths (both)

---

cp

Copy a file or directory.

Parameter	Type	Required	Default	Description
source	string	yes	—	Source path
destination	string	yes	—	Destination path
overwrite	boolean	no	false	Overwrite if exists

Permissions: fs.read, fs.write | Risk: Medium | Side effects: filesystem_write | Constraints: paths (both)

---

rm

Delete a file or directory. Irreversible.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to delete
recursive	boolean	no	false	Required for directories

Permissions: fs.delete | Risk: High | Side effects: filesystem_delete | Constraints: paths

---

mkdir

Create a directory and parent directories.

Parameter	Type	Required	Default	Description
path	string	yes	—	Directory path

Permissions: fs.write | Risk: Low | Side effects: filesystem_write | Constraints: paths

---

file_stat

Get file or directory metadata.

Parameter	Type	Required	Default	Description
path	string	yes	—	Path to inspect

Returns:

{
  "path": "/workspace/main.py",
  "name": "main.py",
  "type": "file",
  "size_bytes": 1234,
  "modified": 1709942400.0,
  "created": 1709856000.0,
  "permissions": "0o644",
  "is_symlink": false
}

Permissions: fs.read | Risk: Low | Constraints: paths

---

Constraints

Modules declare which constraints they support. Applications set values in their YAML definition. The runtime resolves template variables and passes constraints to the module via ExecutionContext.

Constraint	Type	Scope	Default	Description
paths	string_list	Universal	—	Allowed path prefixes. All operations restricted.
max_file_size	size	Module	"100MB"	Max file size for read/write/edit/insert/cp.

Example App YAML

modules:
  - module: filesystem
    actions: [read, write, edit, insert, ls, grep, find, mkdir, rm]
    constraints:
      paths: ["{{workspace}}"]
      max_file_size: "50MB"

Enforcement

• paths — Every action checks the resolved path against the allowed prefixes before any I/O. mv and cp check both source and destination.
• max_file_size — read checks file size before reading. write checks content size before writing.
• No constraints — When no ExecutionContext is provided (dev mode, unit tests), all operations are allowed.

---

Security

Symlink Resolution

All actions resolve paths via Path.resolve(strict=False) before any operation. This prevents write-through-symlink attacks where a symlink targets a location outside the allowed paths.

Path Constraint Enforcement

Agent requests: read("/workspace/../etc/passwd")
    ↓
Path resolved: /etc/passwd
    ↓
Constraint check: /etc/passwd not in ["/workspace"]
    ↓
ActionResult(success=False, error="Path '/etc/passwd' is outside allowed paths")

---

Performance

Strategy	Detail
Sync I/O threshold	Files under 512 KB are read/written synchronously (no thread pool overhead)
Native grep	grep action uses subprocess to rg or grep for 10-100x faster search
No re-encoding	write encodes once, writes bytes directly
Lazy glob	ls and find use generators with early termination at max_results