@dbx-tools/appkit-mastra 0.6.8 → 0.6.10

package/src/filesystems.ts

@@ -1,22 +1,21 @@
 /**
- * Mastra {@link WorkspaceFilesystem} implementations for Databricks Apps.
+ * Mastra workspace filesystem adapters.
  *
- * {@link DatabricksWorkspaceFilesystem} maps a Mastra workspace namespace onto
- * an absolute Databricks path (Unity Catalog volume, workspace object tree, or
- * DBFS). {@link emptyFilesystem} is a read-only no-op mount used when no
- * dynamic mounts resolve for a request.
- *
- * Path helpers ({@link normalizeDatabricksBasePath}, {@link isDbfsPath}, …)
- * are exported for tests and callers that need to reason about Databricks
- * paths without constructing a filesystem.
+ * {@link filesystems} wraps any portable `@dbx-tools/shared-fs` {@link FileSystem}
+ * (local disk, Databricks, memory, …) as a Mastra {@link MastraFilesystem}.
+ * {@link scratchFilesystem} always returns a fresh {@link localFS.tmpFS} mount
+ * (random id root) when Mastra needs a filesystem and no other mount resolved.
  *
  * @module
  */
 
-import { posix as path } from "node:path";
-import { ExecutionError, getExecutionContext, ValidationError } from "@databricks/appkit";
-import { WorkspaceClient } from "@databricks/sdk-experimental";
-import { error, functionModule, hash, log } from "@dbx-tools/shared-core";
+import { localFS } from "@dbx-tools/fs";
+import { FileSystemError, posixPath } from "@dbx-tools/shared-fs";
+import type {
+  FileEntry as SharedFileEntry,
+  FileStat as SharedFileStat,
+  FileSystem,
+} from "@dbx-tools/shared-fs";
 import {
   DirectoryNotEmptyError,
   DirectoryNotFoundError,
@@ -42,1063 +41,319 @@ import type {
   WriteOptions,
 } from "@mastra/core/workspace";
 
-/* ------------------------------ constants ------------------------------ */
-
-const DBFS_READ_CHUNK_BYTES = 1024 * 1024;
-const DBFS_PUT_MAX_BYTES = 1024 * 1024;
-const EMPTY_FILESYSTEM_EPOCH = new Date(0);
-
-/** Mastra error constructor for a known SDK filesystem failure, if any. */
-function filesystemSdkErrorType(err: unknown): (new (path: string) => Error) | undefined {
-  if (err) {
-    const ctx = error.errorContext(err);
-    if (ctx.notAccessible) {
-      return FileNotFoundError;
-    } else if (ctx.hasMessage("already", "exists")) {
-      return FileExistsError;
-    } else if (ctx.hasMessage("not", "directory")) {
-      return NotDirectoryError;
-    } else if (ctx.hasMessage("not", "file")) {
-      return IsDirectoryError;
-    }
-  }
-  return undefined;
-}
-
-const logger = log.logger("mastra/filesystems");
+/** Options for {@link filesystems} / {@link MastraFileSystemAdapter}. */
+export interface MastraFileSystemAdapterOptions extends MastraFilesystemOptions {
+  /** Override the Mastra filesystem id. Defaults to the source {@link FileSystem.id}. */
+  id?: string;
 
-/** How {@link DatabricksWorkspaceFilesystem.init} handles a missing {@link basePath}. */
-export type DatabricksMkdirsMode = boolean | "try";
+  /** Override the Mastra display name. Defaults to `MastraFileSystemAdapter`. */
+  name?: string;
 
-/** Options for {@link DatabricksWorkspaceFilesystem}. */
-export interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOptions {
-  /** Unique identifier for this filesystem instance. */
-  id?: string;
-  /** Auth-scoped Databricks workspace client. */
-  client?: WorkspaceClient;
   /**
-   * Absolute Databricks path that roots the workspace namespace, e.g.
-   * `/Volumes/catalog/schema/volume` or `/dbfs/FileStore/shared`.
+   * Override the Mastra provider id. Defaults to the source
+   * {@link FileSystem.backend}.
    */
-  basePath: string;
+  provider?: string;
+
   /**
-   * When the {@link basePath} is missing at {@link init}, create it with the
-   * matching Databricks `mkdirs` API. `"try"` (default) logs at debug and
-   * falls back to an empty read-only namespace on failure; `true` fails init;
-   * `false` skips creation and uses the empty namespace.
-   *
-   * A successful mkdir also satisfies the write-access probe when
-   * {@link readOnly} is omitted.
+   * Force read-only mounts even when the source filesystem allows writes.
+   * The source {@link FileSystem.readOnly} flag still applies either way.
    */
-  mkdirs?: DatabricksMkdirsMode;
-  /** Block writes while still allowing reads. When omitted, {@link init} probes write access. */
   readOnly?: boolean;
 }
 
-/* ------------------------- exported path helpers ------------------------- */
-
-/** Normalize a Databricks base path (POSIX, no trailing slash). */
-export function normalizeDatabricksBasePath(basePath: string): string {
-  const trimmed = basePath.trim();
-  if (!trimmed.startsWith("/")) {
-    throw ValidationError.invalidValue(
-      "basePath",
-      basePath,
-      "an absolute Databricks path, e.g. /Volumes/catalog/schema/volume",
-    );
-  }
-  return trimmed.replace(/\/+$/, "") || "/";
-}
-
-/** True when `absolutePath` is served by DBFS rather than the UC Files API. */
-export function isDbfsPath(absolutePath: string): boolean {
-  return absolutePath === "/dbfs" || absolutePath.startsWith("/dbfs/");
-}
-
-/** True when `absolutePath` is a Databricks workspace object path. */
-export function isWorkspaceFilesPath(absolutePath: string): boolean {
-  return (
-    absolutePath === "/Workspace" ||
-    absolutePath.startsWith("/Workspace/") ||
-    absolutePath.startsWith("/Users/") ||
-    absolutePath.startsWith("/Repos/")
-  );
-}
-
-type FilesBackend = "dbfs" | "workspace" | "uc-files";
-
-/** Per-backend async handler used by {@link dispatchFilesBackend}. */
-type FilesBackendHandlers<T = unknown> = {
-  dbfs: () => Promise<T>;
-  workspace: () => Promise<T>;
-  ucFiles: () => Promise<T>;
-};
-
 /**
- * Resolve a workspace-relative path to an absolute Databricks path under
- * `basePath`.
+ * Wrap a portable {@link FileSystem} as a Mastra {@link MastraFilesystem}.
+ *
+ * @example
+ * ```ts
+ * import { filesystems } from "@dbx-tools/appkit-mastra";
+ * import { DatabricksFileSystem } from "@dbx-tools/databricks";
+ * import { localFS } from "@dbx-tools/fs";
+ *
+ * const volume = filesystems.filesystems(
+ *   new DatabricksFileSystem({ root: "/Volumes/main/default/assets" }),
+ * );
+ * const scratch = filesystems.filesystems(localFS.tmpFS("agent-job"));
+ * ```
  */
-export function resolveDatabricksAbsolutePath(basePath: string, inputPath: string): string {
-  const root = normalizeDatabricksBasePath(basePath);
-  const trimmed = inputPath.trim();
-  if (!trimmed || trimmed === "/") return root;
-  const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  if (normalized === root || normalized.startsWith(`${root}/`)) {
-    return path.normalize(normalized);
-  }
-  return path.normalize(path.join(root, normalized));
-}
-
-/** Map an absolute Databricks path back to the workspace namespace. */
-export function toDatabricksWorkspacePath(basePath: string, absolutePath: string): string {
-  const root = normalizeDatabricksBasePath(basePath);
-  const normalized = path.normalize(absolutePath);
-  if (normalized === root) return "/";
-  if (normalized.startsWith(`${root}/`)) {
-    return normalized.slice(root.length) || "/";
-  }
-  return normalized;
+export function filesystems(
+  fs: FileSystem,
+  options: MastraFileSystemAdapterOptions = {},
+): MastraFileSystemAdapter {
+  return new MastraFileSystemAdapter(fs, options);
 }
 
-/* ---------------------------- private helpers ---------------------------- */
-
-/** Pick the Databricks Files API backend for an absolute path. */
-function resolveFilesBackend(absolutePath: string): FilesBackend {
-  if (isDbfsPath(absolutePath)) return "dbfs";
-  if (isWorkspaceFilesPath(absolutePath)) return "workspace";
-  return "uc-files";
-}
-
-/** Run the handler that matches `absolutePath`'s Databricks backend. */
-async function dispatchFilesBackend<T>(
-  absolutePath: string,
-  handlers: FilesBackendHandlers<T>,
-): Promise<T> {
-  const backend = resolveFilesBackend(absolutePath);
-  if (backend === "dbfs") return handlers.dbfs();
-  if (backend === "workspace") return handlers.workspace();
-  return handlers.ucFiles();
-}
-
-/** Return `buffer` as a string when `encoding` is set, otherwise unchanged. */
-function formatReadResult(buffer: Buffer, encoding?: BufferEncoding): string | Buffer {
-  return encoding ? buffer.toString(encoding) : buffer;
-}
-
-/** Drain a fetch `ReadableStream` into a single `Buffer`. */
-async function readResponseBody(
-  contents: globalThis.ReadableStream<Uint8Array> | undefined,
-): Promise<Buffer> {
-  if (!contents) return Buffer.alloc(0);
-  const reader = contents.getReader();
-  const chunks: Uint8Array[] = [];
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value) chunks.push(value);
-  }
-  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
-}
-
-/** Coerce Mastra {@link FileContent} to a `Buffer`. */
-function toBuffer(content: FileContent): Buffer {
-  if (typeof content === "string") return Buffer.from(content, "utf8");
-  return Buffer.from(content);
-}
-
-/** Decode a DBFS read payload from base64. */
-function decodeDbfsPayload(data: string | undefined): Buffer {
-  if (!data) return Buffer.alloc(0);
-  return Buffer.from(data, "base64");
-}
-
-/** Wrap a `Buffer` as a one-shot `ReadableStream` for UC file uploads. */
-function bufferToReadableStream(buffer: Buffer): globalThis.ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(new Uint8Array(buffer));
-      controller.close();
-    },
-  });
-}
-
-/** Parse an HTTP date header; returns epoch when missing or invalid. */
-function parseHttpDate(value: string | undefined): Date {
-  if (!value) return new Date(0);
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? new Date(parsed) : new Date(0);
-}
-
-/* ---------------- DatabricksWorkspaceFilesystem ---------------- */
-
 /**
- * Mastra filesystem provider that reads and writes through a Databricks
- * {@link WorkspaceClient}.
- *
- * Workspace paths are absolute within the namespace (`/notes.md` maps to
- * `<basePath>/notes.md`). Unity Catalog volumes use the Files API;
- * `/dbfs/...` paths use DBFS.
+ * Thin Mastra {@link MastraFilesystem} adapter over a `@dbx-tools/shared-fs`
+ * {@link FileSystem}. Identity fields are getters that read the source on
+ * access; construction does not snapshot them.
  */
