@dbx-tools/appkit-mastra 0.9.93 → 0.9.99

package/src/workspaces.ts

@@ -1,39 +1,53 @@
 /**
  * Mastra workspace factory for Databricks Apps.
  *
- * Builds a per-request {@link Workspace} with Databricks Sandbox command
- * execution plus a {@link CompositeFilesystem} over the NAMED skill folders
- * resolved for that request. A skill folder maps a name to a location plus its
- * readable / writable policy: a Databricks path mounted through the OBO client
- * on {@link MASTRA_USER_KEY}, or any {@link WorkspaceFilesystem} a consuming
- * library already owns. {@link DEFAULT_SKILL_FOLDERS} supplies the Assistant
- * trees, and `skillFolders` merges over it - same name overrides, `false`
- * disables, a new name adds. Optional mount resolvers contribute further
- * filesystems and skill scan roots on top.
+ * Builds native Mastra workspace configuration from Databricks paths. Paths
+ * mount at the same path by default, `~` resolves to the current user's
+ * Databricks workspace home, and `/tmp[/subpath]` resolves to stable
+ * user-scoped storage under the host's ephemeral temp directory.
  *
  * Databricks mounts use `@dbx-tools/databricks` {@link DatabricksFileSystem}
- * wrapped by {@link filesystems}; missing roots fall back to
- * {@link scratchFilesystem}.
+ * wrapped by {@link filesystems}; inaccessible roots are skipped independently.
  *
  * @module
  */
 
 import { createHash } from "node:crypto";
-import { ConfigurationError, createWorkspaceClient } from "@databricks/appkit";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ConfigurationError, createWorkspaceClient, getExecutionContext } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
+import { pluginRegistry } from "@dbx-tools/appkit";
+import {
+  filesCache as filesCachePlugin,
+  type FilesCacheExports,
+  type FilesCacheScope,
+} from "@dbx-tools/appkit/files-cache";
 import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { LocalFileSystem } from "@dbx-tools/fs";
+import { match, type PathMatchInput } from "@dbx-tools/path";
 import { errorUtils, log, object, stringUtils, token } from "@dbx-tools/shared-core";
