@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

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

Usage

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

read

Read file contents from the file system.

Parameters:

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

Example:

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

write

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:

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

edit

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:

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

bash

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:

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

Returns: JSON with exitCode, stdout, and stderr

glob

Find files matching a pattern.

Parameters:

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

Example:

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

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

grep

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:

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

Configuration

Enable/Disable Tools

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

Permission System

Restrict which paths and commands agents can access:

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
  },
});

Permission Examples

Allow only project directory:

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

Deny sensitive files:

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

Restrict bash to read-only commands:

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.

Recommended Production Config

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