BaseVFS. Define readdir, read and stat,
and ls, cat, grep, find, head, wc and the other read commands work
on the service. TypeScript names every method in camelCase (rm_r is rmR).
Write one
This VFS serves pages from a dictionary, which stands in for the service:- Python
- TypeScript
notes.py
- Python
- TypeScript
readdirreturns each child’sFileStatwithnameset to the base name. The mount keeps the listing and answers a laterstatfrom it, sols -lcosts one request.path.vfs_path(vfsPath) addresses the service andpath.virtualthe workspace path.- Set
FileStat.sizeto the length of the bytesreadreturns, or leave it unset when it is unknown. - Pass
nameandvfs_md(vfsMd) to the base constructor.vfs_mdis the mount’s layout in its VFS.md: atexttree, then a few notes, with{prefix}for the mount’s folder.
Add functions as the service grows
Every other function is optional. Define one, and the commands that need it start working; leave it out, and those commands answerOperation not supported.
Some commands fall back to simpler functions:
>> without append reads the
file and calls write, cp without copy reads and writes, rm -r without
rm_r removes entry by entry, and chmod without setattr keeps the mode in
Mirage. The mount mode still decides whether a write may run.
For example, write and unlink make the notes writable:
- Python
- TypeScript
echo hi > /notes/new.txt, sed -i and rm now work,
and >> reads the page and writes it back. mv still answers
Operation not supported until rename is defined.
Plug in the service’s search
files_containing and lines_containing hand Mirage the service’s own search.
grep and rg ask them which files or lines can hold the text and read only
those; they still match every line themselves, so the output is the same as a
full read. Returning None (null) reads every file.
- Python
- TypeScript
grep -rn mirage /notes now reads only the pages this returns. mounted_path
(mountedPath) turns a name inside the mount into a path. grep -ri gets
None here, so it reads every page.
- Answer more files than needed, never fewer: an extra file costs one read,
a missing one is a wrong answer. Return
Nonewhenever the answer may be incomplete, such as a truncated result or an index that lags writes. - A search that matches only whole words returns
Noneunlesswhole_wordis set, and setswhole_word_searchso the mount’s VFS.md tells the agent to usegrep -w.
files_containing asks Chroma
for the chunks whose text contains the word and returns their pages.
Search lists which patterns and flags reach these
functions.
A service action that is not a file, such as a search query or adding a
comment, belongs in a CLI, next to the mount.
Use it in YAML
A workspace YAML mounts the class by its file and name, relative to the YAML file;config is what its constructor gets:
workspace.yaml
./notes.ts:NotesVFS. To write vfs: notes
instead, register the class once:
- Python
- TypeScript
SDK guides
Python
Accessors, config, an Elasticsearch-backed S3 and runnable examples.
TypeScript
Accessors, config, an Elasticsearch-backed S3 and runnable examples.