-export class DatabricksWorkspaceFilesystem extends MastraFilesystem {
-  readonly id: string;
-  readonly name = "DatabricksWorkspaceFilesystem";
-  readonly provider = "databricks";
-  readonly basePath: string;
+export class MastraFileSystemAdapter extends MastraFilesystem {
   status: ProviderStatus = "pending";
 
-  private readonly client: WorkspaceClient;
-  private readonly mkdirs: DatabricksMkdirsMode;
-  private _readOnly: boolean | undefined;
-  private _basePathMissing: boolean | undefined;
-
-  get readOnly(): boolean | undefined {
-    return this._readOnly;
-  }
-
-  /**
-   * @param options.client - Defaults to the AppKit execution-context client.
-   * @param options.mkdirs - Default `"try"`; see {@link DatabricksMkdirsMode}.
-   * @param options.readOnly - When omitted, {@link init} probes write access.
-   */
-  constructor(options: DatabricksWorkspaceFilesystemOptions) {
-    super({ name: "DatabricksWorkspaceFilesystem", ...options });
-    this.id = options.id ?? `databricks-fs-${hash.fnvHash(options.basePath)}`;
-    this.client = options.client ?? getExecutionContext().client;
-    this.basePath = normalizeDatabricksBasePath(options.basePath);
-    this.mkdirs = options.mkdirs ?? "try";
-    this._readOnly = options.readOnly;
-  }
+  private readonly fs: FileSystem;
+  private readonly options: MastraFileSystemAdapterOptions;
 
-  /* --- path resolution --- */
-
-  /** Resolve and sandbox a workspace-relative path under {@link basePath}. */
-  private resolvePath(inputPath: string): string {
-    const resolved = resolveDatabricksAbsolutePath(this.basePath, inputPath);
-    if (resolved !== this.basePath && !resolved.startsWith(`${this.basePath}/`)) {
-      throw new PermissionError(inputPath, "access");
-    }
-    return resolved;
+  constructor(fs: FileSystem, options: MastraFileSystemAdapterOptions = {}) {
+    super({
+      name: options.name ?? "MastraFileSystemAdapter",
+      onInit: options.onInit,
+      onDestroy: options.onDestroy,
+    });
+    this.fs = fs;
+    this.options = options;
   }
 
-  /** Map a Databricks absolute path back to the workspace namespace. */
-  private workspacePath(absolutePath: string): string {
-    return toDatabricksWorkspacePath(this.basePath, absolutePath);
+  get id(): string {
+    return this.options.id ?? this.fs.id;
   }
 
-  /** Throw when the filesystem is read-only. */
-  private assertWritable(operation: string): void {
-    if (this.readOnly) {
-      throw new WorkspaceReadOnlyError(operation);
-    }
+  get name(): string {
+    return this.options.name ?? "MastraFileSystemAdapter";
   }
 
-  /** Map SDK / HTTP errors to Mastra workspace filesystem errors. */
-  private rethrow(err: unknown, inputPath: string): never {
-    const workspacePath = inputPath.startsWith("/")
-      ? inputPath
-      : this.workspacePath(this.resolvePath(inputPath));
-    const ErrorType = filesystemSdkErrorType(err);
-    if (ErrorType) {
-      throw new ErrorType(workspacePath);
-    }
-    // The upstream message is logged rather than raised: it reaches the model
-    // (and from there the chat transcript) as the tool's failure text.
-    logger.warn("operation-failed", {
-      path: workspacePath,
-      error: error.errorMessage(err),
-    });
-    throw new ExecutionError(`Databricks filesystem operation failed for ${workspacePath}`, {
-      cause: error.toError(err),
-      context: { path: workspacePath },
-    });
+  get provider(): string {
+    return this.options.provider ?? this.fs.backend;
   }
 
-  /* --- lifecycle --- */
-
-  /**
-   * Probe whether {@link basePath} exists and cache the result on
-   * {@link _basePathMissing}.
-   */
-  private async resolveBasePathStatus(): Promise<void> {
-    if (this._basePathMissing !== undefined) return;
-    try {
-      await this.assertAbsoluteReadable(this.basePath);
-      this._basePathMissing = false;
-    } catch (err) {
-      if (error.errorContext(err).notAccessible) {
-        this._basePathMissing = true;
-        return;
-      }
-      this.rethrow(err, "/");
-    }
+  get readOnly(): boolean {
+    return this.options.readOnly === true || this.fs.readOnly;
   }
 
-  /** Delegate to {@link emptyFilesystem} when the base path is missing. */
-  private async emptyFallback(): Promise<ReturnType<typeof emptyFilesystem> | undefined> {
-    await this.resolveBasePathStatus();
-    return this._basePathMissing ? emptyFilesystem() : undefined;
+  get basePath(): string {
+    return this.fs.root;
   }
 
   override async init(): Promise<void> {
-    await this.resolveBasePathStatus();
-
-    if (this._basePathMissing) {
-      if (this.mkdirs === false) {
-        return;
-      }
-      try {
-        await this.mkdirAbsolute(this.basePath);
-        this._basePathMissing = false;
-        if (this._readOnly === undefined) {
-          this._readOnly = false;
-        }
-      } catch (err) {
-        if (this.mkdirs === true) {
-          this.rethrow(err, "/");
-        }
-        logger.debug("mkdirs:try-failed", {
-          basePath: this.basePath,
-          error: error.errorMessage(err),
-        });
-      }
-      return;
-    }
-
-    if (this._readOnly === undefined) {
-      await this.probeReadOnly();
-    }
-  }
-
-  /**
-   * Write and delete a ephemeral probe file to detect read-only access when
-   * {@link DatabricksWorkspaceFilesystemOptions.readOnly} was not set.
-   *
-   * @returns `true` when the probe write (and cleanup) succeeded.
-   */
-  private async probeReadOnly(): Promise<boolean> {
-    const absolutePath = this.resolvePath(`/.__dbx_fs_probe_${hash.id()}`);
-    try {
-      await this.writeAbsolute(absolutePath, Buffer.from("probe\n"), true);
-      this._readOnly = false;
-    } catch {
-      this._readOnly = true;
-      return false;
-    }
-    try {
-      await this.deleteAbsoluteFile(absolutePath);
-    } catch {
-      // Writable; leave a hidden probe file rather than failing init.
-    }
-    return true;
+    await this.fs.init();
   }
 
   override async destroy(): Promise<void> {
-    // Remote filesystem; nothing to tear down locally.
-  }
-
-  /* --- backend I/O --- */
-
-  /** Probe that `absolutePath` exists (file or directory metadata). */
-  private async assertAbsoluteReadable(absolutePath: string): Promise<void> {
-    await dispatchFilesBackend(absolutePath, {
-      dbfs: () => this.client.dbfs.getStatus({ path: absolutePath }),
-      workspace: () => this.client.workspace.getStatus({ path: absolutePath }),
-      ucFiles: () => this.client.files.getDirectoryMetadata({ directory_path: absolutePath }),
-    });
-  }
-
-  /** Read the full contents of `absolutePath` from the matching backend. */
-  private async readAbsolute(absolutePath: string): Promise<Buffer> {
-    return dispatchFilesBackend(absolutePath, {
-      dbfs: () => this.readDbfsFile(absolutePath),
-      workspace: () => this.readWorkspaceFile(absolutePath),
-      ucFiles: async () => {
-        const response = await this.client.files.download({ file_path: absolutePath });
-        return readResponseBody(
-          response.contents as globalThis.ReadableStream<Uint8Array> | undefined,
-        );
-      },
-    });
-  }
-
-  /** Write `buffer` to `absolutePath` on the matching backend. */
-  private async writeAbsolute(
-    absolutePath: string,
-    buffer: Buffer,
-    overwrite: boolean,
-  ): Promise<void> {
-    await dispatchFilesBackend(absolutePath, {
-      dbfs: () => this.writeDbfsFile(absolutePath, buffer, overwrite),
-      workspace: () => this.writeWorkspaceFile(absolutePath, buffer, overwrite),
-      ucFiles: () => this.uploadUcFile(absolutePath, buffer, overwrite),
-    });
-  }
-
-  /** Upload a buffer to a Unity Catalog Files API path. */
-  private uploadUcFile(absolutePath: string, buffer: Buffer, overwrite: boolean): Promise<unknown> {
-    return this.client.files.upload({
-      file_path: absolutePath,
-      contents: bufferToReadableStream(buffer) as never,
-      overwrite,
-    });
+    await this.fs.close();
   }
 
-  /** Delete a single file at `absolutePath` (non-recursive). */
-  private async deleteAbsoluteFile(absolutePath: string): Promise<void> {
-    await dispatchFilesBackend(absolutePath, {
-      dbfs: () => this.client.dbfs.delete({ path: absolutePath, recursive: false }),
-      workspace: () => this.client.workspace.delete({ path: absolutePath, recursive: false }),
-      ucFiles: () => this.client.files.delete({ file_path: absolutePath }),
-    });
-  }
-
-  /**
-   * Delete a file or directory at `absolutePath`.
-   *
-   * DBFS and workspace APIs accept `recursive`; UC volumes recurse manually.
-   */
-  private async deleteAbsolutePath(absolutePath: string, recursive: boolean): Promise<void> {
-    await dispatchFilesBackend(absolutePath, {
-      dbfs: async () => {
-        await this.client.dbfs.delete({ path: absolutePath, recursive });
-      },
-      workspace: async () => {
-        await this.client.workspace.delete({ path: absolutePath, recursive });
-      },
-      ucFiles: async () => {
-        if (recursive) {
-          await this.deleteUcDirectoryRecursive(absolutePath);
-          return;
-        }
-        const children = await this.listAbsoluteDirectory(absolutePath);
-        if (children.length > 0) {
-          throw new DirectoryNotEmptyError(this.workspacePath(absolutePath));
-        }
-        await this.client.files.deleteDirectory({ directory_path: absolutePath });
-      },
-    });
-  }
-
-  /** Create `absolutePath` and any missing parents on the matching backend. */
-  private async mkdirAbsolute(absolutePath: string): Promise<void> {
-    await dispatchFilesBackend(absolutePath, {
-      dbfs: () => this.client.dbfs.mkdirs({ path: absolutePath }),
-      workspace: () => this.client.workspace.mkdirs({ path: absolutePath }),
-      ucFiles: () => this.client.files.createDirectory({ directory_path: absolutePath }),
-    });
-  }
-
-  private async readDbfsFile(absolutePath: string): Promise<Buffer> {
-    const chunks: Buffer[] = [];
-    let offset = 0;
-    while (true) {
-      const response = await this.client.dbfs.read({
-        path: absolutePath,
-        offset,
-        length: DBFS_READ_CHUNK_BYTES,
-      });
-      const chunk = decodeDbfsPayload(response.data);
-      if (chunk.length === 0) break;
-      chunks.push(chunk);
-      offset += chunk.length;
-      if (chunk.length < DBFS_READ_CHUNK_BYTES) break;
-    }
-    return Buffer.concat(chunks);
-  }
-
-  private async readWorkspaceFile(absolutePath: string): Promise<Buffer> {
-    const response = await this.client.workspace.export({
-      path: absolutePath,
-      format: "AUTO",
-    });
-    return decodeDbfsPayload(response.content);
-  }
-
-  private async writeDbfsFile(
-    absolutePath: string,
-    buffer: Buffer,
-    overwrite: boolean,
-  ): Promise<void> {
-    if (buffer.length <= DBFS_PUT_MAX_BYTES) {
-      await this.client.dbfs.put({
-        path: absolutePath,
-        contents: buffer.toString("base64"),
-        overwrite,
-      });
-      return;
-    }
-    const created = await this.client.dbfs.create({ path: absolutePath, overwrite });
-    const handle = created.handle;
-    if (handle === undefined) {
-      throw ExecutionError.missingData("DBFS upload handle");
-    }
-    for (let offset = 0; offset < buffer.length; offset += DBFS_PUT_MAX_BYTES) {
-      const slice = buffer.subarray(offset, offset + DBFS_PUT_MAX_BYTES);
-      await this.client.dbfs.addBlock({
-        handle,
-        data: slice.toString("base64"),
-      });
-    }
-    await this.client.dbfs.close({ handle });
-  }
-
-  private async writeWorkspaceFile(
-    absolutePath: string,
-    buffer: Buffer,
-    overwrite: boolean,
-  ): Promise<void> {
-    await this.client.workspace.import({
-      path: absolutePath,
-      format: "AUTO",
-      content: buffer.toString("base64"),
-      overwrite,
-    });
-  }
-
-  /* --- MastraFilesystem API --- */
-
-  getInfo(): FilesystemInfo<{ basePath: string }> {
+  getInfo(): FilesystemInfo<{ root: string; backend: string }> {
     return {
       id: this.id,
       name: this.name,
       provider: this.provider,
       status: this.status,
       readOnly: this.readOnly,
-      metadata: { basePath: this.basePath },
+      metadata: { root: this.fs.root, backend: this.fs.backend },
     };
   }
 
   getInstructions(): string {
     return [
-      `Files live in Databricks under ${this.basePath}.`,
-      "Workspace paths are absolute within this root (for example `/notes/report.md`).",
-      "Workspace paths use `/Workspace/...`, `/Users/...`, or `/Repos/...` base paths.",
-      "Unity Catalog volumes use `/Volumes/<catalog>/<schema>/<volume>/...` base paths.",
+      `Files are served by a ${this.fs.backend} filesystem rooted at ${this.fs.root}.`,
+      "Workspace paths are absolute within this mount (for example `/notes/report.md`).",
     ].join(" ");
   }
 
-  /** Map a workspace-relative path to the backing Databricks absolute path. */
-  resolveAbsolutePath(inputPath: string): string | undefined {
-    return this.resolvePath(inputPath);
-  }
-
-  /** Read file contents from the workspace namespace. */
   async readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.readFile(inputPath, options);
-    const absolutePath = this.resolvePath(inputPath);
-    try {
-      const buffer = await this.readAbsolute(absolutePath);
-      return formatReadResult(buffer, options?.encoding);
-    } catch (err) {
-      this.rethrow(err, inputPath);
-    }
+    return this.delegate(inputPath, async () => {
+      if (options?.encoding) {
+        return this.fs.readFile(inputPath, { encoding: options.encoding });
+      }
+      return Buffer.from(await this.fs.readFile(inputPath));
+    });
   }
 
-  /** Write file contents into the workspace namespace. */
   async writeFile(inputPath: string, content: FileContent, options?: WriteOptions): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.writeFile(inputPath, content, options);
-    this.assertWritable("writeFile");
-    const absolutePath = this.resolvePath(inputPath);
-    const buffer = toBuffer(content);
-    const overwrite = options?.overwrite ?? true;
-    try {
-      if (!overwrite && (await this.exists(inputPath))) {
-        throw new FileExistsError(inputPath);
+    return this.delegateWrite("writeFile", inputPath, async () => {
+      if (options?.recursive === false) {
+        await this.assertParentExists(inputPath);
       }
-      await this.writeAbsolute(absolutePath, buffer, overwrite);
-    } catch (err) {
-      if (err instanceof FileExistsError) throw err;
-      this.rethrow(err, inputPath);
-    }
+      await this.fs.writeFile(inputPath, content, {
+        overwrite: options?.overwrite ?? true,
+      });
+    });
   }
 
-  /** Append to an existing file, creating it when missing. */
   async appendFile(inputPath: string, content: FileContent): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.appendFile(inputPath, content);
-    this.assertWritable("appendFile");
-    const existing = (await this.exists(inputPath))
-      ? await this.readFile(inputPath)
-      : Buffer.alloc(0);
-    const merged = Buffer.concat([
-      Buffer.isBuffer(existing) ? existing : Buffer.from(existing, "utf8"),
-      toBuffer(content),
-    ]);
-    await this.writeFile(inputPath, merged, { overwrite: true });
+    return this.delegateWrite("appendFile", inputPath, () =>
+      this.fs.appendFile(inputPath, content),
+    );
   }
 
-  /** Delete a file in the workspace namespace. */
   async deleteFile(inputPath: string, options?: RemoveOptions): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.deleteFile(inputPath, options);
-    this.assertWritable("deleteFile");
-    const absolutePath = this.resolvePath(inputPath);
-    try {
-      if (!(await this.exists(inputPath))) {
-        if (options?.force) return;
-        throw new FileNotFoundError(inputPath);
-      }
-      const entry = await this.stat(inputPath);
-      if (entry.type === "directory") {
-        throw new IsDirectoryError(inputPath);
-      }
-      await this.deleteAbsoluteFile(absolutePath);
-    } catch (err) {
-      if (err instanceof FileNotFoundError || err instanceof IsDirectoryError) throw err;
-      this.rethrow(err, inputPath);
-    }
+    return this.delegateWrite("deleteFile", inputPath, () =>
+      this.fs.deleteFile(inputPath, {
+        force: options?.force,
+        recursive: options?.recursive,
+      }),
+    );
   }
 
-  /** Copy a file within the workspace namespace. */
   async copyFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.copyFile(src, dest, options);
-    this.assertWritable("copyFile");
-    const overwrite = options?.overwrite ?? true;
-    if (!overwrite && (await this.exists(dest))) {
-      throw new FileExistsError(dest);
-    }
-    const content = await this.readFile(src);
-    await this.writeFile(dest, content, { overwrite: true });
+    return this.delegateWrite("copyFile", dest, () =>
+      this.fs.copyFile(src, dest, { overwrite: options?.overwrite ?? true }),
+    );
   }
 
-  /** Move or rename a file within the workspace namespace. */
   async moveFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.moveFile(src, dest, options);
-    this.assertWritable("moveFile");
-    const srcAbsolute = this.resolvePath(src);
-    const destAbsolute = this.resolvePath(dest);
-    const overwrite = options?.overwrite ?? true;
-    try {
-      if (!overwrite && (await this.exists(dest))) {
-        throw new FileExistsError(dest);
-      }
-      if (
-        resolveFilesBackend(srcAbsolute) === "dbfs" &&
-        resolveFilesBackend(destAbsolute) === "dbfs"
-      ) {
-        await this.client.dbfs.move({
-          source_path: srcAbsolute,
-          destination_path: destAbsolute,
-        });
-        return;
-      }
-      await this.copyFile(src, dest, { overwrite: true });
-      await this.deleteFile(src, { force: true });
-    } catch (err) {
-      if (err instanceof FileExistsError) throw err;
-      this.rethrow(err, dest);
-    }
+    return this.delegateWrite("moveFile", dest, () =>
+      this.fs.moveFile(src, dest, { overwrite: options?.overwrite ?? true }),
+    );
   }
 
-  /** Create a directory in the workspace namespace. */
   async mkdir(inputPath: string, options?: { recursive?: boolean }): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.mkdir(inputPath, options);
-    this.assertWritable("mkdir");
-    const absolutePath = this.resolvePath(inputPath);
-    try {
-      await this.mkdirAbsolute(absolutePath);
-      if (!options?.recursive) {
-        return;
-      }
-    } catch (err) {
-      this.rethrow(err, inputPath);
-    }
+    return this.delegateWrite("mkdir", inputPath, () =>
+      this.fs.mkdir(inputPath, { recursive: options?.recursive }),
+    );
   }
 
-  /** Remove a directory from the workspace namespace. */
   async rmdir(inputPath: string, options?: RemoveOptions): Promise<void> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.rmdir(inputPath, options);
-    this.assertWritable("rmdir");
-    const absolutePath = this.resolvePath(inputPath);
-    try {
-      if (!(await this.exists(inputPath))) {
-        if (options?.force) return;
-        throw new DirectoryNotFoundError(inputPath);
-      }
-      const entry = await this.stat(inputPath);
-      if (entry.type !== "directory") {
-        throw new NotDirectoryError(inputPath);
-      }
-      await this.deleteAbsolutePath(absolutePath, options?.recursive ?? false);
-    } catch (err) {
-      if (
-        err instanceof DirectoryNotFoundError ||
-        err instanceof NotDirectoryError ||
-        err instanceof DirectoryNotEmptyError
-      ) {
-        throw err;
-      }
-      this.rethrow(err, inputPath);
-    }
-  }
-
-  /**
-   * Recursively delete a Unity Catalog directory tree.
-   *
-   * DBFS and workspace trees use native recursive delete via
-   * {@link deleteAbsolutePath} instead.
-   */
-  private async deleteUcDirectoryRecursive(absolutePath: string): Promise<void> {
-    for (const child of await this.listAbsoluteDirectory(absolutePath)) {
-      const childAbsolute = path.join(absolutePath, child.name);
-      if (child.type === "directory") {
-        await this.deleteUcDirectoryRecursive(childAbsolute);
-      } else {
-        await this.deleteAbsoluteFile(childAbsolute);
-      }
-    }
-    await this.client.files.deleteDirectory({ directory_path: absolutePath });
+    return this.delegateWrite(
+      "rmdir",
+      inputPath,
+      () =>
+        this.fs.rmdir(inputPath, {
+          force: options?.force,
+          recursive: options?.recursive,
+        }),
+      { preferDirectory: true },
+    );
   }
 
-  /* --- directory listing --- */
-
-  /** List entries in a workspace directory. */
   async readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.readdir(inputPath, options);
-    const absolutePath = this.resolvePath(inputPath);
-    try {
-      const entries = await this.listAbsoluteDirectory(absolutePath);
-      const filtered = this.filterEntries(entries, options);
-      if (!options?.recursive) return filtered;
-      return await this.readDirectoryRecursive(absolutePath, options, 0);
-    } catch (err) {
-      this.rethrow(err, inputPath);
-    }
-  }
-
-  private async readDirectoryRecursive(
-    absolutePath: string,
-    options: ListOptions,
-    depth: number,
-    relativePrefix = "",
-  ): Promise<FileEntry[]> {
-    const maxDepth = options.maxDepth ?? Number.POSITIVE_INFINITY;
-    const entries = this.filterEntries(await this.listAbsoluteDirectory(absolutePath), options);
-    const collected: FileEntry[] = [];
-    for (const entry of entries) {
-      const relativeName = relativePrefix ? path.join(relativePrefix, entry.name) : entry.name;
-      collected.push({ ...entry, name: relativeName });
-      if (entry.type !== "directory" || depth >= maxDepth) continue;
-      collected.push(
-        ...(await this.readDirectoryRecursive(
-          path.join(absolutePath, entry.name),
-          options,
-          depth + 1,
-          relativeName,
-        )),
-      );
-    }
-    return collected;
-  }
-
-  private async listAbsoluteDirectory(absolutePath: string): Promise<FileEntry[]> {
-    return dispatchFilesBackend(absolutePath, {
-      dbfs: async () => {
-        const entries: FileEntry[] = [];
-        for await (const info of this.client.dbfs.list({ path: absolutePath })) {
-          entries.push({
-            name: path.basename(info.path ?? ""),
-            type: info.is_dir ? "directory" : "file",
-            size: info.file_size,
-          });
-        }
-        return entries;
-      },
-      workspace: async () => {
-        const entries: FileEntry[] = [];
-        for await (const info of this.client.workspace.list({ path: absolutePath })) {
-          entries.push({
-            name: path.basename(info.path ?? ""),
-            type: info.object_type === "DIRECTORY" ? "directory" : "file",
-          });
-        }
-        return entries;
-      },
-      ucFiles: async () => {
-        const entries: FileEntry[] = [];
-        for await (const entry of this.client.files.listDirectoryContents({
-          directory_path: absolutePath,
-        })) {
-          entries.push({
-            name: entry.name ?? path.basename(entry.path ?? ""),
-            type: entry.is_directory ? "directory" : "file",
-            size: entry.file_size,
-          });
-        }
-        return entries;
-      },
-    });
-  }
-
-  /** Apply Mastra list filters (`extension`, etc.) to directory entries. */
-  private filterEntries(entries: FileEntry[], options?: ListOptions): FileEntry[] {
-    if (!options?.extension) return entries;
-    const extensions = Array.isArray(options.extension) ? options.extension : [options.extension];
-    const normalized = extensions.map((ext) =>
-      ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`,
+    return this.delegate(
+      inputPath,
+      async () =>
+        (
+          await this.fs.readdir(inputPath, {
+            recursive: options?.recursive,
+            maxDepth: options?.maxDepth,
+            extension: options?.extension,
+          })
+        ).map(toMastraEntry),
+      { preferDirectory: true },
     );
-    return entries.filter((entry) => {
-      if (entry.type !== "file") return true;
-      const lower = entry.name.toLowerCase();
-      return normalized.some((ext) => lower.endsWith(ext));
-    });
   }
 
-  /* --- metadata --- */
-
-  /** Return whether `inputPath` exists in the workspace namespace. */
   async exists(inputPath: string): Promise<boolean> {
     await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.exists(inputPath);
-    try {
-      await this.stat(inputPath);
-      return true;
-    } catch (err) {
-      if (err instanceof FileNotFoundError) return false;
-      throw err;
-    }
+    return this.fs.exists(inputPath);
   }
 
-  /** Return file or directory metadata for `inputPath`. */
   async stat(inputPath: string): Promise<FileStat> {
-    await this.ensureReady();
-    const empty = await this.emptyFallback();
-    if (empty) return empty.stat(inputPath);
-    const absolutePath = this.resolvePath(inputPath);
-    const workspacePath = this.workspacePath(absolutePath);
-    try {
-      return await dispatchFilesBackend(absolutePath, {
-        dbfs: async () => {
-          const info = await this.client.dbfs.getStatus({ path: absolutePath });
-          return {
-            name: path.basename(info.path ?? absolutePath),
-            path: workspacePath,
-            type: info.is_dir ? ("directory" as const) : ("file" as const),
-            size: info.file_size ?? 0,
-            createdAt: new Date(info.modification_time ?? 0),
-            modifiedAt: new Date(info.modification_time ?? 0),
-          };
-        },
-        workspace: async () => {
-          const info = await this.client.workspace.getStatus({ path: absolutePath });
-          return {
-            name: path.basename(info.path ?? absolutePath),
-            path: workspacePath,
-            type: info.object_type === "DIRECTORY" ? ("directory" as const) : ("file" as const),
-            size: 0,
-            createdAt: new Date(info.created_at ?? 0),
-            modifiedAt: new Date(info.modified_at ?? 0),
-          };
-        },
-        ucFiles: () => this.statUcAbsolute(absolutePath, workspacePath, inputPath),
-      });
-    } catch (err) {
-      this.rethrow(err, inputPath);
-    }
-  }
-
-  /**
-   * Stat a Unity Catalog path by probing file metadata first, then
-   * directory metadata.
-   */
-  private async statUcAbsolute(
-    absolutePath: string,
-    workspacePath: string,
-    inputPath: string,
-  ): Promise<FileStat> {
-    try {
-      const metadata = await this.client.files.getMetadata({
-        file_path: absolutePath,
-      });
-      return {
-        name: path.basename(absolutePath),
-        path: workspacePath,
-        type: "file" as const,
-        size: Number(metadata["content-length"] ?? 0),
-        createdAt: parseHttpDate(metadata["last-modified"]),
-        modifiedAt: parseHttpDate(metadata["last-modified"]),
-        mimeType: metadata["content-type"],
-      };
-    } catch (fileErr) {
-      if (!error.errorContext(fileErr).notAccessible) {
-        this.rethrow(fileErr, inputPath);
-      }
-      await this.client.files.getDirectoryMetadata({
-        directory_path: absolutePath,
-      });
-      return {
-        name: path.basename(absolutePath),
-        path: workspacePath,
-        type: "directory" as const,
-        size: 0,
-        createdAt: new Date(0),
-        modifiedAt: new Date(0),
-      };
-    }
-  }
-}
-
-/* --------------------------- empty filesystem --------------------------- */
-
-/** Normalize paths for the in-memory empty filesystem namespace. */
-function normalizeEmptyFilesystemPath(inputPath: string): string {
-  const trimmed = inputPath.trim();
-  if (!trimmed || trimmed === ".") return "/";
-  const normalized = trimmed.startsWith("/")
-    ? path.normalize(trimmed)
-    : path.normalize(`/${trimmed}`);
-  return normalized === "." ? "/" : normalized;
-}
-
-/**
- * Read-only in-memory {@link WorkspaceFilesystem} with a single empty root.
- * Use {@link emptyFilesystem} rather than constructing directly.
- */
-class EmptyFilesystem extends MastraFilesystem {
-  readonly id = "empty-fs";
-  readonly name = "EmptyFilesystem";
-  readonly provider = "empty";
-  readonly readOnly = true;
-  status: ProviderStatus = "pending";
-
-  constructor() {
-    super({ name: "EmptyFilesystem" });
-  }
-
-  override async init(): Promise<void> {
-    // No remote or on-disk resources to provision.
-  }
-
-  override async destroy(): Promise<void> {
-    // Stateless; nothing to release.
-  }
-
-  getInfo(): FilesystemInfo {
-    return {
-      id: this.id,
-      name: this.name,
-      provider: this.provider,
-      status: this.status,
-      readOnly: this.readOnly,
-    };
-  }
-
-  getInstructions(): string {
-    return "This filesystem is empty and read-only.";
-  }
-
-  private rootStat(): FileStat {
-    return {
-      name: "/",
-      path: "/",
-      type: "directory",
-      size: 0,
-      createdAt: EMPTY_FILESYSTEM_EPOCH,
-      modifiedAt: EMPTY_FILESYSTEM_EPOCH,
-    };
-  }
-
-  private assertWritable(operation: string): void {
-    throw new WorkspaceReadOnlyError(operation);
+    return this.delegate(inputPath, async () =>
+      toMastraStat(await this.fs.stat(inputPath), inputPath),
+    );
   }
 
-  override async readFile(inputPath: string, _options?: ReadOptions): Promise<string | Buffer> {
+  private async delegate<T>(
+    path: string,
+    op: () => Promise<T>,
+    options?: { preferDirectory?: boolean },
+  ): Promise<T> {
     await this.ensureReady();
-    const normalized = normalizeEmptyFilesystemPath(inputPath);
-    if (normalized === "/") {
-      throw new IsDirectoryError(normalized);
+    try {
+      return await op();
+    } catch (err) {
+      this.rethrow(err, path, options);
     }
-    throw new FileNotFoundError(normalized);
   }
 
-  override async writeFile(
-    _inputPath: string,
-    _content: FileContent,
-    _options?: WriteOptions,
+  /** {@link delegate} for a mutation: refuse a read-only mount before doing any work. */
+  private delegateWrite(
+    operation: string,
+    path: string,
+    op: () => Promise<void>,
+    options?: { preferDirectory?: boolean },
   ): Promise<void> {
-    await this.ensureReady();
-    this.assertWritable("writeFile");
-  }
-
-  override async appendFile(_inputPath: string, _content: FileContent): Promise<void> {
-    await this.ensureReady();
-    this.assertWritable("appendFile");
-  }
-
-  override async deleteFile(inputPath: string, options?: RemoveOptions): Promise<void> {
-    await this.ensureReady();
-    const normalized = normalizeEmptyFilesystemPath(inputPath);
-    if (normalized === "/") {
-      throw new IsDirectoryError(normalized);
+    if (this.readOnly) {
+      throw new WorkspaceReadOnlyError(operation);
     }
-    if (options?.force) return;
-    throw new FileNotFoundError(normalized);
-  }
-
-  override async copyFile(src: string, _dest: string, _options?: CopyOptions): Promise<void> {
-    await this.ensureReady();
-    const normalizedSrc = normalizeEmptyFilesystemPath(src);
-    if (normalizedSrc !== "/") {
-      throw new FileNotFoundError(normalizedSrc);
+    return this.delegate(path, op, options);
+  }
+
+  /** When Mastra asks for non-recursive writes, require the parent directory. */
+  private async assertParentExists(inputPath: string): Promise<void> {
+    const parent = posixPath.dirname(normalizeWorkspacePath(inputPath));
+    if (parent === "/" || (await this.fs.exists(parent))) return;
+    throw new DirectoryNotFoundError(parent);
+  }
+
+  private rethrow(err: unknown, inputPath: string, options?: { preferDirectory?: boolean }): never {
+    if (
+      err instanceof FileNotFoundError ||
+      err instanceof DirectoryNotFoundError ||
+      err instanceof FileExistsError ||
+      err instanceof IsDirectoryError ||
+      err instanceof NotDirectoryError ||
+      err instanceof DirectoryNotEmptyError ||
+      err instanceof PermissionError ||
+      err instanceof WorkspaceReadOnlyError
+    ) {
+      throw err;
     }
-    throw new IsDirectoryError(normalizedSrc);
-  }
 
-  override async moveFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
-    await this.copyFile(src, dest, options);
-  }
+    if (err instanceof FileSystemError) {
+      throw mapSharedError(err, inputPath, options?.preferDirectory === true);
+    }
 
-  override async mkdir(_inputPath: string, _options?: { recursive?: boolean }): Promise<void> {
-    await this.ensureReady();
-    this.assertWritable("mkdir");
+    throw err;
   }
+}
 
-  override async rmdir(inputPath: string, options?: RemoveOptions): Promise<void> {
-    await this.ensureReady();
-    const normalized = normalizeEmptyFilesystemPath(inputPath);
-    if (normalized === "/") {
-      throw new DirectoryNotEmptyError(normalized);
-    }
-    if (options?.force) return;
-    throw new DirectoryNotFoundError(normalized);
-  }
+/** Fresh writable local temp mount on a root unique to this call. */
+export function scratchFilesystem(): MastraFileSystemAdapter {
+  return filesystems(localFS.scratchFS("mastra"));
+}
 
-  override async readdir(inputPath: string, _options?: ListOptions): Promise<FileEntry[]> {
-    await this.ensureReady();
-    const normalized = normalizeEmptyFilesystemPath(inputPath);
-    if (normalized === "/") return [];
-    throw new DirectoryNotFoundError(normalized);
+/** Map a shared-fs error code onto the matching Mastra filesystem error. */
+function mapSharedError(err: FileSystemError, inputPath: string, preferDirectory: boolean): Error {
+  const path = err.path ?? inputPath;
+  switch (err.code) {
+    case "NOT_FOUND":
+      return preferDirectory ? new DirectoryNotFoundError(path) : new FileNotFoundError(path);
+    case "ALREADY_EXISTS":
+      return new FileExistsError(path);
+    case "NOT_DIRECTORY":
+      return new NotDirectoryError(path);
+    case "IS_DIRECTORY":
+      return new IsDirectoryError(path);
+    case "DIRECTORY_NOT_EMPTY":
+      return new DirectoryNotEmptyError(path);
+    case "PERMISSION_DENIED":
+      return new PermissionError(path, err.message);
+    case "READ_ONLY":
+      return new WorkspaceReadOnlyError(err.message);
+    default:
+      return err;
   }
+}
 
-  override async exists(inputPath: string): Promise<boolean> {
-    await this.ensureReady();
-    return normalizeEmptyFilesystemPath(inputPath) === "/";
-  }
+function toMastraEntry(entry: SharedFileEntry): FileEntry {
+  return {
+    name: entry.name,
+    type: entry.type === "directory" ? "directory" : "file",
+    size: entry.size,
+    isSymlink: entry.type === "symbolic-link",
+  };
+}
 
-  override async stat(inputPath: string): Promise<FileStat> {
-    await this.ensureReady();
-    const normalized = normalizeEmptyFilesystemPath(inputPath);
-    if (normalized === "/") return this.rootStat();
-    throw new FileNotFoundError(normalized);
-  }
+function toMastraStat(stat: SharedFileStat, inputPath: string): FileStat {
+  const epoch = new Date(0);
+  return {
+    name: stat.name,
+    path: normalizeWorkspacePath(stat.path || inputPath),
+    type: stat.type === "directory" ? "directory" : "file",
+    size: stat.size ?? 0,
+    createdAt: stat.createdAt ?? epoch,
+    modifiedAt: stat.modifiedAt ?? epoch,
+    mimeType: stat.mimeType,
+  };
 }
 
-/** Memoized singleton empty read-only filesystem for no-op mounts. */
-export const emptyFilesystem = functionModule.memoize(() => new EmptyFilesystem());
+/**
+ * Mastra namespace path (`/a/b`). A `..` that would escape clamps to the root
+ * rather than throwing - the wrapped filesystem enforces containment itself,
+ * and a mount should not fail a listing over a stray segment.
+ */
+function normalizeWorkspacePath(inputPath: string): string {
+  const result = posixPath.normalize(inputPath);
+  return result.ok ? result.path : "/";
+}