Virtual Filesystem for Agents

Builder procedure

Core idea

Expose a single namespace of paths. Agents should not need to know whether a path is a local file, a synthesized JSON view, or a remote object.

Minimal API (MUST-level capabilities)

Implement at least:

stat(path) -> { type: file|dir|missing, size?, mtime? }
list(path) -> entries[]
read(path) -> bytes|text
write(path, bytes|text, { mode: create|overwrite|append })
mkdir(path)
remove(path)   # optional; prefer policy-gated

Optional but valuable:

grep(root, pattern) -> matches[]
watch(path) -> events   # for long-running agents

Path rules (SHOULD)

• Use forward-slash logical paths (/workspace/draft.md)
• Normalize . / ..; reject escapes outside the allowed root
• Keep paths stable across sessions when possible
• Document which prefixes are durable vs ephemeral

Virtual files (MAY)

A path need not map 1:1 to disk:

The agent still uses read / write. The backend performs translation.

Consistency model (SHOULD document)

Tell agents (in FILESYSTEM.md / TOOLS.md) what to expect:

• Read-after-write visibility
• Append vs overwrite semantics
• Whether deletes are allowed
• Whether directories are real or prefix illusions

Checklist

• Path normalization + jail
• Explicit file/dir types
• Text/write/list work for UTF-8 markdown
• Append mode for logs
• Error strings that agents can parse (not found, permission denied)

Human notes

Virtual FS is the hinge between agent cognition (paths) and storage reality (DB/S3/disk). Prefer a small, boring API over a clever one. See also Composite backend and Infrastructure mounts.