Filesystem

Filesystem

Edge adaptation of the upstream file operations subsystem.

Upstream reference: Filesystem

What Upstream Provides

The filesystem subsystem gives the model safe, guarded file operations through four packages:

• dsh-fs — abstract FileSystem service (ctx.fs) defining resolve, stat, lstat, readText, streamText, writeText, editText, readBytes, listDir.
• dsh-fs-local — local disk backend using node:fs.
• dsh-tool-fs — registers four model-facing tools: read, write, edit, read_image.
• dsh-sandbox — enforces writable-root policies and path canonicalization.

Write guards (createIfAbsent, replaceIfVersion) prevent stale overwrites. Edit is atomic literal-replacement with match validation. Error codes (FS_STALE_VERSION, FS_NOT_FOUND, FS_IO_ERROR, etc.) are stable and programmatic.

What Edge Changed

Replacement EdgeFileSystem → Cloudflare Computer VFS

EdgeFileSystem (309 lines) extends the upstream abstract FileSystem class. Every method delegates to the Cloudflare Computer VFS API (vfs.readFile, vfs.writeFile, vfs.stat, vfs.mkdir, vfs.readdir). Key adaptations:

• AsyncLocalStorage for turn-scoped VFS bindings — each active turn gets its own {vfs, cwd} pair via runInScope(), so concurrent sessions on the same DO never cross-contaminate.
• readText calls stat after read to get the real mtime:size version token, matching upstream's freshness guard contract.
• streamText returns a single-yield async iterable — VFS has no streaming API, so the entire content is read then yielded once.
• writeText creates parent directories via vfs.mkdir(parentDir, { recursive: true }) before writing, since VFS paths may not exist yet.
• stat/lstat return undefined for ENOENT; other errors propagate as FS_IO_ERROR.

Direct Reuse ToolFs

dsh-tool-fs installed as-is. The four model tools (read, write, edit, read_image) use ctx.fs which resolves to EdgeFileSystem. Tool schemas, guard logic, diff output formatting, and line-number display are upstream.

Patch dsh-sandbox

The sandbox patch removes two Node.js imports:

• node:fs realpathSync → canonicalPath() returns the path directly (VFS has no symlinks).
• node:os tmpdir() → writableRoots omits the OS temp directory.

Removal condition: upstream provides a VFS-compatible sandbox or removes the Node.js imports.

What Edge Did NOT Change

• Tool definitions and parameter schemas (read/write/edit/read_image)
• Write guard semantics (createIfAbsent, replaceIfVersion)
• Edit atomicity and match validation
• Error codes and their stable classification
• Observation policy events (fs/write-intent, fs/edit-intent, fs/observed)

Performance Characteristics

VFS I/O

All file operations go through Cloudflare Computer's VFS, which is an in-memory filesystem scoped to the workspace container. Reads and writes are fast (no disk I/O in the traditional sense) but bounded by the container's memory allocation. Large files may hit VFS memory limits before the upstream FS_TOO_LARGE byte cap.

AsyncLocalStorage overhead

AsyncLocalStorage.run() is a V8 native with negligible overhead per call — well under 1 microsecond. It's invoked once per turn (in runInScope()), not per file operation. Within a turn, getStore() is a single context lookup.

Concurrent session safety

Each turn's VFS binding is scoped via AsyncLocalStorage, so two sessions sharing the same DO can run file operations concurrently without cross-contamination. Previously a global activeBinding variable was used, which caused wrong-VFS bugs under interleaved async turns — replaced in 0.7.0-alpha.1.

Version token accuracy

readText calls vfs.stat() after reading the file to get the real mtime:size pair. This ensures the version token matches the actual file state, preventing false FS_STALE_VERSION errors on subsequent edits. The extra stat call adds one VFS round-trip per read.

Architecture Summary

Component	Category	Edge Code
EdgeFileSystem	Replace	309 lines — VFS delegation + AsyncLocalStorage
ToolFs (read/write/edit/read_image)	Reuse	One ctx.plugin() call
dsh-sandbox patch	Patch	Removes node:fs + node:os imports

Key observation: EdgeFileSystem is a textbook capability-seam replacement — upstream defines the abstract FileSystem class, Edge provides the platform-specific backend. The tool layer and guard logic run entirely upstream code. The only patch is on the sandbox (Node.js imports), not on the filesystem itself.