-import type { FileSystem } from "@dbx-tools/shared-fs";
-import { LRUCache } from "lru-cache";
+import {
+  fs as sharedFS,
+  posixPath,
+  type CacheableFileSystemOperation,
+  type FileSystem,
+  type FileSystemCache,
+  type FileSystemCacheOptions,
+  MemoryFileSystem,
+} from "@dbx-tools/shared-fs";
 import type { RequestContext } from "@mastra/core/request-context";
 import {
-  CompositeFilesystem,
+  WORKSPACE_TOOLS,
   Workspace,
   type SkillsResolver,
+  type ToolConfigWithArgsContext,
+  type WorkspaceConfig,
   type WorkspaceFilesystem,
   type WorkspaceSandbox,
   type WorkspaceSandboxResolver,
+  type WorkspaceToolConfig,
+  type WorkspaceToolsConfig,
 } from "@mastra/core/workspace";
 
 import {
@@ -43,94 +57,129 @@ import {
   resolveUserKey,
   type User,
 } from "./config.ts";
-import { filesystems, scratchFilesystem } from "./filesystems.ts";
+import {
+  filesystems,
+  MountedCompositeFilesystem,
+  type MastraFileSystemAdapterOptions,
+} from "./filesystems.ts";
 import { MontySandbox } from "./monty-sandbox.ts";
 import { DatabricksSandbox, type DatabricksWorkspaceSandboxOptions } from "./sandbox.ts";
-import {
-  DEFAULT_WORKSPACE_SKILL_CACHE_TTL_MS,
-  workspaceSkillCatalogue,
-  type SkillCatalogueResolver,
-  type SkillCatalogueSource,
-} from "./skill-cache.ts";
-import { ASSISTANT_SHARED_SKILLS_PATH, userAssistantSkillsPath } from "./skill-paths.ts";
+import { ORGANIZATION_ASSISTANT_PATH, personalWorkspacePath } from "./skill-paths.ts";
 
 /* ------------------------------ constants ------------------------------ */
 
 /** OAuth scopes that gate Databricks workspace file mounts. */
 const WORKSPACE_FILE_SCOPES = ["workspace", "workspace.workspace", "all-apis"] as const;
+const SCRATCH_MOUNT = "/tmp";
+const CACHEABLE_FILESYSTEM_OPERATIONS = [
+  "exists",
+  "readFile",
+  "readdir",
+  "stat",
+] as const satisfies readonly CacheableFileSystemOperation[];
 
 const logger = log.logger("mastra/workspaces");
-const MAX_SCOPED_WORKSPACE_FILESYSTEMS = 16;
-const scopedWorkspaceFilesystems = new LRUCache<string, WorkspaceFilesystem>({
-  max: MAX_SCOPED_WORKSPACE_FILESYSTEMS,
-});
-const workspaceCatalogueResolvers = new WeakMap<Workspace, SkillCatalogueResolver>();
+let workspaceSourceSequence = 0;
+const databricksWorkspaceOptions = new WeakMap<Workspace, DatabricksWorkspaceOptions>();
 
 /* -------------------------------- types -------------------------------- */
 
 /** Per-request context for mount and skill-folder resolvers. */
-export interface WorkspaceMountContext {
+export interface DatabricksWorkspaceContext {
   requestContext?: RequestContext;
 }
 
 /**
- * A skill-folder field given either directly or as a per-request resolver.
- * A resolver returning `undefined` skips the folder for that request.
+ * One Databricks path mounted into a Mastra workspace.
  */
-export type SkillFolderValue<T> =
-  T | ((context: WorkspaceMountContext) => T | undefined | Promise<T | undefined>);
-
-/**
- * One named skill-folder location and its read / write policy.
- *
- * Give {@link path} for a Databricks workspace tree (mounted through the
- * request's OBO client), or {@link filesystem} for a mount the consumer builds
- * itself. {@link filesystem} wins when both are set.
- */
-export interface SkillFolderOptions {
-  /** Absolute Databricks workspace path for this folder. */
-  path?: SkillFolderValue<string>;
-  /** Ready-made mount, for locations the OBO client cannot reach. */
-  filesystem?: SkillFolderValue<WorkspaceFilesystem>;
+export interface DatabricksWorkspacePathOptions {
+  /** Absolute Databricks path or `~` shortcut for the current user's workspace home. */
+  path: string;
+  /** Human-friendly mount name shown in filesystem listings. */
+  displayName?: string;
+  /** Mount description shown in filesystem listings and workspace instructions. */
+  description?: string;
   /**
    * Scan this mount for `SKILL.md` files. Defaults to `true`; `false` mounts
    * the location for file tools without adding it to skill discovery.
    */
   readable?: boolean;
   /**
-   * Allow writes to a {@link path} mount (and create the root when missing).
-   * Defaults to `false`. A supplied {@link filesystem} carries its own
-   * read-only flag instead.
+   * Skill roots relative to this filesystem root. Defaults to `["."]`.
+   * Each path is joined to the actual mount path before Mastra scans it.
+   */
+  skills?: readonly string[];
+  /**
+   * Allow write attempts to a {@link path} mount. Defaults to `true` for
+   * `/Workspace` roots and `false` elsewhere. Databricks permissions still
+   * determine whether each mutation succeeds.
    */
   writable?: boolean;
-  /** Mount point in the composite namespace. Defaults to `/<name>`. */
+  /**
+   * Create a writable {@link path} root when missing. Defaults to
+   * {@link writable}; set `false` for pre-existing roots with conditional access.
+   */
+  createRoot?: boolean;
+  /** Mount point in the composite namespace. Databricks paths default to their actual root. */
   mount?: string;
 }
 
-/** Mount map plus optional Mastra skill scan roots for one resolver. */
-export interface WorkspaceMountContribution {
+/** String shorthand or full options for one Databricks workspace path. */
+export type DatabricksWorkspacePath = string | DatabricksWorkspacePathOptions;
+
+/** Fixed or request-dependent Databricks path entry. */
+export type DatabricksWorkspacePathValue =
+  | DatabricksWorkspacePath
+  | false
+  | ((
+      context: DatabricksWorkspaceContext,
+    ) =>
+      | DatabricksWorkspacePath
+      | false
+      | undefined
+      | Promise<DatabricksWorkspacePath | false | undefined>);
+
+/** Operations and path globs cached by the Databricks filesystem shortcut. */
+export interface DatabricksWorkspaceCacheFilter {
+  /** Cached filesystem operations. Omit for `exists`, `readFile`, `readdir`, and `stat`. */
+  operations?: CacheableFileSystemOperation | readonly CacheableFileSystemOperation[];
+  /** Absolute or root-relative globs and predicates. `~` expands per request. */
+  paths?: PathMatchInput | readonly PathMatchInput[];
+}
+
+/** Fixed or request-dependent filesystem cache selection. */
+export type DatabricksWorkspaceCache =
+  | boolean
+  | DatabricksWorkspaceCacheFilter
+  | readonly DatabricksWorkspaceCacheFilter[]
+  | ((
+      context: DatabricksWorkspaceContext,
+    ) =>
+      | boolean
+      | DatabricksWorkspaceCacheFilter
+      | readonly DatabricksWorkspaceCacheFilter[]
+      | undefined
+      | Promise<
+          | boolean
+          | DatabricksWorkspaceCacheFilter
+          | readonly DatabricksWorkspaceCacheFilter[]
+          | undefined
+        >);
+
+/** Mount map plus optional Mastra skill scan roots resolved for one request. */
+interface WorkspaceMountContribution {
   mounts: Record<string, WorkspaceFilesystem>;
-  /** Ordered source roots included in catalogue discovery. */
-  skillSources?: SkillCatalogueSource[];
   /** Paths within the composite namespace where `SKILL.md` files are scanned. */
   skillPaths?: string[];
-  /**
-   * Stable identity for this contribution. When every non-empty contribution
-   * supplies one, Mastra reuses the resolved source across requests.
-   */
-  cacheKey?: string;
 }
 
-/** Contributes filesystem mounts (and optional skill paths) for one request. */
-export type WorkspaceMountResolver = (
-  context: WorkspaceMountContext,
+/** Internal filesystem contribution resolver. */
+type WorkspaceMountResolver = (
+  context: DatabricksWorkspaceContext,
 ) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
 
-/** Names carried by {@link DEFAULT_SKILL_FOLDERS}. */
-export type DefaultSkillFolderName = "workspace-team" | "workspace-team-app";
-
 /**
- * Sandbox selection for {@link createWorkspace}. Databricks is the default;
+ * Sandbox selection for {@link databricksWorkspace}. Monty is the default;
  * `false` disables command execution, and a Mastra provider or resolver is an
  * explicit replacement.
  */
@@ -142,36 +191,26 @@ export type WorkspaceSandboxSelection =
   | WorkspaceSandbox
   | WorkspaceSandboxResolver;
 
-/** Options for {@link createWorkspace}. */
-export interface CreateWorkspaceOptions {
-  /** Workspace id; derived from `name` or `"workspace"` when omitted. */
-  id?: string;
-  /** Display name; derived from `id` when omitted. */
-  name?: string;
+/** Native Mastra workspace options plus Databricks path shortcuts. */
+export interface DatabricksWorkspaceOptions
+  extends Omit<WorkspaceConfig, "filesystem" | "mounts" | "sandbox" | "skills"> {
   /**
-   * Start from {@link DEFAULT_SKILL_FOLDERS}. Defaults to `true`; `false`
-   * starts from an empty map, leaving only the {@link skillFolders} given here.
+   * Start from {@link DEFAULT_DATABRICKS_WORKSPACE_PATHS}. Defaults to `true`.
    */
-  assistantSkills?: boolean;
+  assistantPaths?: boolean;
   /**
-   * Named skill folders merged over {@link DEFAULT_SKILL_FOLDERS}: a matching
-   * name overrides that default, `false` disables it, and any other name adds
-   * a folder.
+   * Databricks paths appended after the defaults. A string is shorthand for
+   * `{ path }`; a resolver may return either form per request.
    */
-  skillFolders?: Record<string, SkillFolderOptions | false>;
-  /** Extra per-request mount resolvers (run after the skill-folder mounts). */
-  mounts?: WorkspaceMountResolver[];
+  paths?: readonly DatabricksWorkspacePathValue[];
+  /** Native Mastra filesystems composed beside the Databricks paths. */
+  mounts?: Record<string, WorkspaceFilesystem>;
   /** Replace the auto-built dynamic skills resolver. */
   skills?: SkillsResolver;
-  /** Forwarded to Mastra when skill discovery is enabled. */
-  checkSkillFileMtime?: boolean;
-  /**
-   * Refresh TTL for the complete parsed skill catalogue. Auxiliary reads are
-   * always fresh. Defaults to five minutes.
-   */
-  workspaceSkillRefreshTtlMs?: number;
-  /** Enable BM25 keyword search over indexed workspace content. */
-  bm25?: boolean;
+  /** Filesystem cache filters. Ignored when the AppKit files-cache plugin is absent. */
+  cache?: DatabricksWorkspaceCache;
+  /** AppKit plugin context used to discover optional sibling capabilities. */
+  pluginContext?: pluginRegistry.PluginContextLike;
   /**
    * Command sandbox. Defaults to Monty. Pass `"databricks"` or an options
    * object for Databricks Sandbox, `false` to disable command execution, or an
@@ -191,96 +230,123 @@ export interface CreateWorkspaceOptions {
 /* ------------------------------- defaults ------------------------------- */
 
 /**
- * The skill folders every workspace starts with.
- *
- * - `workspace-team` - the shared workspace Assistant tree, read-only because
- *   writing it is a workspace-admin action.
- * - `workspace-team-app` - the requesting user's own Assistant tree, writable
- *   so the app can save skills back to it. Skipped when the request carries no
- *   user email.
+ * Default Databricks paths for shared and current-user Agent Skills.
  */
-export const DEFAULT_SKILL_FOLDERS: Readonly<Record<DefaultSkillFolderName, SkillFolderOptions>> = {
-  "workspace-team": {
-    path: ASSISTANT_SHARED_SKILLS_PATH,
+export const DEFAULT_DATABRICKS_WORKSPACE_PATHS: readonly DatabricksWorkspacePathOptions[] = [
+  {
+    path: ORGANIZATION_ASSISTANT_PATH,
     readable: true,
-    writable: false,
+    skills: ["skills"],
+    writable: true,
+    createRoot: false,
   },
-  "workspace-team-app": {
-    path: ({ requestContext }) => {
-      const email = resolveScopedEmail(requestContext);
-      return email ? userAssistantSkillsPath(email) : undefined;
-    },
+  {
+    path: "~",
     readable: true,
+    skills: [".assistant/skills"],
     writable: true,
+    createRoot: false,
   },
-};
+];
 
 /**
  * Create a Mastra {@link Workspace} with per-request Databricks mounts.
  *
- * @example Default skill folders only
+ * @example Default Databricks paths
  * ```ts
- * createWorkspace()
+ * databricksWorkspace()
  * ```
  *
- * @example Override a default, drop another, and add a location of your own
+ * @example Use only explicit paths
  * ```ts
- * createWorkspace({
- *   skillFolders: {
- *     "workspace-team": { path: "/Workspace/Shared/team-skills" },
- *     "workspace-team-app": false,
- *     runbooks: { path: "/Workspace/Shared/runbooks/skills", writable: true },
- *     volume: { filesystem: myVolumeFilesystem },
- *   },
+ * databricksWorkspace({
+ *   assistantPaths: false,
+ *   paths: ["~/project", "/tmp/project", "/Volumes/main/default/data"],
  * })
  * ```
  *
- * @example Skill folders plus a custom mount resolver
+ * @example Build a standard Mastra workspace yourself
  * ```ts
- * createWorkspace({
- *   mounts: [
- *     async ({ requestContext }) => ({
- *       mounts: { "/data": myFilesystem },
- *       skillPaths: [],
- *     }),
- *   ],
+ * new Workspace({
+ *   ...databricksWorkspaceConfig({ paths: ["~/project"] }),
+ *   sandbox: mySandbox,
  * })
  * ```
  */
-export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace {
+export function databricksWorkspaceConfig(
+  options: DatabricksWorkspaceOptions = {},
+): WorkspaceConfig {
   const { id, name } = resolveWorkspaceIdentity(options);
-  const skillFolders = resolveSkillFolders(options);
-  const folderNames = Object.keys(skillFolders);
+  const filesystemSourceKey = `${id}:${++workspaceSourceSequence}`;
+  const paths = resolveDatabricksWorkspacePaths(options);
+  const configuredPaths = paths.length;
   const extraSkillPaths = options.extraSkillPaths ?? [];
+  const filesCache = pluginRegistry.instance(options.pluginContext, filesCachePlugin)?.exports();
+  const configuredCache = options.cache;
+  const mountFilesCache = configuredCache === false ? undefined : filesCache;
+  const retainFilesystemSource =
+    mountFilesCache !== undefined &&
+    typeof configuredCache !== "function" &&
+    paths.every((path) => typeof path !== "function");
   const resolvers = buildMountResolvers(
-    skillFolders,
-    [...(options.mounts ?? []), ...localSkillMountResolvers(extraSkillPaths)],
+    paths,
+    options.mounts,
+    localSkillMountResolvers(extraSkillPaths),
+    mountFilesCache,
+    configuredCache,
   );
   const resolveContribution = contributionResolver(resolvers);
-  const skills = options.skills;
+  const resolveFilesystem = (context: DatabricksWorkspaceContext) =>
+    resolveWorkspaceFilesystem(
+      resolveContribution,
+      context,
+      retainFilesystemSource ? mountFilesCache : undefined,
+      filesystemSourceKey,
+    );
+  const skills: SkillsResolver =
+    options.skills ??
+    (async ({ requestContext }) => {
+      const context = { requestContext };
+      const contribution = await resolveContribution(context);
+      return resolveDistinctSkillPaths(
+        await resolveFilesystem(context),
+        contribution.skillPaths ?? [],
+      );
+    });
   const checkSkillFileMtime = options.checkSkillFileMtime ?? false;
-  const bm25 = options.bm25 !== false;
+  const bm25 = options.bm25 ?? true;
   const sandbox = resolveWorkspaceSandbox(options.sandbox, id, name);
+  const tools = workspaceTools(options.tools);
   logger.debug("workspace:create", {
     id,
     name,
     resolverCount: resolvers.length,
-    skillFolders: folderNames,
-    customMountResolvers: options.mounts?.length ?? 0,
+    configuredPaths,
+    customMounts: Object.keys(options.mounts ?? {}).length,
     customSkillsResolver: Boolean(options.skills),
     checkSkillFileMtime,
-    workspaceSkillRefreshTtlMs:
-      options.workspaceSkillRefreshTtlMs ?? DEFAULT_WORKSPACE_SKILL_CACHE_TTL_MS,
     bm25,
     extraSkillPaths: extraSkillPaths.length,
     sandbox: sandbox ? sandboxName(options.sandbox) : "disabled",
   });
 
-  const workspace = new Workspace({
+  const {
+    assistantPaths: _assistantPaths,
+    paths: _paths,
+    mounts: _mounts,
+    skills: _skills,
+    cache: _cache,
+    pluginContext: _pluginContext,
+    sandbox: _sandbox,
+    extraSkillPaths: _extraSkillPaths,
+    ...workspaceOptions
+  } = options;
+  return {
+    ...workspaceOptions,
     id,
     name,
-    filesystem: (context) => resolveWorkspaceFilesystem(resolveContribution, context),
-    ...(skills
+    filesystem: resolveFilesystem,
+    ...(resolvers.length > 0 || options.skills
       ? {
           skills,
           checkSkillFileMtime,
@@ -293,46 +359,85 @@ export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace
         }
       : {}),
     bm25,
-  });
-  if (!options.skills && resolvers.length > 0) {
-    workspaceCatalogueResolvers.set(
-      workspace,
-      buildSkillCatalogueResolver(resolveContribution, options.workspaceSkillRefreshTtlMs),
-    );
-  }
+    tools,
+  };
+}
+
+/** Create a native Mastra {@link Workspace} from {@link databricksWorkspaceConfig}. */
+export function databricksWorkspace(options: DatabricksWorkspaceOptions = {}): Workspace {
+  const workspace = new Workspace(databricksWorkspaceConfig(options));
+  databricksWorkspaceOptions.set(workspace, options);
   return workspace;
 }
 
-/** Return the dbx-tools catalogue resolver attached to one workspace. */
-export function workspaceSkillCatalogueResolver(
-  workspace: Workspace | undefined,
-): SkillCatalogueResolver | undefined {
-  return workspace ? workspaceCatalogueResolvers.get(workspace) : undefined;
+/** @internal Bind a caller-created Databricks workspace to its AppKit plugin context. */
+export function bindDatabricksWorkspaceContext(
+  workspace: Workspace,
+  pluginContext: pluginRegistry.PluginContextLike | undefined,
+): Workspace {
+  const options = databricksWorkspaceOptions.get(workspace);
+  if (!options || options.pluginContext !== undefined || pluginContext === undefined) {
+    return workspace;
+  }
+  return databricksWorkspace({ ...options, pluginContext });
 }
 
 /**
- * Merge the configured skill folders over {@link DEFAULT_SKILL_FOLDERS}.
- *
- * `assistantSkills: false` drops the defaults, and a `false` value removes one
- * entry by name.
+ * Resolve default and caller-provided Databricks paths in priority order.
  */
-export function resolveSkillFolders(
-  options: Pick<CreateWorkspaceOptions, "assistantSkills" | "skillFolders"> = {},
-): Record<string, SkillFolderOptions> {
-  const merged: Record<string, SkillFolderOptions> =
-    options.assistantSkills === false ? {} : { ...DEFAULT_SKILL_FOLDERS };
-  for (const [name, folder] of Object.entries(options.skillFolders ?? {})) {
-    if (folder === false) {
-      delete merged[name];
-    } else {
-      merged[name] = folder;
-    }
-  }
-  return merged;
+export function resolveDatabricksWorkspacePaths(
+  options: Pick<DatabricksWorkspaceOptions, "assistantPaths" | "paths"> = {},
+): DatabricksWorkspacePathValue[] {
+  return [
+    ...(options.assistantPaths === false ? [] : DEFAULT_DATABRICKS_WORKSPACE_PATHS),
+    ...(options.paths ?? []),
+  ];
 }
 
 /* ---------------------------- private helpers ---------------------------- */
 
+/** Require approval unless a filesystem mutation stays inside a user-owned writable root. */
+function requireApprovalOutsideWritableRoots({
+  args,
+  requestContext,
+}: ToolConfigWithArgsContext): boolean {
+  const inputPath = args.path;
+  if (typeof inputPath !== "string" || !posixPath.isAbsolute(inputPath)) return true;
+  const normalized = posixPath.normalize(inputPath);
+  if (!normalized.ok) return true;
+  if (posixPath.isWithinRoot(SCRATCH_MOUNT, normalized.path)) return false;
+  const emailValue = requestContext[MASTRA_USER_EMAIL_KEY];
+  const email = typeof emailValue === "string" ? stringUtils.trimToNull(emailValue) : undefined;
+  if (!email) return true;
+  return !posixPath.isWithinRoot(personalWorkspacePath(email), normalized.path);
+}
+
+function workspaceTools(configured: WorkspaceToolsConfig | undefined): WorkspaceToolsConfig {
+  const requireApproval: WorkspaceToolConfig =
+    configured?.requireApproval === undefined
+      ? { requireApproval: requireApprovalOutsideWritableRoots }
+      : {};
+  const defaults = {
+    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: requireApproval,
+    [WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE]: requireApproval,
+    [WORKSPACE_TOOLS.FILESYSTEM.AST_EDIT]: requireApproval,
+    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: requireApproval,
+    [WORKSPACE_TOOLS.FILESYSTEM.MKDIR]: requireApproval,
+  } satisfies WorkspaceToolsConfig;
+  const configuredTools = configured as
+    Readonly<Record<string, WorkspaceToolConfig | undefined>> | undefined;
+  const mergedTools = Object.fromEntries(
+    Object.entries(defaults).map(([name, defaultConfig]) => [
+      name,
+      { ...defaultConfig, ...configuredTools?.[name] },
+    ]),
+  );
+  return {
+    ...defaults,
+    ...configured,
+    ...mergedTools,
+  };
+}
 function resolveWorkspaceSandbox(
   selection: WorkspaceSandboxSelection | undefined,
   workspaceId: string,
@@ -410,6 +515,48 @@ function hasWorkspaceFileScope(requestContext: RequestContext | undefined): bool
   );
 }
 
+/** Resolve the request client and authorization-safe files-cache scope. */
+async function resolveFilesCacheScope(context: DatabricksWorkspaceContext): Promise<
+  | {
+      client: WorkspaceClient;
+      scope: FilesCacheScope;
+    }
+  | undefined
+> {
+  const requestContext = context.requestContext;
+  const user = requestContext?.get(MASTRA_USER_KEY) as User | undefined;
+  const client = user?.executionContext.client as WorkspaceClient | undefined;
+  if (!requestContext || !user || !client) return undefined;
+  return {
+    client,
+    scope: {
+      host: (await client.config.getHost()).toString(),
+      userKey: resolveUserKey(requestContext),
+      ...(process.env.DATABRICKS_WORKSPACE_ID?.trim()
+        ? { workspaceId: process.env.DATABRICKS_WORKSPACE_ID.trim() }
+        : {}),
+    },
+  };
+}
+
+/** Join one relative skill root to its actual composite mount path. */
+function mountedSkillPath(mount: string, skillRoot: string): string {
+  if (posixPath.isAbsolute(skillRoot)) {
+    throw new TypeError(`Skill path must be relative to its mount: ${skillRoot}`);
+  }
+  const normalized = posixPath.normalize(skillRoot);
+  if (!normalized.ok) {
+    throw new TypeError(`Skill path escapes its mount: ${skillRoot}`);
+  }
+  return posixPath.join(posixPath.normalizeRoot(mount), normalized.path.slice(1));
+}
+
+/** Return whether a Databricks path belongs to the writable Workspace namespace. */
+function isWorkspaceRoot(root: string): boolean {
+  const normalized = posixPath.normalizeRoot(root);
+  return normalized === "/Workspace" || normalized.startsWith("/Workspace/");
+}
+
 /**
  * Mount resolver for the named skill folders.
  *
@@ -417,42 +564,54 @@ function hasWorkspaceFileScope(requestContext: RequestContext | undefined): bool
  * folder whose location resolves for this request.
  */
 async function resolveSkillFolderMounts(
-  skillFolders: Record<string, SkillFolderOptions>,
-  context: WorkspaceMountContext,
+  paths: readonly DatabricksWorkspacePathValue[],
+  context: DatabricksWorkspaceContext,
+  filesCache: FilesCacheExports | undefined,
+  cacheConfig: DatabricksWorkspaceCache | undefined,
 ): Promise<WorkspaceMountContribution> {
   const mounts: Record<string, WorkspaceFilesystem> = {};
-  const skillSources: SkillCatalogueSource[] = [];
   const skillPaths: string[] = [];
-  const cacheKeys: string[] = [];
   const requestContext = context.requestContext;
 
-  if (!requestContext || !shouldMountSkillFolders(requestContext)) {
-    logger.debug("skill-folders:skipped", {
-      reason: !requestContext ? "no-request-context" : "missing-workspace-scope",
-      nodeEnv: process.env.NODE_ENV,
-      scopes: requestContext?.get(MASTRA_SCOPES_KEY),
-    });
-    return { mounts, skillPaths };
-  }
+  const canMountDatabricks = Boolean(requestContext && shouldMountSkillFolders(requestContext));
+  const scoped = canMountDatabricks ? await resolveFilesCacheScope(context) : undefined;
+  const client = scoped?.client;
+  const fileSystemCache =
+    filesCache && scoped ? await filesCache.forScope(scoped.scope) : undefined;
 
-  const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
-  const client = user?.executionContext.client as WorkspaceClient | undefined;
-  const userKey = user ? resolveUserKey(requestContext) : undefined;
-  const host = client ? (await client.config.getHost()).toString() : undefined;
-
-  for (const [name, folder] of Object.entries(skillFolders)) {
-    const resolved = await resolveSkillFolderFilesystem(name, folder, context, {
+  for (const [index, path] of paths.entries()) {
+    const configured = await resolveDatabricksWorkspacePath(path, context);
+    if (!configured) continue;
+    if (posixPath.isWithinRoot(SCRATCH_MOUNT, configured.path)) {
+      const mount = configured.mount ?? configured.path;
+      mounts[mount] = userTempFilesystem(context, configured.path);
+      if (configured.readable !== false) {
+        skillPaths.push(
+          ...(configured.skills ?? []).map((path) => mountedSkillPath(mount, path)),
+        );
+      }
+      continue;
+    }
+    if (!canMountDatabricks) {
+      logger.debug("workspace-path:skipped", {
+        path: configured.path,
+        reason: !requestContext ? "no-request-context" : "missing-workspace-scope",
+      });
+      continue;
+    }
+    const resolved = await resolveSkillFolderFilesystem(configured, context, cacheConfig, {
       client,
-      host,
-      userKey,
+      fileSystemCache,
     });
     if (!resolved) continue;
-    const mount = folder.mount ?? `/${name}`;
+    const mount = configured.mount ?? resolved.root;
+    if (!mount) {
+      logger.debug("workspace-path:skipped", { index, reason: "missing-mount" });
+      continue;
+    }
     mounts[mount] = resolved.filesystem;
-    if (resolved.cacheKey) cacheKeys.push(resolved.cacheKey);
-    if (folder.readable !== false) {
-      skillPaths.push(mount);
-      skillSources.push({ ...resolved.skillSource, id: object.toStableKey({ mount, source: resolved.skillSource.id }) });
+    if (configured.readable !== false) {
+      skillPaths.push(...(configured.skills ?? ["."]).map((path) => mountedSkillPath(mount, path)));
     }
   }
 
@@ -463,11 +622,36 @@ async function resolveSkillFolderMounts(
 
   return {
     mounts,
-    skillSources,
     skillPaths,
-    ...(cacheKeys.length === Object.keys(mounts).length && cacheKeys.length > 0
-      ? { cacheKey: object.toStableKey(cacheKeys.sort()) }
-      : {}),
+  };
+}
+
+interface ResolvedDatabricksWorkspacePath {
+  path: string;
+  displayName?: string;
+  description?: string;
+  readable?: boolean;
+  skills?: readonly string[];
+  writable?: boolean;
+  createRoot?: boolean;
+  mount?: string;
+}
+
+async function resolveDatabricksWorkspacePath(
+  value: DatabricksWorkspacePathValue,
+  context: DatabricksWorkspaceContext,
+): Promise<ResolvedDatabricksWorkspacePath | undefined> {
+  const selected = typeof value === "function" ? await value(context) : value;
+  if (selected === false || selected === undefined) return undefined;
+  const configured = typeof selected === "string" ? { path: selected } : selected;
+  const requestContext = requestContextValues(context.requestContext);
+  const resolvedPath = resolveHomePath(configured.path, requestContext);
+  if (!resolvedPath) return undefined;
+  const resolvedMount = resolveHomePath(configured.mount, requestContext);
+  return {
+    ...configured,
+    path: resolvedPath,
+    ...(resolvedMount ? { mount: resolvedMount } : {}),
   };
 }
 
@@ -476,69 +660,164 @@ async function resolveSkillFolderMounts(
  * for this request.
  */
 async function resolveSkillFolderFilesystem(
-  name: string,
-  folder: SkillFolderOptions,
-  context: WorkspaceMountContext,
+  folder: ResolvedDatabricksWorkspacePath,
+  context: DatabricksWorkspaceContext,
+  cacheConfig: DatabricksWorkspaceCache | undefined,
   cache: {
     client: WorkspaceClient | undefined;
-    host: string | undefined;
-    userKey: string | undefined;
+    fileSystemCache: FileSystemCache | undefined;
   },
 ): Promise<
   | {
-      cacheKey?: string;
       filesystem: WorkspaceFilesystem;
-      skillSource: SkillCatalogueSource;
+      root?: string;
     }
   | undefined
 > {
-  if (folder.filesystem !== undefined) {
-    const filesystem = await resolveSkillFolderValue(folder.filesystem, context);
-    return filesystem
-      ? {
-          filesystem,
-          skillSource: mastraSkillSource(
-            object.toStableKey({
-              id: filesystem.id,
-              name,
-              provider: filesystem.provider,
-            }),
-            filesystem,
-          ),
-        }
-      : undefined;
-  }
   // A path mount needs the request's OBO client to reach the workspace.
-  if (folder.path === undefined || !cache.client || !cache.host || !cache.userKey) {
+  if (!cache.client) {
     logger.debug("skill-folder:skipped", {
-      name,
-      reason: folder.path === undefined ? "no-location" : "missing-obo-client",
+      path: folder.path,
+      reason: "missing-obo-client",
     });
     return undefined;
   }
-  const root = stringUtils.trimToNull(await resolveSkillFolderValue(folder.path, context));
+  const root = stringUtils.trimToNull(folder.path);
   if (!root) return undefined;
-  return databricksFilesystem(cache.client, root, folder.writable !== true, {
-    host: cache.host,
-    userKey: cache.userKey,
-  });
+  const writable = folder.writable ?? isWorkspaceRoot(root);
+  const cacheOptions = cache.fileSystemCache
+    ? await resolveFileCacheOptions(
+        cacheConfig,
+        context,
+        root,
+        folder.readable === false ? [] : (folder.skills ?? ["."]),
+      )
+    : undefined;
+  const resolved = await databricksFilesystem(
+    cache.client,
+    root,
+    !writable,
+    folder.createRoot ?? folder.writable === true,
+    cache.fileSystemCache,
+    cacheOptions,
+    {
+      ...(folder.description ? { description: folder.description } : {}),
+      ...(folder.displayName ? { displayName: folder.displayName } : {}),
+    },
+  );
+  return resolved ? { ...resolved, root } : undefined;
 }
 
-/** Read a {@link SkillFolderValue}, calling it when it is a per-request resolver. */
-function resolveSkillFolderValue<T>(
-  value: SkillFolderValue<T>,
-  context: WorkspaceMountContext,
-): T | undefined | Promise<T | undefined> {
+async function resolveCacheConfig(
+  value: DatabricksWorkspaceCache | undefined,
+  context: DatabricksWorkspaceContext,
+): Promise<
+  | boolean
+  | DatabricksWorkspaceCacheFilter
+  | readonly DatabricksWorkspaceCacheFilter[]
+  | undefined
+> {
   return typeof value === "function"
-    ? (value as (context: WorkspaceMountContext) => T | undefined | Promise<T | undefined>)(context)
+    ? value(context)
     : value;
 }
 
+function requestContextValues(requestContext: RequestContext | undefined): Record<string, unknown> {
+  return requestContext?.toJSON() ?? {};
+}
+
+function resolveHomePath(
+  input: string | undefined,
+  requestContext: Record<string, unknown>,
+): string | undefined {
+  const value = stringUtils.trimToNull(input);
+  if (!value || (value !== "~" && !value.startsWith("~/"))) return value ?? undefined;
+  const emailValue = requestContext[MASTRA_USER_EMAIL_KEY];
+  const email = typeof emailValue === "string" ? stringUtils.trimToNull(emailValue) : undefined;
+  if (!email) return undefined;
+  const home = personalWorkspacePath(email);
+  return value === "~" ? home : `${home}/${value.slice(2)}`;
+}
+
+function toPolicyArray<T>(value: T | readonly T[] | undefined): readonly T[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? (value as readonly T[]) : [value as T];
+}
+
+function cacheFilterMatches(
+  policy: DatabricksWorkspaceCacheFilter,
+  operation: CacheableFileSystemOperation,
+  path: string,
+  requestContext: Record<string, unknown>,
+  root?: string,
+): boolean {
+  const operations = toPolicyArray(policy.operations ?? CACHEABLE_FILESYSTEM_OPERATIONS);
+  if (!operations.includes(operation)) return false;
+  if (policy.paths === undefined) return true;
+  const inputs: PathMatchInput[] = [];
+  for (const input of toPolicyArray<PathMatchInput>(policy.paths)) {
+    if (typeof input !== "string") {
+      inputs.push(input);
+      continue;
+    }
+    const expanded = resolveHomePath(input, requestContext);
+    if (!expanded) continue;
+    inputs.push(
+      !root || posixPath.isAbsolute(expanded) || expanded.startsWith("**")
+        ? expanded
+        : `${posixPath.normalizeRoot(root)}/${expanded.replace(/^\.\//, "")}`,
+    );
+  }
+  return inputs.length > 0 && match.toPathMatcher(...inputs)(path);
+}
+
+async function resolveFileCacheOptions(
+  configured: DatabricksWorkspaceCache | undefined,
+  context: DatabricksWorkspaceContext,
+  root: string,
+  skillPaths: readonly string[],
+): Promise<FileSystemCacheOptions | undefined> {
+  const requestContext = requestContextValues(context.requestContext);
+  const resolved = await resolveCacheConfig(configured, context);
+  if (resolved === false) return undefined;
+  if (resolved === undefined || resolved === true) {
+    const roots = skillPaths.map((path) => mountedSkillPath(root, path));
+    return {
+      operations: CACHEABLE_FILESYSTEM_OPERATIONS,
+      filter: (operation, path) =>
+        operation !== "readFile" ||
+        roots.some((skillRoot) => posixPath.isWithinRoot(skillRoot, path)),
+    };
+  }
+  const policies = toPolicyArray(resolved);
+  if (policies.length === 0) return undefined;
+  const operations = [
+    ...new Set(
+      policies.flatMap((policy) =>
+        toPolicyArray(policy.operations ?? CACHEABLE_FILESYSTEM_OPERATIONS),
+      ),
+    ),
+  ];
+  return {
+    operations,
+    filter: (operation, path) =>
+      policies.some((policy) =>
+        cacheFilterMatches(
+          policy,
+          operation,
+          path,
+          requestContext,
+          root,
+        ),
+      ),
+  };
+}
+
 /**
- * Fill in `id` and `name` when either is omitted on {@link CreateWorkspaceOptions}.
+ * Fill in `id` and `name` when either is omitted on {@link DatabricksWorkspaceOptions}.
  * Slugifies `name` into `id`; tokenizes `id` into a display `name`.
  */
-function resolveWorkspaceIdentity(options: CreateWorkspaceOptions): {
+function resolveWorkspaceIdentity(options: DatabricksWorkspaceOptions): {
   id: string;
   name: string;
 } {
@@ -555,29 +834,58 @@ function resolveWorkspaceIdentity(options: CreateWorkspaceOptions): {
 
 /** Collect the skill-folder resolver and any caller-supplied ones. */
 function buildMountResolvers(
-  skillFolders: Record<string, SkillFolderOptions>,
-  mounts: WorkspaceMountResolver[] | undefined,
+  paths: readonly DatabricksWorkspacePathValue[],
+  mounts: Record<string, WorkspaceFilesystem> | undefined,
+  localMounts: WorkspaceMountResolver[],
+  filesCache: FilesCacheExports | undefined,
+  cacheConfig: DatabricksWorkspaceCache | undefined,
 ): WorkspaceMountResolver[] {
   const resolvers: WorkspaceMountResolver[] = [];
-  const folderCount = Object.keys(skillFolders).length;
-  if (folderCount > 0) {
-    resolvers.push((context) => resolveSkillFolderMounts(skillFolders, context));
-  }
-  if (mounts?.length) {
-    resolvers.push(...mounts);
+  const pathCount = paths.length;
+  if (pathCount > 0) {
+    resolvers.push((context) =>
+      resolveSkillFolderMounts(paths, context, filesCache, cacheConfig),
+    );
   }
+  if (mounts && Object.keys(mounts).length > 0) resolvers.push(() => ({ mounts }));
+  resolvers.push(...localMounts);
   logger.debug("mounts:resolvers", {
-    skillFolderCount: folderCount,
-    customResolverCount: mounts?.length ?? 0,
+    pathCount,
+    customMountCount: Object.keys(mounts ?? {}).length,
+    localMountCount: localMounts.length,
     totalResolverCount: resolvers.length,
   });
   return resolvers;
 }
 
+/** Stable user-scoped local storage under the host operating system's temp directory. */
+function userTempFilesystem(
+  context: DatabricksWorkspaceContext,
+  workspacePath: string,
+): WorkspaceFilesystem {
+  const userKey = resolveUserKey(context.requestContext);
+  const digest = createHash("sha256")
+    .update(object.toStableKey({ package: "@dbx-tools/appkit-mastra", userKey }))
+    .digest("hex")
+    .slice(0, 16);
+  const normalized = posixPath.normalizeRoot(workspacePath);
+  const relative = normalized === SCRATCH_MOUNT ? "" : normalized.slice(`${SCRATCH_MOUNT}/`.length);
+  const source = new LocalFileSystem({
+    root: join(tmpdir(), "dbx-tools", "mastra", digest, relative),
+    readOnly: false,
+    createRoot: true,
+  });
+  return filesystems(source, {
+    displayName: "Temporary Files",
+    description:
+      "User-scoped temporary files retained while the host keeps its ephemeral temp storage.",
+  });
+}
+
 /** Mount startup-provisioned local skill roots into Mastra's workspace filesystem. */
 function localSkillMountResolvers(paths: readonly string[]): WorkspaceMountResolver[] {
-  return [...new Set(paths.map((path) => path.trim()).filter(Boolean))].map((root, index) => {
-    const mount = `/remote-skills/${index}`;
+  return [...new Set(paths.map((path) => path.trim()).filter(Boolean))].map((root) => {
+    const mount = posixPath.normalizeRoot(root);
     const source = new LocalFileSystem({
       root,
       readOnly: true,
@@ -586,51 +894,11 @@ function localSkillMountResolvers(paths: readonly string[]): WorkspaceMountResol
     const filesystem = filesystems(source, { readOnly: true });
     return () => ({
       mounts: { [mount]: filesystem },
-      skillSources: [sharedSkillSource(object.toStableKey({ mount, root }), source)],
       skillPaths: [mount],
-      cacheKey: object.toStableKey({ mount, root }),
     });
   });
 }
 
-/** Adapt a portable dbx-tools filesystem to catalogue discovery callbacks. */
-function sharedSkillSource(id: string, filesystem: FileSystem): SkillCatalogueSource {
-  return {
-    id,
-    async list(path) {
-      await filesystem.init();
-      return (await filesystem.readdir(path)).flatMap((entry) =>
-        entry.type === "file" || entry.type === "directory"
-          ? [
-              {
-                name: entry.name,
-                type: entry.type,
-                ...(entry.size !== undefined ? { size: entry.size } : {}),
-                ...(entry.metadata ? { metadata: entry.metadata } : {}),
-              },
-            ]
-          : [],
-      );
-    },
-    async read(path) {
-      await filesystem.init();
-      return filesystem.readFile(path, { encoding: "utf8" });
-    },
-  };
-}
-
-/** Adapt an arbitrary Mastra filesystem when no portable source is available. */
-function mastraSkillSource(id: string, filesystem: WorkspaceFilesystem): SkillCatalogueSource {
-  return {
-    id,
-    list: (path) => filesystem.readdir(path),
-    async read(path) {
-      const value = await filesystem.readFile(path, { encoding: "utf8" });
-      return typeof value === "string" ? value : value.toString("utf8");
-    },
-  };
-}
-
 /**
  * Gate skill-folder mounts on the request's token.
  *
@@ -642,53 +910,49 @@ function shouldMountSkillFolders(requestContext: RequestContext): boolean {
   return hasWorkspaceFileScope(requestContext);
 }
 
-/** Read the trimmed OBO user email stamped on {@link MASTRA_USER_EMAIL_KEY}. */
-function resolveScopedEmail(requestContext: RequestContext | undefined): string | undefined {
-  return stringUtils.trimToNull(requestContext?.get(MASTRA_USER_EMAIL_KEY)) ?? undefined;
-}
-
 /**
- * Wrap a {@link DatabricksFileSystem} as a Mastra filesystem. When the root is
- * missing (and {@link readOnly} so we will not create it), fall back to
- * {@link scratchFilesystem} so skill scans still have a writable local mount.
+ * Wrap a {@link DatabricksFileSystem} as a Mastra filesystem. Missing or
+ * inaccessible roots return `undefined` so other accessible roots remain
+ * usable.
  */
 async function databricksFilesystem(
   client: WorkspaceClient,
   root: string,
   readOnly: boolean = true,
-  cache: { host: string; userKey: string },
+  createRoot: boolean = !readOnly,
+  fileSystemCache?: FileSystemCache,
+  cacheOptions?: FileSystemCacheOptions,
+  adapterOptions: Pick<MastraFileSystemAdapterOptions, "description" | "displayName"> = {},
 ): Promise<
-  {
-    cacheKey: string;
-    filesystem: WorkspaceFilesystem;
-    skillSource: SkillCatalogueSource;
-  }
+  | {
+      filesystem: WorkspaceFilesystem;
+    }
   | undefined
 > {
+  const initialClient = workspaceClient.toLegacyWorkspaceClient(client);
   const fs = new DatabricksFileSystem({
-    client: workspaceClient.toLegacyWorkspaceClient(client),
+    client: () => {
+      try {
+        return workspaceClient.toLegacyWorkspaceClient(getExecutionContext().client);
+      } catch {
+        return initialClient;
+      }
+    },
     root,
     readOnly,
-    createRoot: !readOnly,
-  });
-  const cacheKey = object.toStableKey({
-    host: cache.host,
-    readOnly,
-    root,
-    userKey: cache.userKey,
+    createRoot,
   });
-  const filesystem = filesystems(fs, { readOnly });
+  const cached =
+    fileSystemCache && cacheOptions ? sharedFS.cache(fs, fileSystemCache, cacheOptions) : fs;
+  const source = verifyFirstFileSystemAccess(cached, () => fs.stat("."), root);
+  const filesystem = filesystems(source, { ...adapterOptions, readOnly });
   try {
     await filesystem.init();
     if (await filesystem.exists(".")) {
-      return {
-        cacheKey,
-        filesystem,
-        skillSource: sharedSkillSource(cacheKey, fs),
-      };
+      return { filesystem };
     }
   } catch (err) {
-    logger.debug("databricks-mount:scratch-fallback", {
+    logger.debug("databricks-mount:skipped", {
       root,
       readOnly,
       error: errorUtils.errorMessage(err),
@@ -697,19 +961,86 @@ async function databricksFilesystem(
   return undefined;
 }
 
+function verifyFirstFileSystemAccess<TFileSystem extends FileSystem>(
+  filesystem: TFileSystem,
+  readProbe: () => Promise<unknown>,
+  root: string,
+): TFileSystem {
+  let readCheck: Promise<void> | undefined;
+  let writeVerified = false;
+  const boundMethods = new Map<PropertyKey, unknown>();
+  const readOperations = new Set<PropertyKey>(["exists", "readFile", "readdir", "stat"]);
+  const writeOperations = new Set<PropertyKey>([
+    "appendFile",
+    "copyFile",
+    "deleteFile",
+    "mkdir",
+    "moveFile",
+    "rmdir",
+    "writeFile",
+  ]);
+  const verifyRead = async (): Promise<void> => {
+    readCheck ??= Promise.resolve(readProbe()).then(() => undefined);
+    try {
+      await readCheck;
+    } catch (error) {
+      readCheck = undefined;
+      logger.debug("databricks-mount:read-check-failed", {
+        root,
+        error: errorUtils.errorMessage(error),
+      });
+      throw error;
+    }
+  };
+
+  return new Proxy(filesystem, {
+    get(target, property) {
+      const value = Reflect.get(target, property, target);
+      if (typeof value !== "function") return value;
+      if (boundMethods.has(property)) return boundMethods.get(property);
+      const delegated = value.bind(target) as (...args: unknown[]) => unknown;
+      let method = delegated;
+      if (readOperations.has(property)) {
+        method = async (...args: unknown[]) => {
+          await verifyRead();
+          return delegated(...args);
+        };
+      } else if (writeOperations.has(property)) {
+        method = async (...args: unknown[]) => {
+          try {
+            const result = await delegated(...args);
+            if (!writeVerified) {
+              writeVerified = true;
+              logger.debug("databricks-mount:write-check-passed", { root });
+            }
+            return result;
+          } catch (error) {
+            if (!writeVerified) {
+              logger.debug("databricks-mount:write-check-failed", {
+                root,
+                error: errorUtils.errorMessage(error),
+              });
+            }
+            throw error;
+          }
+        };
+      }
+      boundMethods.set(property, method);
+      return method;
+    },
+  });
+}
+
 /**
  * Run every mount resolver for one request and merge mounts plus skill paths.
  * Later resolvers overwrite mount keys from earlier ones.
  */
 async function resolveWorkspaceContribution(
   resolvers: WorkspaceMountResolver[],
-  context: WorkspaceMountContext,
+  context: DatabricksWorkspaceContext,
 ): Promise<WorkspaceMountContribution> {
   const mounts: Record<string, WorkspaceFilesystem> = {};
-  const skillSources: SkillCatalogueSource[] = [];
   const skillPaths: string[] = [];
-  const cacheKeys: string[] = [];
-  let cacheable = true;
 
   for (const [index, resolver] of resolvers.entries()) {
     const contribution = await resolver(context);
@@ -719,16 +1050,9 @@ async function resolveWorkspaceContribution(
       skillPaths: contribution.skillPaths ?? [],
     });
     Object.assign(mounts, contribution.mounts);
-    if (Object.keys(contribution.mounts).length > 0) {
-      if (contribution.cacheKey) cacheKeys.push(contribution.cacheKey);
-      else cacheable = false;
-    }
     if (contribution.skillPaths?.length) {
       skillPaths.push(...contribution.skillPaths);
     }
-    if (contribution.skillSources?.length) {
-      skillSources.push(...contribution.skillSources);
-    }
   }
 
   logger.debug("mounts:merged", {
@@ -738,45 +1062,76 @@ async function resolveWorkspaceContribution(
 
   return {
     mounts,
-    skillSources,
     skillPaths,
-    ...(cacheable && cacheKeys.length > 0
-      ? { cacheKey: object.toStableKey({ mounts: Object.keys(mounts), sources: cacheKeys }) }
-      : {}),
   };
 }
 
 /**
  * Dynamic filesystem resolver passed to Mastra {@link Workspace}.
  *
- * Returns a {@link CompositeFilesystem} when any mount resolved; otherwise a
- * fresh {@link scratchFilesystem} so Mastra always has a writable local root.
+ * Returns a {@link CompositeFilesystem} over every path that resolved for the
+ * request. An empty composite exposes no implicit local storage.
  */
 async function resolveWorkspaceFilesystem(
-  resolveContribution: (context: WorkspaceMountContext) => Promise<WorkspaceMountContribution>,
-  context: WorkspaceMountContext,
+  resolveContribution: (context: DatabricksWorkspaceContext) => Promise<WorkspaceMountContribution>,
+  context: DatabricksWorkspaceContext,
+  filesCache?: FilesCacheExports,
+  sourceKey?: string,
 ): Promise<WorkspaceFilesystem> {
-  const { cacheKey, mounts } = await resolveContribution(context);
+  const { mounts } = await resolveContribution(context);
   const mountKeys = Object.keys(mounts);
   if (mountKeys.length === 0) {
-    logger.debug("filesystem:scratch", {
+    logger.debug("filesystem:empty", {
       hasRequestContext: Boolean(context.requestContext),
     });
-    return scratchFilesystem();
+    return filesystems(new MemoryFileSystem({ root: "/", readOnly: true }), {
+      readOnly: true,
+    });
   }
   logger.debug("filesystem:composite", { mountKeys });
-  if (!cacheKey) return new CompositeFilesystem({ mounts });
-  const existing = scopedWorkspaceFilesystems.get(cacheKey);
-  if (existing) return existing;
-  const filesystem = new CompositeFilesystem({ mounts });
-  scopedWorkspaceFilesystems.set(cacheKey, filesystem);
-  return filesystem;
+  const load = () => new MountedCompositeFilesystem({ mounts });
+  if (!filesCache) return load();
+  const scoped = await resolveFilesCacheScope(context);
+  if (!scoped) return load();
+  return filesCache.forFileSystem(scoped.scope, { paths: mountKeys, key: sourceKey }, load);
+}
+
+/**
+ * Expand skill roots into concrete skill directories and keep the first
+ * same-named directory. Mastra still owns parsing, indexing, and refreshes,
+ * while earlier configured roots retain precedence over later roots.
+ */
+async function resolveDistinctSkillPaths(
+  filesystem: WorkspaceFilesystem,
+  roots: readonly string[],
+): Promise<string[]> {
+  const selected = new Map<string, string>();
+  for (const root of roots) {
+    try {
+      const entries = await filesystem.readdir(root);
+      if (entries.some((entry) => entry.type === "file" && entry.name === "SKILL.md")) {
+        const name = posixPath.basename(root);
+        if (!selected.has(name)) selected.set(name, root);
+        continue;
+      }
+      for (const entry of entries) {
+        if (entry.type !== "directory" || selected.has(entry.name)) continue;
+        selected.set(entry.name, posixPath.join(root, entry.name));
+      }
+    } catch (error) {
+      logger.debug("skill-root:skipped", {
+        root,
+        error: errorUtils.errorMessage(error),
+      });
+    }
+  }
+  return [...selected.values()];
 }
 
 /** Memoize one complete mount contribution for each request context. */
 function contributionResolver(
   resolvers: WorkspaceMountResolver[],
-): (context: WorkspaceMountContext) => Promise<WorkspaceMountContribution> {
+): (context: DatabricksWorkspaceContext) => Promise<WorkspaceMountContribution> {
   const scoped = new WeakMap<RequestContext, Promise<WorkspaceMountContribution>>();
   let unscoped: Promise<WorkspaceMountContribution> | undefined;
   return (context) => {
@@ -791,22 +1146,3 @@ function contributionResolver(
     return pending;
   };
 }
-
-/** Resolve one semantic catalogue owner from a request's ordered skill roots. */
-function buildSkillCatalogueResolver(
-  resolveContribution: (context: WorkspaceMountContext) => Promise<WorkspaceMountContribution>,
-  ttlMs: number | undefined,
-): SkillCatalogueResolver {
-  return async ({ requestContext }) => {
-    const contribution = await resolveContribution({ requestContext });
-    const user = requestContext?.get(MASTRA_USER_KEY) as User | undefined;
-    const client = user?.executionContext.client as WorkspaceClient | undefined;
-    const host = client ? (await client.config.getHost()).toString() : "local";
-    return workspaceSkillCatalogue({
-      host,
-      sources: contribution.skillSources ?? [],
-      ttlMs,
-      userKey: user?.id ?? "service",
-    });
-  };
-}