# tool_filesystem A RocketRide tool node that gives an AI agent read/write access to the account-scoped RocketRide file store. ## What it does Exposes the account file store, the same storage area the client SDK reaches via its `fs_*` methods, to an agent as a set of callable tools. All paths are relative to `users//files/`, so files written by the agent are visible to the client SDK and vice versa. The account is resolved automatically from the `ROCKETRIDE_CLIENT_ID` env var injected by the task engine, no account configuration is needed on the node. If that env var is missing or the account store fails to initialise, a warning is logged and **all** tool methods are hidden from the agent. The node has no pipeline lanes: it is connected to agents via the `tool` invoke channel. Every operation is gated by a per-operation allow toggle. Read, write, list, mkdir, and stat are **on by default**; **delete is off by default**. Tools whose toggle is disabled are hidden from the agent at discovery time (`tool.query`), not just blocked at invocation. An optional regex path whitelist further restricts which paths any operation may touch. --- ## Configuration | Field | Type | Description | |---|---|---| | `allowRead` | boolean | Default true. | | `allowWrite` | boolean | Default true. | | `allowList` | boolean | Default true. | | `allowMkdir` | boolean | Default true. | | `allowStat` | boolean | Default true. | | `allowDelete` | boolean | Default false. Destructive, enable only when the agent is trusted to delete account files. | | `whitelistPattern` | string | Default empty. | | `pathWhitelist` | array | Regex patterns applied to the relative path of every operation using re.search semantics, a partial match anywhere in the path is enough, so a pattern like 'secret' will also match 'notsecret/file.txt'. Anchor with ^ and $ if you need a full-path match (e.g. '^docs/.*$'). If non-empty, a path must match at least one pattern. If empty, all paths under users//files/ are allowed. | ### Path whitelist If `pathWhitelist` is non-empty, the relative path of **every** operation must match at least one pattern. Patterns use `re.search` semantics, a partial match anywhere in the path is enough, so a pattern like `secret` will also match `notsecret/file.txt`. Anchor with `^` and `$` if you need a full-path match (e.g. `^docs/.*$`). Invalid regexes are skipped with a logged warning. An empty `path` on `list_directory` means the account root and bypasses the whitelist check (an empty string can't match a non-trivial regex). --- ## Available tools Each tool is namespaced by the node id: e.g. an agent sees `tool_filesystem_1.read_file`. Disabled tools are filtered out of discovery, and the allow-flag is re-checked at invocation as defence-in-depth. ### Read & inspect | Tool | Description | |---|---|---| | `read_file` | Read a file from the account file store and return its contents as a decoded string. Required: "path" (relative path). Optional: "encoding" (default "utf-8"), "maxBytes" (default 256 KB, max 4 MB). Returns: {path, content, size} where size is the byte length before decoding. Files larger than maxBytes are rejected. | | `write_file` | Write (or overwrite) a file in the account file store. Required: "path", "content". Optional: "encoding" (default "utf-8"). Returns: {path, bytesWritten}. | | `delete_file` | Delete a file from the account file store. Only available when the operator has enabled "allowDelete" on this node. Required: "path". Returns: {path, deleted: true}. | | `list_directory` | List the immediate children of a directory in the account file store. Optional: "path" (defaults to the account root). Returns: {entries: [{name, type, size?, modified?}], count}. | | `create_directory` | Create a directory in the account file store. Intermediate segments are created as needed. Required: "path". Returns: {path, created: true}. | | `stat_file` | Get metadata for a file or directory in the account file store. Required: "path". Returns: {exists, type?, size?, modified?}. | ### Write | Tool | Description | |--------------------|----------------------------------------------------------------------| | `write_file` | Create or overwrite a file with text content. Required: `path`, `content`. Optional: `encoding` (default `utf-8`). Returns `{path, bytesWritten}`. | | `create_directory` | Create a directory; intermediate segments are created as needed. Required: `path`. Returns `{path, created: true}`. | ### Delete | Tool | Description | |---------------|-----------------------------------------------------------------------------| | `delete_file` | Delete a file. Only available when `allowDelete` is enabled. Required: `path`. Returns `{path, deleted: true}`. | ### Read size cap `read_file` accepts `maxBytes` (default **256 KB**, hard ceiling **4 MB**). Files larger than the cap are **rejected with an error**, not truncated, use a smaller `maxBytes` for sampling, or split the file. The cap exists because the underlying store defaults to 100 MB per read, which could blow the agent's context window or OOM the engine subprocess long before the LLM ever sees the result. --- ## Storage location Files land under the configured storage backend (defaults to `~/.rocketlib/store/`). For the default filesystem backend the absolute path is: ```text /users//files/ ``` Each account gets its own isolated `files/` directory, the node picks up the current account automatically, no configuration needed. --- ## Running the tests ```bash pytest nodes/test/tool_filesystem/test_read_size_cap.py -v ``` --- ## Schema | Field | Type | Description | Default | |---|---|---|---| | `filesystem.allowDelete` | `boolean` | **Delete files**
Destructive: enable only when the agent is trusted to delete account files. | `false` | | `filesystem.allowList` | `boolean` | **List directories** | `true` | | `filesystem.allowMkdir` | `boolean` | **Create directories** | `true` | | `filesystem.allowRead` | `boolean` | **Read files** | `true` | | `filesystem.allowStat` | `boolean` | **Stat (metadata)** | `true` | | `filesystem.allowWrite` | `boolean` | **Write files** | `true` | | `filesystem.pathWhitelist` | `array` | **Path Whitelist**
Regex patterns applied to the relative path of every operation using re.search semantics: a partial match anywhere in the path is enough, so a pattern like 'secret' will also match 'notsecret/file.txt'. Anchor with ^ and $ if you need a full-path match (e.g. '^docs/.*$'). If non-empty, a path must match at least one pattern. If empty, all paths under users//files/ are allowed. | | | `filesystem.whitelistPattern` | `string` | **Path Pattern (regex)** | `""` | ## Source [ View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_filesystem)