@ai-sdk/harness-pi 0.0.0 → 1.0.0-beta.10

package/src/pi-workspace-mirror.ts

@@ -0,0 +1,276 @@
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+import { shellQuote } from './pi-utils';
+
+/*
+ * Pi runs on the host with its working directory pointed at the local mirror,
+ * but the only thing it reads from that directory is its own resource
+ * configuration: the `.pi` and `.agents` directories (skills, prompts, themes,
+ * extensions) and the root-level agent context files (`AGENTS.md`). The model
+ * never reads workspace source through the host — file reads, directory
+ * listings, and greps all run as tools against the sandbox. Mirroring the whole
+ * sandbox workspace to the host would therefore copy files Pi never looks at,
+ * one `readBinaryFile` round-trip per file. For a real project that has been
+ * cloned and had its dependencies installed (hundreds of thousands of files
+ * under `node_modules`) that makes session startup take hours. The mirror is
+ * consequently scoped to exactly the paths Pi's resource loader consults.
+ *
+ * Within those config directories, symlinks are resolved and their targets
+ * copied as real files. `.agents/skills` is frequently a symlink to a `skills`
+ * directory living elsewhere in the workspace; a mirrored symlink would dangle
+ * because its target falls outside the scoped mirror, so the linked content is
+ * walked and copied verbatim instead.
+ */
+const PI_CONFIG_DIRS = ['.pi', '.agents'] as const;
+const PI_CONTEXT_FILENAMES = ['AGENTS.md', 'AGENTS.MD'] as const;
+
+function normalizeRelativePath(inputPath: string): string {
+  const normalized = inputPath.split(path.posix.sep).join(path.sep);
+  const relative = path.normalize(normalized);
+  if (
+    relative === '' ||
+    relative === '.' ||
+    path.isAbsolute(relative) ||
+    relative === '..' ||
+    relative.startsWith(`..${path.sep}`)
+  ) {
+    throw new Error(
+      `Sandbox workspace mirror received an invalid relative path: ${inputPath}`,
+    );
+  }
+  return relative;
+}
+
+async function readCommandOutput(
+  sandbox: Experimental_SandboxSession,
+  command: string,
+): Promise<string> {
+  const result = await sandbox.run({ command });
+  const output = result.stdout || result.stderr;
+  if (result.exitCode != null && result.exitCode !== 0) {
+    throw new Error(
+      output || `Sandbox command failed with exit code ${result.exitCode}`,
+    );
+  }
+  return output;
+}
+
+async function listRemoteWorkspaceEntries(
+  sandbox: Experimental_SandboxSession,
+  sandboxWorkDir: string,
+): Promise<{ directories: string[]; files: string[] }> {
+  const contextPredicate = PI_CONTEXT_FILENAMES.map(
+    name => `-name ${shellQuote(name)}`,
+  ).join(' -o ');
+
+  // Enumerate only the `.pi`/`.agents` config subtrees plus the root-level
+  // context files — never the rest of the workspace. `find -L` dereferences
+  // symlinks so that linked targets (e.g. `.agents/skills` pointing elsewhere)
+  // are walked and reported through the symlinked path; the resolved file/dir
+  // types from `[ -d ]`/`[ -f ]` then tag each entry `d`/`f`, NUL-joined
+  // exactly like a full-tree walk so the reconcile below is unchanged.
+  const configFinds = PI_CONFIG_DIRS.map(
+    dir =>
+      `  if [ -d ./${dir} ]; then find -L ./${dir} \\( -type d -o -type f \\) -print0; fi;`,
+  );
+  const listCommand = [
+    '{',
+    ...configFinds,
+    `  find . -maxdepth 1 -type f \\( ${contextPredicate} \\) -print0;`,
+    '} |',
+    "while IFS= read -r -d '' entry; do",
+    '  rel=${entry#./}',
+    '  if [ -d "$entry" ]; then',
+    `    printf 'd\\t%s\\n' "$rel"`,
+    '  elif [ -f "$entry" ]; then',
+    `    printf 'f\\t%s\\n' "$rel"`,
+    '  fi',
+    'done | LC_ALL=C sort',
+  ].join('\n');
+
+  const output = await readCommandOutput(
+    sandbox,
+    [`cd ${shellQuote(sandboxWorkDir)}`, listCommand].join(' && '),
+  );
+
+  const directories: string[] = [];
+  const files: string[] = [];
+
+  for (const line of output.split('\n').filter(Boolean)) {
+    const [kind, rawPath] = line.split('\t', 2);
+    if (!rawPath) continue;
+
+    const relativePath = normalizeRelativePath(rawPath);
+    if (kind === 'd') directories.push(relativePath);
+    else if (kind === 'f') files.push(relativePath);
+  }
+
+  return { directories, files };
+}
+
+async function pathKind(
+  target: string,
+): Promise<'file' | 'directory' | undefined> {
+  try {
+    const stats = await stat(target);
+    if (stats.isDirectory()) return 'directory';
+    if (stats.isFile()) return 'file';
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function collectHostSubtree(
+  rootDir: string,
+  currentDir: string,
+  directories: string[],
+  files: string[],
+): Promise<void> {
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const absolutePath = path.join(currentDir, entry.name);
+    const relativePath = path.relative(rootDir, absolutePath);
+    if (entry.isDirectory()) {
+      directories.push(relativePath);
+      await collectHostSubtree(rootDir, absolutePath, directories, files);
+    } else if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+}
+
+/**
+ * Enumerate the locally-mirrored entries that fall within Pi's scope: the
+ * `.pi`/`.agents` config subtrees and the root-level context files. Anything
+ * else on the local side (it should not normally exist) is intentionally
+ * ignored so the reconcile below neither copies nor deletes it.
+ */
+async function collectHostScopedEntries(
+  rootDir: string,
+): Promise<{ directories: string[]; files: string[] }> {
+  const directories: string[] = [];
+  const files: string[] = [];
+
+  for (const dir of PI_CONFIG_DIRS) {
+    const configDir = path.join(rootDir, dir);
+    if ((await pathKind(configDir)) === 'directory') {
+      directories.push(dir);
+      await collectHostSubtree(rootDir, configDir, directories, files);
+    }
+  }
+
+  for (const name of PI_CONTEXT_FILENAMES) {
+    if ((await pathKind(path.join(rootDir, name))) === 'file') {
+      files.push(name);
+    }
+  }
+
+  return { directories, files };
+}
+
+function buildRequiredDirectories(
+  remoteDirectories: string[],
+  remoteFiles: string[],
+): Set<string> {
+  const directories = new Set<string>();
+  for (const directory of remoteDirectories) {
+    directories.add(normalizeRelativePath(directory));
+  }
+  for (const file of remoteFiles) {
+    let current = path.dirname(normalizeRelativePath(file));
+    while (current !== '.' && current !== path.sep && current.length > 0) {
+      directories.add(current);
+      current = path.dirname(current);
+    }
+  }
+  return directories;
+}
+
+export async function syncHostWorkspaceFromSandbox(args: {
+  sandbox: Experimental_SandboxSession;
+  sandboxWorkDir: string;
+  hostWorkDir: string;
+}): Promise<void> {
+  const { sandbox, sandboxWorkDir, hostWorkDir } = args;
+  const remoteEntries = await listRemoteWorkspaceEntries(
+    sandbox,
+    sandboxWorkDir,
+  );
+  const hostEntries = await collectHostScopedEntries(hostWorkDir);
+  const remoteFiles = new Set(remoteEntries.files);
+  const requiredDirectories = buildRequiredDirectories(
+    remoteEntries.directories,
+    remoteEntries.files,
+  );
+
+  for (const relativePath of hostEntries.files) {
+    if (!remoteFiles.has(relativePath)) {
+      await rm(path.join(hostWorkDir, relativePath), { force: true });
+    }
+  }
+
+  const removableDirectories = [...hostEntries.directories]
+    .filter(p => !requiredDirectories.has(p))
+    .sort((a, b) => b.length - a.length);
+  for (const relativePath of removableDirectories) {
+    await rm(path.join(hostWorkDir, relativePath), {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  for (const relativePath of [...requiredDirectories].sort(
+    (a, b) => a.length - b.length,
+  )) {
+    await mkdir(path.join(hostWorkDir, relativePath), { recursive: true });
+  }
+
+  for (const relativePath of remoteEntries.files) {
+    const remotePath = path.posix.join(
+      sandboxWorkDir,
+      relativePath.split(path.sep).join('/'),
+    );
+    const bytes = await sandbox.readBinaryFile({ path: remotePath });
+    if (!bytes) {
+      throw new Error(
+        `Sandbox workspace file disappeared during mirror sync: ${remotePath}`,
+      );
+    }
+    const content = Buffer.from(bytes);
+
+    const hostPath = path.join(hostWorkDir, relativePath);
+    let shouldWrite = true;
+    try {
+      const existing = await readFile(hostPath);
+      shouldWrite = !existing.equals(content);
+    } catch {
+      shouldWrite = true;
+    }
+
+    if (shouldWrite) {
+      await mkdir(path.dirname(hostPath), { recursive: true });
+      await writeFile(hostPath, content);
+    }
+  }
+}
+
+export async function writeHostWorkspaceFile(
+  hostWorkDir: string,
+  relativePath: string,
+  content: Buffer,
+): Promise<void> {
+  const normalizedPath = normalizeRelativePath(relativePath);
+  const hostPath = path.join(hostWorkDir, normalizedPath);
+  await mkdir(path.dirname(hostPath), { recursive: true });
+  await writeFile(hostPath, content);
+}

package/src/pi-workspace-vfs.ts

@@ -0,0 +1,437 @@
+/**
+ * Pi VFS — global Node `fs` monkey-patch that redirects reads/writes against a
+ * mount point (the session's sandbox working directory, e.g.
+ * `/vercel/sandbox/<harnessId>-<sessionId>/...`) to a real backing directory on
+ * the host. The mount point is a sandbox path that does not exist on the host,
+ * so the redirect never shadows real host files.
+ *
+ * The mapping is process-global because Pi's upstream runtime reads and
+ * writes through the shared `fs` module. Concurrent mounts are supported as
+ * long as each instance uses a distinct mount point (each session's sandbox
+ * working directory is unique).
+ *
+ * Multi-instance invariants:
+ * - Multiple `PiWorkspaceVfs` instances may stay mounted concurrently.
+ * - Path routing uses longest-prefix matching, so mount points must not
+ *   overlap.
+ * - Extra `fs` patches stay installed while `mountedRoots.size > 0` and are
+ *   restored only after the final unmount.
+ * - Mount and unmount remain synchronous, so Node's single-threaded execution
+ *   preserves patch/install ordering.
+ *
+ * Supported logical-path APIs:
+ * - Sync: `existsSync`, `readFileSync`, `writeFileSync`, `mkdirSync`,
+ *   `readdirSync`, `renameSync`, `rmSync`, `openSync`, `statSync`,
+ *   `realpathSync` (+ `.native`).
+ * - Callback: `mkdir`, `realpath`, `stat`, `rmdir`, `utimes`, `writeFile`.
+ * - Promises: `fs.promises.mkdir`, `fs.promises.readFile`,
+ *   `fs.promises.writeFile`.
+ *
+ * Anything else is intentionally unsupported. If Pi starts using additional
+ * `fs` APIs against logical roots, those call sites must be added here
+ * deliberately with tests.
+ */
+
+import fs from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
+import path from 'node:path';
+
+type MountedRoot = {
+  backingRoot: string;
+  mountPoint: string;
+};
+
+type WrappedRealpathSync = typeof fs.realpathSync & {
+  native?: typeof fs.realpathSync.native;
+};
+
+type Mutable<T> = {
+  -readonly [K in keyof T]: T[K];
+};
+
+const mountedRoots = new Map<string, MountedRoot>();
+const mutableFs = fs as Mutable<typeof fs>;
+const mutableFsPromises = fs.promises as Mutable<typeof fs.promises>;
+
+const originalFsSyncMethods = {
+  existsSync: fs.existsSync,
+  mkdirSync: fs.mkdirSync,
+  openSync: fs.openSync,
+  readFileSync: fs.readFileSync,
+  readdirSync: fs.readdirSync,
+  realpathSync: fs.realpathSync,
+  renameSync: fs.renameSync,
+  rmSync: fs.rmSync,
+  statSync: fs.statSync,
+  writeFileSync: fs.writeFileSync,
+};
+
+const originalFsCallbackMethods = {
+  mkdir: fs.mkdir,
+  realpath: fs.realpath,
+  rmdir: fs.rmdir,
+  stat: fs.stat,
+  utimes: fs.utimes,
+  writeFile: fs.writeFile,
+};
+
+const originalFsPromises = {
+  mkdir: fs.promises.mkdir.bind(fs.promises),
+  readFile: fs.promises.readFile.bind(fs.promises),
+  writeFile: fs.promises.writeFile.bind(fs.promises),
+};
+
+function isInsidePath(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return (
+    relative === '' ||
+    (!relative.startsWith('..') && !path.isAbsolute(relative))
+  );
+}
+
+function resolveAbsolutePath(inputPath: string): string {
+  return path.isAbsolute(inputPath)
+    ? path.normalize(inputPath)
+    : path.resolve(inputPath);
+}
+
+function findMountedRoot(inputPath: string): MountedRoot | undefined {
+  const resolvedPath = resolveAbsolutePath(inputPath);
+  let bestMatch: MountedRoot | undefined;
+
+  for (const mountedRoot of mountedRoots.values()) {
+    if (!isInsidePath(mountedRoot.mountPoint, resolvedPath)) {
+      continue;
+    }
+    if (
+      !bestMatch ||
+      mountedRoot.mountPoint.length > bestMatch.mountPoint.length
+    ) {
+      bestMatch = mountedRoot;
+    }
+  }
+
+  return bestMatch;
+}
+
+function mapToBackingPath(inputPath: string): string | null {
+  const mountedRoot = findMountedRoot(inputPath);
+  if (!mountedRoot) {
+    return null;
+  }
+
+  const resolvedPath = resolveAbsolutePath(inputPath);
+  const relativePath = path.relative(mountedRoot.mountPoint, resolvedPath);
+  return relativePath
+    ? path.join(mountedRoot.backingRoot, relativePath)
+    : mountedRoot.backingRoot;
+}
+
+function mapRealpathResult(inputPath: string, result: string): string {
+  const mountedRoot = findMountedRoot(inputPath);
+  if (!mountedRoot) {
+    return result;
+  }
+
+  let normalizedBackingRoot = path.resolve(mountedRoot.backingRoot);
+  try {
+    const realpath =
+      originalFsSyncMethods.realpathSync.native ??
+      originalFsSyncMethods.realpathSync;
+    normalizedBackingRoot = path.resolve(realpath(mountedRoot.backingRoot));
+  } catch {
+    // Fall back to the configured backing root when canonicalization fails.
+  }
+
+  const normalizedResult = path.resolve(result);
+  if (!isInsidePath(normalizedBackingRoot, normalizedResult)) {
+    return result;
+  }
+
+  const relativePath = path.relative(normalizedBackingRoot, normalizedResult);
+  return relativePath
+    ? path.join(mountedRoot.mountPoint, relativePath)
+    : mountedRoot.mountPoint;
+}
+
+function mapRenamePaths(
+  sourcePath: string,
+  destinationPath: string,
+): [string, string] | null {
+  const sourceRoot = findMountedRoot(sourcePath);
+  const destinationRoot = findMountedRoot(destinationPath);
+
+  if (!sourceRoot && !destinationRoot) {
+    return null;
+  }
+
+  if (
+    !sourceRoot ||
+    !destinationRoot ||
+    sourceRoot.mountPoint !== destinationRoot.mountPoint
+  ) {
+    throw new Error(
+      'Pi logical VFS paths cannot rename across mount boundaries',
+    );
+  }
+
+  return [
+    mapToBackingPath(sourcePath) ?? sourcePath,
+    mapToBackingPath(destinationPath) ?? destinationPath,
+  ];
+}
+
+function wrapSinglePathSync<Fn extends (...args: never[]) => unknown>(
+  original: Fn,
+  options: {
+    mapResult?: (inputPath: string, result: ReturnType<Fn>) => ReturnType<Fn>;
+  } = {},
+): Fn {
+  return ((...args: Parameters<Fn>) => {
+    const [inputPath] = args;
+    if (typeof inputPath === 'string') {
+      const mappedPath = mapToBackingPath(inputPath);
+      if (mappedPath) {
+        const result = original(
+          ...([mappedPath, ...args.slice(1)] as Parameters<Fn>),
+        ) as ReturnType<Fn>;
+        return options.mapResult
+          ? options.mapResult(inputPath, result)
+          : result;
+      }
+    }
+    return original(...args);
+  }) as Fn;
+}
+
+function wrapRenameSync<Fn extends (...args: never[]) => unknown>(
+  original: Fn,
+): Fn {
+  return ((...args: Parameters<Fn>) => {
+    const [sourcePath, destinationPath] = args;
+    if (typeof sourcePath === 'string' && typeof destinationPath === 'string') {
+      const mappedPaths = mapRenamePaths(sourcePath, destinationPath);
+      if (mappedPaths) {
+        return original(
+          ...([
+            mappedPaths[0],
+            mappedPaths[1],
+            ...args.slice(2),
+          ] as Parameters<Fn>),
+        );
+      }
+    }
+    return original(...args);
+  }) as Fn;
+}
+
+function wrapSinglePathCallback<Fn extends (...args: never[]) => unknown>(
+  original: Fn,
+  options: {
+    mapCallbackResult?: (inputPath: string, result: unknown) => unknown;
+  } = {},
+): Fn {
+  return ((...args: Parameters<Fn>) => {
+    const [inputPath] = args;
+    if (typeof inputPath === 'string') {
+      const mappedPath = mapToBackingPath(inputPath);
+      if (mappedPath) {
+        const nextArgs = [mappedPath, ...args.slice(1)] as unknown[];
+        const maybeCallback = nextArgs.at(-1);
+        if (options.mapCallbackResult && typeof maybeCallback === 'function') {
+          nextArgs[nextArgs.length - 1] = (
+            error: NodeJS.ErrnoException | null,
+            result: unknown,
+            ...rest: unknown[]
+          ) => {
+            const mappedResult = error
+              ? result
+              : options.mapCallbackResult?.(inputPath, result);
+            (maybeCallback as (...callbackArgs: unknown[]) => void)(
+              error,
+              mappedResult,
+              ...rest,
+            );
+          };
+        }
+        return original(...(nextArgs as Parameters<Fn>));
+      }
+    }
+    return original(...args);
+  }) as Fn;
+}
+
+function wrapSinglePathPromise<
+  Fn extends (...args: never[]) => Promise<unknown>,
+>(original: Fn): Fn {
+  return (async (...args: Parameters<Fn>) => {
+    const [inputPath] = args;
+    if (typeof inputPath === 'string') {
+      const mappedPath = mapToBackingPath(inputPath);
+      if (mappedPath) {
+        return await original(
+          ...([mappedPath, ...args.slice(1)] as Parameters<Fn>),
+        );
+      }
+    }
+    return await original(...args);
+  }) as Fn;
+}
+
+function createWrappedRealpathSync(): WrappedRealpathSync {
+  const wrapped = wrapSinglePathSync(originalFsSyncMethods.realpathSync, {
+    mapResult: (inputPath, result) =>
+      typeof result === 'string'
+        ? mapRealpathResult(inputPath, result)
+        : result,
+  }) as WrappedRealpathSync;
+
+  if (originalFsSyncMethods.realpathSync.native) {
+    wrapped.native = wrapSinglePathSync(
+      originalFsSyncMethods.realpathSync.native,
+      {
+        mapResult: (inputPath, result) =>
+          typeof result === 'string'
+            ? mapRealpathResult(inputPath, result)
+            : result,
+      },
+    ) as typeof fs.realpathSync.native;
+  }
+
+  return wrapped;
+}
+
+const wrappedFsSyncMethods = {
+  existsSync: wrapSinglePathSync(originalFsSyncMethods.existsSync),
+  mkdirSync: wrapSinglePathSync(originalFsSyncMethods.mkdirSync),
+  openSync: wrapSinglePathSync(originalFsSyncMethods.openSync),
+  readFileSync: wrapSinglePathSync(originalFsSyncMethods.readFileSync),
+  readdirSync: wrapSinglePathSync(originalFsSyncMethods.readdirSync),
+  realpathSync: createWrappedRealpathSync(),
+  renameSync: wrapRenameSync(originalFsSyncMethods.renameSync),
+  rmSync: wrapSinglePathSync(originalFsSyncMethods.rmSync),
+  statSync: wrapSinglePathSync(originalFsSyncMethods.statSync),
+  writeFileSync: wrapSinglePathSync(originalFsSyncMethods.writeFileSync),
+};
+
+const wrappedFsCallbackMethods = {
+  mkdir: wrapSinglePathCallback(originalFsCallbackMethods.mkdir),
+  realpath: wrapSinglePathCallback(originalFsCallbackMethods.realpath, {
+    mapCallbackResult: (inputPath, result) =>
+      typeof result === 'string'
+        ? mapRealpathResult(inputPath, result)
+        : result,
+  }),
+  rmdir: wrapSinglePathCallback(originalFsCallbackMethods.rmdir),
+  stat: wrapSinglePathCallback(originalFsCallbackMethods.stat),
+  utimes: wrapSinglePathCallback(originalFsCallbackMethods.utimes),
+  writeFile: wrapSinglePathCallback(originalFsCallbackMethods.writeFile),
+};
+
+const wrappedFsPromises = {
+  mkdir: wrapSinglePathPromise(originalFsPromises.mkdir),
+  readFile: wrapSinglePathPromise(originalFsPromises.readFile),
+  writeFile: wrapSinglePathPromise(originalFsPromises.writeFile),
+};
+
+function areExtraFsPatchesInstalled(): boolean {
+  return mutableFs.existsSync === wrappedFsSyncMethods.existsSync;
+}
+
+function installExtraFsPatches() {
+  if (areExtraFsPatchesInstalled()) return;
+
+  mutableFs.existsSync = wrappedFsSyncMethods.existsSync;
+  mutableFs.mkdirSync = wrappedFsSyncMethods.mkdirSync;
+  mutableFs.openSync = wrappedFsSyncMethods.openSync;
+  mutableFs.readFileSync = wrappedFsSyncMethods.readFileSync;
+  mutableFs.readdirSync = wrappedFsSyncMethods.readdirSync;
+  mutableFs.realpathSync = wrappedFsSyncMethods.realpathSync;
+  mutableFs.renameSync = wrappedFsSyncMethods.renameSync;
+  mutableFs.rmSync = wrappedFsSyncMethods.rmSync;
+  mutableFs.statSync = wrappedFsSyncMethods.statSync;
+  mutableFs.writeFileSync = wrappedFsSyncMethods.writeFileSync;
+
+  mutableFs.mkdir = wrappedFsCallbackMethods.mkdir;
+  mutableFs.realpath = wrappedFsCallbackMethods.realpath;
+  mutableFs.rmdir = wrappedFsCallbackMethods.rmdir;
+  mutableFs.stat = wrappedFsCallbackMethods.stat;
+  mutableFs.utimes = wrappedFsCallbackMethods.utimes;
+  mutableFs.writeFile = wrappedFsCallbackMethods.writeFile;
+
+  mutableFsPromises.mkdir = wrappedFsPromises.mkdir;
+  mutableFsPromises.readFile = wrappedFsPromises.readFile;
+  mutableFsPromises.writeFile = wrappedFsPromises.writeFile;
+
+  syncBuiltinESMExports();
+}
+
+function restoreExtraFsPatches() {
+  if (!areExtraFsPatchesInstalled()) return;
+
+  mutableFs.existsSync = originalFsSyncMethods.existsSync;
+  mutableFs.mkdirSync = originalFsSyncMethods.mkdirSync;
+  mutableFs.openSync = originalFsSyncMethods.openSync;
+  mutableFs.readFileSync = originalFsSyncMethods.readFileSync;
+  mutableFs.readdirSync = originalFsSyncMethods.readdirSync;
+  mutableFs.realpathSync = originalFsSyncMethods.realpathSync;
+  mutableFs.renameSync = originalFsSyncMethods.renameSync;
+  mutableFs.rmSync = originalFsSyncMethods.rmSync;
+  mutableFs.statSync = originalFsSyncMethods.statSync;
+  mutableFs.writeFileSync = originalFsSyncMethods.writeFileSync;
+
+  mutableFs.mkdir = originalFsCallbackMethods.mkdir;
+  mutableFs.realpath = originalFsCallbackMethods.realpath;
+  mutableFs.rmdir = originalFsCallbackMethods.rmdir;
+  mutableFs.stat = originalFsCallbackMethods.stat;
+  mutableFs.utimes = originalFsCallbackMethods.utimes;
+  mutableFs.writeFile = originalFsCallbackMethods.writeFile;
+
+  mutableFsPromises.mkdir = originalFsPromises.mkdir;
+  mutableFsPromises.readFile = originalFsPromises.readFile;
+  mutableFsPromises.writeFile = originalFsPromises.writeFile;
+
+  syncBuiltinESMExports();
+}
+
+export class PiWorkspaceVfs {
+  private backingRoot: string | null = null;
+  private mountPoint: string | null = null;
+
+  private disposeMount(): void {
+    if (this.mountPoint) {
+      mountedRoots.delete(this.mountPoint);
+    }
+    this.backingRoot = null;
+    this.mountPoint = null;
+  }
+
+  mount(backingRoot: string, mountPoint: string): void {
+    if (this.backingRoot === backingRoot && this.mountPoint === mountPoint) {
+      return;
+    }
+
+    const resolvedBackingRoot = path.resolve(backingRoot);
+    const resolvedMountPoint = path.resolve(mountPoint);
+    if (this.mountPoint) {
+      this.disposeMount();
+    }
+
+    mountedRoots.set(resolvedMountPoint, {
+      backingRoot: resolvedBackingRoot,
+      mountPoint: resolvedMountPoint,
+    });
+    installExtraFsPatches();
+
+    this.backingRoot = resolvedBackingRoot;
+    this.mountPoint = resolvedMountPoint;
+  }
+
+  unmount(): void {
+    this.disposeMount();
+
+    if (mountedRoots.size === 0) {
+      restoreExtraFsPatches();
+    }
+  }
+}