packages/fs
September 4, 2026 · View on GitHub
English | 中文
Summary
The fs/ group gives agents durable, policy-governed access to files: the ctx.fs service contract in fs/, the host-filesystem and sandbox-enforcing backends in fs-local/ and fs-sandbox/, the read-before-edit policy in fs-observation-policy/, and the model-facing tools in tool-fs/ (read, read_image, write, edit) and tool-fs-search/ (glob, grep). A deployment mounts one backend, loads the policy for freshness-guarded mutations, and registers the tool packages the model should see; backends swap without touching the tools or the policy. File I/O takes no timeout by design: a deadline would kill work the OS still finishes, so cancellation is a best-effort signal at syscall boundaries.
Table of Contents
Packages
Seven packages plus the remote sibling fs-e2b play the filesystem roles; the subsystem reference owns the exhaustive contracts and the error taxonomy.
| Package | Role | ctx key |
|---|---|---|
fs/ | ctx.fs service contract: execution-world paths, bounded text I/O, and atomic mutations with an optional version guard | ctx.fs |
fs-local/ | Host-filesystem backend: reads, writes, and edits real files on the local machine | registers on ctx.fs |
fs-sandbox/ | Sandbox-enforcing backend: fences writes and edits by the per-call sandbox mode while reads pass through | registers on ctx.fs |
e2b/fs-e2b | E2B-backed backend: file state lives in the remote execution world shared with the E2B subprocess provider | registers on ctx.fs |
fs-observation-policy/ | Read-before-edit policy: records observed presence or absence and guards write/edit through the fs/* events | fs/* listeners |
tool-fs/ | Model-facing read, read_image, write, and edit tools plus their executor | registers on ctx.tools |
tool-fs-search/ | Model-facing glob and grep discovery tools backed by the packaged ripgrep binary | registers on ctx.tools |
tool-str-replace-editor/ | Standalone str_replace_editor tool: view, create, str_replace, and insert over ctx.fs | registers on ctx.tools |
The policy is a plugin, not a service the tools inject: removing it leaves the bare provider's unconditional mutation behavior instead of breaking the tools. The mode fence in fs-sandbox and the read-before-edit gate compose. tool-fs-search deliberately does not extend the provider contract — search is a process-backed ripgrep workflow, so filesystem backends stay free of a universal search API.
Related documentation
Start with the subsystem reference for the shared vocabulary and error taxonomy, then the decisions that shaped the family.
- Filesystem subsystem — targets, outcomes, guards, policy events, and the error taxonomy.
- Cross-family fs sandbox decision — the shared sandbox mode fence over the filesystem seam.
- Portable execution world consumers decision — why the E2B backend shares the remote execution world.
Dev Note
Working context for maintainers — click to expand
None.