@dbx-tools/appkit-mastra 0.9.95 → 0.9.105

package/src/workspaces.ts

@@ -1,16 +1,10 @@
 /**
  * Mastra workspace factory for Databricks Apps.
  *
- * Builds a {@link Workspace} with Databricks Sandbox command execution, an
- * isolated `/tmp` scratch mount, and 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}; inaccessible roots are skipped independently.
@@ -19,9 +13,11 @@
  */
 
 import { createHash } from "node:crypto";
-import { ConfigurationError, createWorkspaceClient, getExecutionContext } from "@databricks/appkit";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ConfigurationError, createWorkspaceClient } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
-import { pluginRegistry } from "@dbx-tools/appkit";
+import { appkit, pluginRegistry } from "@dbx-tools/appkit";
 import {
   filesCache as filesCachePlugin,
   type FilesCacheExports,
@@ -29,18 +25,25 @@ import {
 } 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 { fs as sharedFS, posixPath, type FileSystemCache } from "@dbx-tools/shared-fs";
+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 {
-  WORKSPACE_TOOLS,
   Workspace,
   type SkillsResolver,
+  type WorkspaceConfig,
   type WorkspaceFilesystem,
   type WorkspaceSandbox,
   type WorkspaceSandboxResolver,
-  type ToolConfigWithArgsContext,
-  type WorkspaceToolConfig,
   type WorkspaceToolsConfig,
 } from "@mastra/core/workspace";
 
@@ -54,7 +57,6 @@ import {
 import {
   filesystems,
   MountedCompositeFilesystem,
-  scratchFilesystem,
   type MastraFileSystemAdapterOptions,
 } from "./filesystems.ts";
 import { MontySandbox } from "./monty-sandbox.ts";
@@ -66,35 +68,30 @@ import { ORGANIZATION_ASSISTANT_PATH, personalWorkspacePath } from "./skill-path
 /** 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");
+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 root mounted at its actual path. */
-  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. */
@@ -124,23 +121,62 @@ export interface SkillFolderOptions {
   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>;
   /** Paths within the composite namespace where `SKILL.md` files are scanned. */
   skillPaths?: 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 = "organization-skills" | "personal-skills";
-
 /**
- * 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.
  */
@@ -152,35 +188,28 @@ 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;
-  /** Additional native Mastra workspace tool configuration and overrides. */
-  tools?: WorkspaceToolsConfig;
+  /** 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;
-  /** Enable BM25 keyword search over indexed workspace content. */
-  bm25?: boolean;
   /**
    * Command sandbox. Defaults to Monty. Pass `"databricks"` or an options
    * object for Databricks Sandbox, `false` to disable command execution, or an
@@ -200,97 +229,78 @@ export interface CreateWorkspaceOptions {
 /* ------------------------------- defaults ------------------------------- */
 
 /**
- * The skill folders every workspace starts with.
- *
- * - `organization-skills` - `/Workspace/.assistant` with `skills`; write
- *   attempts require approval and remain subject to Databricks permissions.
- * - `personal-skills` - the requesting user's `/Workspace/Users/<email>` root
- *   with `.assistant/skills`, writable and skipped without an email.
+ * Default Databricks paths for shared and current-user Agent Skills.
  */
-export const DEFAULT_SKILL_FOLDERS: Readonly<Record<DefaultSkillFolderName, SkillFolderOptions>> = {
-  "organization-skills": {
-    description: "Organization skills shared with everyone in this Databricks workspace.",
-    displayName: "Organization Skills",
+export const DEFAULT_DATABRICKS_WORKSPACE_PATHS: readonly DatabricksWorkspacePathOptions[] = [
+  {
     path: ORGANIZATION_ASSISTANT_PATH,
     readable: true,
     skills: ["skills"],
     writable: true,
     createRoot: false,
   },
-  "personal-skills": {
-    description: "Your Databricks workspace home directory for personal files and skills.",
-    displayName: "Home",
-    path: ({ requestContext }) => {
-      const email = resolveScopedEmail(requestContext);
-      return email ? personalWorkspacePath(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: {
- *     "organization-skills": {
- *       path: "/Workspace/Shared/.assistant",
- *       skills: ["skills"],
- *     },
- *     "personal-skills": 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 =
-    filesCache !== undefined &&
-    (options.mounts?.length ?? 0) === 0 &&
-    Object.values(skillFolders).every(
-      (folder) =>
-        typeof folder.filesystem !== "function" &&
-        !(typeof folder.path === "function" && folder.mount !== undefined),
-    );
+    mountFilesCache !== undefined &&
+    typeof configuredCache !== "function" &&
+    paths.every((path) => typeof path !== "function");
   const resolvers = buildMountResolvers(
-    skillFolders,
-    [...(options.mounts ?? []), ...localSkillMountResolvers(extraSkillPaths)],
-    filesCache,
+    paths,
+    options.mounts,
+    localSkillMountResolvers(extraSkillPaths),
+    mountFilesCache,
+    configuredCache,
   );
   const resolveContribution = contributionResolver(resolvers);
-  const resolveFilesystem = (context: WorkspaceMountContext) =>
+  const resolveFilesystem = (context: DatabricksWorkspaceContext) =>
     resolveWorkspaceFilesystem(
       resolveContribution,
       context,
-      retainFilesystemSource ? filesCache : undefined,
+      retainFilesystemSource ? mountFilesCache : undefined,
+      filesystemSourceKey,
     );
   const skills: SkillsResolver =
     options.skills ??
@@ -303,15 +313,15 @@ export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace
       );
     });
   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,
     bm25,
@@ -319,7 +329,19 @@ export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace
     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: resolveFilesystem,
@@ -337,75 +359,50 @@ export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace
       : {}),
     bm25,
     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;
 }
 
+/** @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,
+    enabled: true,
+    requireApproval: false,
     ...configured,
-    ...mergedTools,
   };
 }
+
 function resolveWorkspaceSandbox(
   selection: WorkspaceSandboxSelection | undefined,
   workspaceId: string,
@@ -484,7 +481,7 @@ function hasWorkspaceFileScope(requestContext: RequestContext | undefined): bool
 }
 
 /** Resolve the request client and authorization-safe files-cache scope. */
-async function resolveFilesCacheScope(context: WorkspaceMountContext): Promise<
+async function resolveFilesCacheScope(context: DatabricksWorkspaceContext): Promise<
   | {
       client: WorkspaceClient;
       scope: FilesCacheScope;
@@ -532,38 +529,52 @@ function isWorkspaceRoot(root: string): boolean {
  * 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 skillPaths: 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 scoped = await resolveFilesCacheScope(context);
+  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;
 
-  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,
       fileSystemCache,
     });
     if (!resolved) continue;
-    const mount = folder.mount ?? resolved.root ?? `/${name}`;
+    const mount = configured.mount ?? resolved.root;
+    if (!mount) {
+      logger.debug("workspace-path:skipped", { index, reason: "missing-mount" });
+      continue;
+    }
     mounts[mount] = resolved.filesystem;
-    if (folder.readable !== false) {
-      skillPaths.push(...(folder.skills ?? ["."]).map((path) => mountedSkillPath(mount, path)));
+    if (configured.readable !== false) {
+      skillPaths.push(...(configured.skills ?? ["."]).map((path) => mountedSkillPath(mount, path)));
     }
   }
 
@@ -578,14 +589,43 @@ async function resolveSkillFolderMounts(
   };
 }
 
+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 } : {}),
+  };
+}
+
 /**
  * Resolve one skill folder to a Mastra filesystem, or `undefined` to skip it
  * for this request.
  */
 async function resolveSkillFolderFilesystem(
-  name: string,
-  folder: SkillFolderOptions,
-  context: WorkspaceMountContext,
+  folder: ResolvedDatabricksWorkspacePath,
+  context: DatabricksWorkspaceContext,
+  cacheConfig: DatabricksWorkspaceCache | undefined,
   cache: {
     client: WorkspaceClient | undefined;
     fileSystemCache: FileSystemCache | undefined;
@@ -597,32 +637,32 @@ async function resolveSkillFolderFilesystem(
     }
   | undefined
 > {
-  if (folder.filesystem !== undefined) {
-    const filesystem = await resolveSkillFolderValue(folder.filesystem, context);
-    return filesystem
-      ? {
-          filesystem,
-        }
-      : undefined;
-  }
   // A path mount needs the request's OBO client to reach the workspace.
-  if (folder.path === undefined || !cache.client) {
+  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;
   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,
-    folder.readable === false ? [] : (folder.skills ?? ["."]),
+    cacheOptions,
     {
       ...(folder.description ? { description: folder.description } : {}),
       ...(folder.displayName ? { displayName: folder.displayName } : {}),
@@ -631,21 +671,103 @@ async function resolveSkillFolderFilesystem(
   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> {
-  return typeof value === "function"
-    ? (value as (context: WorkspaceMountContext) => T | undefined | Promise<T | undefined>)(context)
-    : value;
+async function resolveCacheConfig(
+  value: DatabricksWorkspaceCache | undefined,
+  context: DatabricksWorkspaceContext,
+): Promise<
+  boolean | DatabricksWorkspaceCacheFilter | readonly DatabricksWorkspaceCacheFilter[] | undefined
+> {
+  return typeof value === "function" ? 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;
 } {
@@ -662,30 +784,49 @@ 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[] = [scratchMountResolver()];
-  const folderCount = Object.keys(skillFolders).length;
-  if (folderCount > 0) {
-    resolvers.push((context) => resolveSkillFolderMounts(skillFolders, context, filesCache));
-  }
-  if (mounts?.length) {
-    resolvers.push(...mounts);
+  const resolvers: WorkspaceMountResolver[] = [];
+  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;
 }
 
-/** Contribute one isolated local scratch filesystem at `/tmp`. */
-function scratchMountResolver(): WorkspaceMountResolver {
-  return () => ({
-    mounts: { [SCRATCH_MOUNT]: scratchFilesystem() },
+/** 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.",
   });
 }
 
@@ -717,15 +858,10 @@ 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. Missing or
- * inaccessible roots return `undefined` so the independent `/tmp` mount and
- * any other accessible roots remain usable.
+ * inaccessible roots return `undefined` so other accessible roots remain
+ * usable.
  */
 async function databricksFilesystem(
   client: WorkspaceClient,
@@ -733,7 +869,7 @@ async function databricksFilesystem(
   readOnly: boolean = true,
   createRoot: boolean = !readOnly,
   fileSystemCache?: FileSystemCache,
-  skillPaths: readonly string[] = [],
+  cacheOptions?: FileSystemCacheOptions,
   adapterOptions: Pick<MastraFileSystemAdapterOptions, "description" | "displayName"> = {},
 ): Promise<
   | {
@@ -741,22 +877,15 @@ async function databricksFilesystem(
     }
   | undefined
 > {
-  const initialClient = workspaceClient.toLegacyWorkspaceClient(client);
   const fs = new DatabricksFileSystem({
-    client: () => {
-      try {
-        return workspaceClient.toLegacyWorkspaceClient(getExecutionContext().client);
-      } catch {
-        return initialClient;
-      }
-    },
+    client: () => workspaceClient.toLegacyWorkspaceClient(requestWorkspaceClient(client)),
     root,
     readOnly,
     createRoot,
   });
-  const source = fileSystemCache
-    ? sharedFS.cache(fs, fileSystemCache, { readFilePaths: skillPaths })
-    : fs;
+  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();
@@ -773,13 +902,100 @@ async function databricksFilesystem(
   return undefined;
 }
 
+/** @internal Keep service context from replacing the request-scoped workspace client. */
+export function requestWorkspaceClient(
+  initialClient: WorkspaceClient,
+  executionContext: ReturnType<
+    typeof appkit.tryGetExecutionContext
+  > = appkit.tryGetExecutionContext(),
+): WorkspaceClient {
+  if (
+    executionContext &&
+    "isUserContext" in executionContext &&
+    executionContext.isUserContext === true
+  ) {
+    return executionContext.client;
+  }
+  return initialClient;
+}
+
+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 skillPaths: string[] = [];
@@ -811,34 +1027,37 @@ async function resolveWorkspaceContribution(
 /**
  * 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 { 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 });
   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 }, 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 organization roots retain precedence over personal roots.
+ * while earlier configured roots retain precedence over later roots.
  */
 async function resolveDistinctSkillPaths(
   filesystem: WorkspaceFilesystem,
@@ -870,7 +1089,7 @@ async function resolveDistinctSkillPaths(
 /** 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) => {