@ellie-ai/agent-fs-tools-plugin

File system and command execution tools for Ellie agents.

Overview

This plugin provides agents with the ability to:

- Read files - Read file contents in UTF-8 or base64 encoding
- Write files - Create or overwrite files with content
- Edit files - Make precise string replacements in files
- Execute commands - Run shell commands via bash
- Find files - Use glob patterns to locate files
- Search content - Search file contents with regex patterns

Installation

``bash
bun add @ellie-ai/agent-fs-tools-plugin
`

Usage

`typescript
import { createRuntime } from "@ellie-ai/runtime";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import { fsToolsPlugin } from "@ellie-ai/agent-fs-tools-plugin";
import { openAI } from "@ellie-ai/model-providers";

const runtime = createRuntime({
plugins: [
agentPlugin({
model: openAI(),
toolPlugins: [fsToolsPlugin()],
}),
],
});
`

Tools

$3

Read file contents from the file system.

Parameters:
- path (string, required): Absolute or relative file path
- encoding (string, optional): "utf8" (default) or "base64"

Example:
`json
{
"path": "/path/to/file.txt",
"encoding": "utf8"
}
`

$3

Create or overwrite a file with content.

Parameters:
- path (string, required): File path to write to
- content (string, required): Content to write
- encoding (string, optional): "utf8" (default) or "base64"

Example:
`json
{
"path": "/path/to/file.txt",
"content": "Hello world"
}
`

$3

Make precise edits by replacing old_string with new_string.

Parameters:
- path (string, required): File path to edit
- old_string (string, required): Exact text to find
- new_string (string, required): Text to replace with
- replace_all (boolean, optional): Replace all occurrences (default: false)

Example:
`json
{
"path": "/path/to/file.txt",
"old_string": "Hello",
"new_string": "Hi",
"replace_all": true
}
`

$3

Execute shell commands.

Parameters:
- command (string, required): Shell command to execute
- cwd (string, optional): Working directory
- timeout (number, optional): Timeout in milliseconds (default: 30000)

Example:
`json
{
"command": "ls -la",
"cwd": "/tmp"
}
`

Returns: JSON with exitCode, stdout, and stderr

$3

Find files matching a pattern.

Parameters:
- pattern (string, required): Glob pattern (e.g., "*/.ts")
- cwd (string, optional): Directory to search in

Example:
`json
{
"pattern": "src/*/.ts",
"cwd": "/path/to/project"
}
`

Returns: JSON array of matching file paths, sorted by modification time

$3

Search file contents with regex.

Parameters:
- pattern (string, required): Regular expression pattern
- path (string, optional): File or directory to search in
- glob (string, optional): File filter pattern (default: "*/")
- context (number, optional): Number of context lines (default: 0)

Example:
`json
{
"pattern": "function.*test",
"path": "/path/to/project",
"glob": "*/.ts",
"context": 2
}
`

Configuration

$3

`typescript
fsToolsPlugin({
tools: {
read: true,
write: true,
edit: true,
bash: true,
glob: true,
grep: false, // Disable grep tool
},
});
`

$3

Restrict which paths and commands agents can access:

`typescript
fsToolsPlugin({
permissions: {
// Allow access to specific paths (glob patterns)
allowedPaths: ["/tmp/", "/home/user/projects/"],

// Deny access to specific paths (takes precedence)
deniedPaths: ["/etc/", "/home/user/.ssh/"],

// Restrict bash commands to specific prefixes
allowedCommands: ["ls", "cat", "grep", "find"],

// Maximum file size for read operations (in bytes)
maxFileSize: 1024 * 1024, // 1MB
},
});
`

$3

Allow only project directory:
`typescript
fsToolsPlugin({
permissions: {
allowedPaths: ["/home/user/my-project/**"],
},
});
`

Deny sensitive files:
`typescript
fsToolsPlugin({
permissions: {
deniedPaths: [
"/etc/**",
"/home/user/.ssh/**",
"/home/user/.aws/**",
"**/.env",
],
},
});
`

Restrict bash to read-only commands:
`typescript
fsToolsPlugin({
permissions: {
allowedCommands: ["ls", "cat", "grep", "find", "head", "tail"],
},
});
`

Security Considerations

⚠️ File System Access: This plugin gives agents full file system access by default. Always configure permissions in production environments.

⚠️ Command Execution: The bash tool can execute arbitrary commands. Consider:
- Disabling bash entirely in untrusted environments
- Using allowedCommands to restrict to safe read-only commands
- Running agents in sandboxed environments

⚠️ Path Traversal: Permission checks use glob patterns. Test your patterns carefully to avoid unintended access.

$3

`typescript
fsToolsPlugin({
tools: {
bash: false, // Disable command execution
},
permissions: {
allowedPaths: ["/var/app/data/", "/tmp/agent-workspace/"],
deniedPaths: ["/.env", "/.git/", "/node_modules/**"],
maxFileSize: 10 1024 1024, // 10MB limit
},
});
``

License

MIT