Filesystem API
Filesystem constructors, bridge adapters, and types for connect-time handles plus kernel I/O.
Runtime supports Node.js, browser, memory, confined fs-compatible, and cross-worker bridge filesystems.
Filesystem Types
Prop
Type
Prop
Type
Prop
Type
Prop
Type
Kernel I/O methods use the shared entry and event types: FileEntry, FileStat, FileStatEntry, FileTreeEntry, and FileStatus describe listings and stats; watch callbacks receive ChangeEvent values carrying a ChangeEventStat. isRuntimeFileSystem guards an opaque handle; isNotFoundError classifies read failures; runtimeFileSystemSchema is the Zod validator for the kernel-facing method surface.
Constructors
| Function | Import Path | Description |
|---|---|---|
fromNodeFs(basePath) | @taucad/runtime/filesystem/node | Node.js filesystem rooted at basePath |
fromBrowserFs(root) | @taucad/runtime/filesystem/browser | Browser directory handle used as the runtime root |
fromMemoryFs(files?) | @taucad/runtime/filesystem | In-memory Map-backed filesystem, optionally seeded |
fromFsLike(fs) | @taucad/runtime/filesystem | An already-confined virtual filesystem |
fromFileSystemBridge(open) | @taucad/runtime/filesystem | A fresh rooted bridge connection for each runtime binding |
Every constructor establishes the root of the runtime-path namespace. Filesystem method arguments are root-relative, so main.ts refers to a file beneath the supplied root and '' refers to the root itself.
Bridge Types
Prop
Type
Prop
Type
Prop
Type
fromFileSystemBridge returns a FileSystemBridgeConnection; BridgePort and BridgeServerHandle support host adapters.
Bridge Utilities
For cross-worker filesystem access, @taucad/runtime/filesystem provides the filesystem-specific authority boundary:
| Function | Description |
|---|---|
exposeFileSystem(handlers, options?) | Listen in the filesystem-owning worker; expose an authority as workspaceBridgeService(service). |
openFileSystemBridge(worker, options?) | Open a fresh scoped connection for fromFileSystemBridge; use this for runtime transport wiring. |
createFileSystemBridge(worker, options?) | Open a managed filesystem bridge when the current isolate also needs to call filesystem methods. |
createFileSystemBridgeProxy(bridge) | Create the validated filesystem proxy from the managed bridge returned by createFileSystemBridge. |
Bridge Usage
Trusted host code selects an authority route once and supplies a connection factory. The runtime sees only the rooted project's writable local namespace:
import { fromFileSystemBridge, openFileSystemBridge } from '@taucad/runtime/filesystem';
const fileManagerWorker = new Worker(new URL('./file-manager.worker.ts', import.meta.url), { type: 'module' });
const fileSystem = fromFileSystemBridge(() =>
openFileSystemBridge(fileManagerWorker, { root: '/projects/widget', consumer: 'agent' }),
);A root always names the surface it serves. There is no default: an absent or unknown consumer is refused, and the connection answers ROOT_UNAVAILABLE.
consumer | Surface |
|---|---|
'working-copy' | The checkout's own files, with no overlays composed above them. Trusted host composition only. |
'user' | What a person sees in the file tree: host-written records included, the control plane hidden. |
'agent' | What an agent sees: records readable but not writable, the control plane hidden. A runtime that renders agent-authored code names this one too. |
Inside runtime, main.ts, .tau/cache/**, and node_modules/** all belong to that rooted capability. The runtime receives no project id or authority-global root and performs no authorization checks; filesystem reachability is the authority boundary. fromFsLike(fs) follows the same local-path contract but assumes fs is already confined. Use fromNodeFs(hostRoot) for raw Node.js access so the adapter can enforce lexical and symlink containment.