@dbx-tools/appkit-mastra 0.9.106 → 0.9.110

package/src/remote-skills.ts

@@ -5,8 +5,8 @@
  * {@link AITOOLS_SOURCE} constant, a GitHub `owner/repo`, any git / GitLab URL,
  * or a direct download URL - and optional per-source policy.
  * {@link provisionRemoteSkills} materializes every source into a local
- * `SKILL.md` tree at app boot and returns the directories to hand Mastra as
- * extra skill scan paths.
+ * `SKILL.md` tree at app boot and returns read-only backing directories plus
+ * their stable virtual workspace mounts.
  *
  * Resolution per source, in order:
  *
@@ -43,8 +43,8 @@
  * identity cannot WRITE the destination, which is the normal case for a
  * Databricks App service principal against the admin-owned shared tree (see
  * {@link openWritableWorkspace}) - the tree is written under
- * {@link localFS.tmpFS} and returned as an extra local skill path for the
- * current process. Storage location degrades; the skills themselves do not.
+ * {@link localFS.tmpFS} and exposed through a stable read-only virtual mount
+ * for the current process. Storage location degrades; the skills themselves do not.
  *
  * @module
  */
@@ -100,6 +100,12 @@ const DEFAULT_DOWNLOAD_TIMEOUT_MS = 60_000;
 /** Stable temp directory holding one rebuilt skill tree per remote source. */
 const LOCAL_SKILLS_DIR = "mastra-local-skills";
 
+/** Virtual workspace path reserved for locally provisioned Databricks AI Tools. */
+export const AITOOLS_SKILLS_MOUNT = "/.databricks/skills";
+
+/** Virtual workspace root for every other locally provisioned remote source. */
+export const REMOTE_SKILLS_MOUNT = "/.skills";
+
 /**
  * Bookkeeping file written at the root of every provisioned skill tree, naming
  * when each source was last downloaded. A dotfile so the skill scanners, which
@@ -156,6 +162,8 @@ interface AiToolsManifest {
 export interface RemoteSkillSourceOptions {
   /** `"aitools"`, a GitHub shorthand, a git / GitLab URL, or a download URL. */
   source: net.UrlLike | AiToolsSource;
+  /** Stable virtual mount name under `/.skills`; generated from the source when omitted. */
+  name?: string;
   /** Install only these skill names from the source. */
   skills?: string | string[];
   /** Include experimental skills. `"aitools"` only. */
@@ -195,6 +203,14 @@ export type RemoteSkillsOption =
 /** A source entry with its `source` flattened to a plain string. */
 type NormalizedSource = Omit<RemoteSkillSourceOptions, "source"> & { source: string };
 
+/** Read-only local backing storage exposed at a stable virtual workspace path. */
+export interface LocalSkillMount {
+  /** Physical local directory containing the provisioned `SKILL.md` tree. */
+  root: string;
+  /** Virtual path agents see inside the composed Mastra workspace. */
+  mountPath: string;
+}
+
 /** Top-level remote-skills provisioning options. */
 export interface ProvisionRemoteSkillsOptions {
   /** Sources to materialize at startup. */
@@ -226,11 +242,11 @@ export interface ProvisionRemoteSkillsOptions {
 /** What {@link provisionRemoteSkills} resolved. */
 export interface ProvisionedRemoteSkills {
   /**
-   * Extra LOCAL skill scan paths to hand Mastra (a temp dir per source that
-   * couldn't be written to Databricks). Empty when everything landed in the
-   * Databricks Assistant tree, which the built-in mount already scans.
+   * Extra read-only LOCAL skill mounts to hand Mastra when a source couldn't
+   * be written to Databricks. Physical temp/cache paths remain hidden behind
+   * stable virtual workspace paths.
    */
-  localSkillPaths: string[];
+  localSkillMounts: LocalSkillMount[];
   /** Absolute Databricks destination each source was written to, if any. */
   databricksBasePath?: string;
   /**
@@ -342,6 +358,29 @@ function cacheKey(sourceOptions: NormalizedSource): string {
   );
 }
 
+/** Stable virtual workspace path for one locally provisioned source. */
+function localSkillMountPath(sourceOptions: NormalizedSource, key: string): string {
+  if (isAiToolsSource(sourceOptions.source)) return AITOOLS_SKILLS_MOUNT;
+  const configuredName = stringUtils.trimToNull(sourceOptions.name);
+  const identifier = configuredName
+    ? stringUtils.toSlug(configuredName)
+    : stringUtils.toSlug(remoteSourceIdentifier(sourceOptions.source)) || "source";
+  if (!identifier) {
+    throw new Error(
+      `remote skill source name must contain letters or numbers: "${configuredName}"`,
+    );
+  }
+  return posix.join(REMOTE_SKILLS_MOUNT, configuredName ? identifier : `${identifier}-${key}`);
+}
+
+/** Human-readable source portion used by generated virtual mount identifiers. */
+function remoteSourceIdentifier(source: string): string {
+  const url = net.urlBuilder(source);
+  if (!url) return source;
+  const path = url.pathname.replace(/\.(git|md|zip|tar|tgz|gz)$/i, "");
+  return `${url.hostname}-${path}`;
+}
+
 /** The effective reuse window: per-source, then top-level, then seven days. */
 function resolveRefreshTtl(
   sourceOptions: NormalizedSource,
@@ -416,13 +455,13 @@ function localSkillsFS(key: string): LocalFileSystem {
  *
  * Writes each resolved `SKILL.md` tree to the Databricks user Assistant skills
  * folder when a writable workspace is available, else under
- * {@link localFS.tmpFS} returned in {@link ProvisionedRemoteSkills.localSkillPaths}.
+ * {@link localFS.tmpFS} returned in {@link ProvisionedRemoteSkills.localSkillMounts}.
  */
 export async function provisionRemoteSkills(
   option: RemoteSkillsOption | undefined,
 ): Promise<ProvisionedRemoteSkills> {
   const options = normalizeRemoteSkillsOption(option);
-  const empty: ProvisionedRemoteSkills = { localSkillPaths: [], skillNames: [] };
+  const empty: ProvisionedRemoteSkills = { localSkillMounts: [], skillNames: [] };
   if (!options) return empty;
 
   const failDefault = options.failOnError !== false;
@@ -437,7 +476,7 @@ export async function provisionRemoteSkills(
     : undefined;
   const databricksBasePath = destination ? requestedBasePath : undefined;
 
-  const localSkillPaths: string[] = [];
+  const localSkillMounts: LocalSkillMount[] = [];
   const skillNames: string[] = [];
   let staging: LocalFileSystem | undefined;
 
@@ -450,15 +489,16 @@ export async function provisionRemoteSkills(
         // Where this source's bookkeeping lives: the shared Databricks tree, or
         // the source's own stable local dir.
         const key = cacheKey(sourceOptions);
+        const mountPath = localSkillMountPath(sourceOptions, key);
         const cacheFS = destination ?? localSkillsFS(key);
         const metadata = await readMetadata(cacheFS);
         const cached = metadata?.sources[key];
         if (cached && isFresh(cached, resolveRefreshTtl(sourceOptions, options))) {
           skillNames.push(...cached.skills);
-          if (!destination) localSkillPaths.push(cacheFS.root);
+          if (!destination) localSkillMounts.push({ root: cacheFS.root, mountPath });
           logger.info("remote skill ready", {
             source: sourceOptions.source,
-            destination: databricksBasePath ?? cacheFS.root,
+            destination: databricksBasePath ?? mountPath,
             downloadedAt: cached.downloadedAt,
             skills: cached.skills,
             cached: true,
@@ -489,12 +529,15 @@ export async function provisionRemoteSkills(
           // mark a failed provision as fresh and suppress the retry for a day.
           await writeMetadata(destination, key, record);
         } else {
-          localSkillPaths.push(await persistLocally(key, staged, record));
+          localSkillMounts.push({
+            root: await persistLocally(key, staged, record),
+            mountPath,
+          });
         }
         skillNames.push(...record.skills);
         logger.info("remote skill installed", {
           source: sourceOptions.source,
-          destination: databricksBasePath ?? localSkillPaths.at(-1),
+          destination: databricksBasePath ?? localSkillMounts.at(-1)?.mountPath,
           skills: record.skills,
         });
       } catch (err) {
@@ -516,7 +559,22 @@ export async function provisionRemoteSkills(
     }
   }
 
-  return { localSkillPaths, databricksBasePath, skillNames };
+  assertUniqueLocalSkillMounts(localSkillMounts);
+  return { localSkillMounts, databricksBasePath, skillNames };
+}
+
+/** Fail before workspace composition when two sources claim one virtual mount. */
+function assertUniqueLocalSkillMounts(mounts: readonly LocalSkillMount[]): void {
+  const rootsByMount = new Map<string, string>();
+  for (const mount of mounts) {
+    const previousRoot = rootsByMount.get(mount.mountPath);
+    if (previousRoot && previousRoot !== mount.root) {
+      throw new Error(
+        `multiple remote skill sources resolve to virtual mount "${mount.mountPath}"; give each source a unique name`,
+      );
+    }
+    rootsByMount.set(mount.mountPath, mount.root);
+  }
 }
 
 /** Remove directories dropped by one source unless another source still owns them. */

package/src/sandbox.ts

@@ -68,7 +68,8 @@ export interface DatabricksSandboxOptions {
   commandTimeoutMs?: number;
   /**
    * Provider used only when Databricks Sandbox is definitively unavailable.
-   * Defaults to the Node Pydantic Monty runtime; `false` fails instead.
+   * Disabled by default. Pass `"monty"`, Monty options, or another Mastra
+   * sandbox to enable a fallback explicitly.
    */
   fallback?: false | "monty" | MontySandboxOptions | WorkspaceSandbox;
 }
@@ -123,7 +124,7 @@ export class DatabricksSandbox implements WorkspaceSandbox {
     this.inactivityTimeout = options.inactivityTimeout ?? DEFAULT_INACTIVITY_TIMEOUT;
     this.startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
     this.commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
-    this.fallbackConfig = options.fallback ?? "monty";
+    this.fallbackConfig = options.fallback ?? false;
   }
 
   get provider(): string {

package/src/workspaces.ts

@@ -60,6 +60,7 @@ import {
   type MastraFileSystemAdapterOptions,
 } from "./filesystems.ts";
 import { MontySandbox } from "./monty-sandbox.ts";
+import type { LocalSkillMount } from "./remote-skills.ts";
 import { DatabricksSandbox, type DatabricksWorkspaceSandboxOptions } from "./sandbox.ts";
 import { ORGANIZATION_ASSISTANT_PATH, personalWorkspacePath } from "./skill-paths.ts";
 
@@ -81,7 +82,7 @@ const databricksWorkspaceOptions = new WeakMap<Workspace, DatabricksWorkspaceOpt
 
 /* -------------------------------- types -------------------------------- */
 
-/** Per-request context for mount and skill-folder resolvers. */
+/** Per-request context for workspace path resolvers. */
 export interface DatabricksWorkspaceContext {
   requestContext?: RequestContext;
 }
@@ -97,13 +98,9 @@ export interface DatabricksWorkspacePathOptions {
   /** 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;
-  /**
-   * Skill roots relative to this filesystem root. Defaults to `["."]`.
-   * Each path is joined to the actual mount path before Mastra scans it.
+   * Skill paths relative to this included filesystem path. Omit for a
+   * file-only mount. Each entry is joined to the actual mount path before
+   * Mastra receives it.
    */
   skills?: readonly string[];
   /**
@@ -176,9 +173,9 @@ type WorkspaceMountResolver = (
 ) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
 
 /**
- * Sandbox selection for {@link databricksWorkspace}. Monty is the default;
- * `false` disables command execution, and a Mastra provider or resolver is an
- * explicit replacement.
+ * Sandbox selection for {@link databricksWorkspace}. Command execution is
+ * disabled by default; Monty, Databricks Sandbox, or a Mastra provider/resolver
+ * must be selected explicitly.
  */
 export type WorkspaceSandboxSelection =
   | false
@@ -204,26 +201,28 @@ export interface DatabricksWorkspaceOptions extends Omit<
   paths?: readonly DatabricksWorkspacePathValue[];
   /** Native Mastra filesystems composed beside the Databricks paths. */
   mounts?: Record<string, WorkspaceFilesystem>;
-  /** Replace the auto-built dynamic skills resolver. */
+  /** Native Mastra skill paths or resolver composed with path-declared skills. */
   skills?: SkillsResolver;
   /** 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
-   * explicit Mastra sandbox/provider resolver.
+   * Command sandbox. Disabled by default. Pass `"monty"`, `"databricks"`, or
+   * Databricks Sandbox options to enable one of the built-in providers, or pass
+   * an explicit Mastra sandbox/provider resolver.
    */
   sandbox?: WorkspaceSandboxSelection;
+  /** Add user-scoped `/tmp` only when no configured Databricks path mounts writable. */
+  fallbackToTmp?: boolean;
   /**
-   * Extra LOCAL skill roots mounted read-only for every request's skill discovery.
-   * Used by the plugin to surface remote skills provisioned to a local temp
-   * dir at startup (see `remote-skills.ts`). Databricks-hosted remote skills
-   * need no entry here - they land in the Assistant tree the built-in mount
-   * already scans.
+   * Extra LOCAL skill trees mounted read-only for every request's skill
+   * discovery. Used by the plugin to expose remote skills from local backing
+   * storage at stable virtual paths (see `remote-skills.ts`). Databricks-hosted
+   * remote skills need no entry here because the built-in Assistant mount
+   * already scans them.
    */
-  extraSkillPaths?: string[];
+  extraSkillMounts?: LocalSkillMount[];
 }
 
 /* ------------------------------- defaults ------------------------------- */
@@ -234,14 +233,12 @@ export interface DatabricksWorkspaceOptions extends Omit<
 export const DEFAULT_DATABRICKS_WORKSPACE_PATHS: readonly DatabricksWorkspacePathOptions[] = [
   {
     path: ORGANIZATION_ASSISTANT_PATH,
-    readable: true,
     skills: ["skills"],
     writable: true,
     createRoot: false,
   },
   {
     path: "~",
-    readable: true,
     skills: [".assistant/skills"],
     writable: true,
     createRoot: false,
@@ -279,7 +276,7 @@ export function databricksWorkspaceConfig(
   const filesystemSourceKey = `${id}:${++workspaceSourceSequence}`;
   const paths = resolveDatabricksWorkspacePaths(options);
   const configuredPaths = paths.length;
-  const extraSkillPaths = options.extraSkillPaths ?? [];
+  const extraSkillMounts = options.extraSkillMounts ?? [];
   const filesCache = pluginRegistry.instance(options.pluginContext, filesCachePlugin)?.exports();
   const configuredCache = options.cache;
   const mountFilesCache = configuredCache === false ? undefined : filesCache;
@@ -290,9 +287,10 @@ export function databricksWorkspaceConfig(
   const resolvers = buildMountResolvers(
     paths,
     options.mounts,
-    localSkillMountResolvers(extraSkillPaths),
+    localSkillMountResolvers(extraSkillMounts),
     mountFilesCache,
     configuredCache,
+    options.fallbackToTmp === true,
   );
   const resolveContribution = contributionResolver(resolvers);
   const resolveFilesystem = (context: DatabricksWorkspaceContext) =>
@@ -302,6 +300,7 @@ export function databricksWorkspaceConfig(
       retainFilesystemSource ? mountFilesCache : undefined,
       filesystemSourceKey,
     );
+  const hasSkillPaths = paths.some(pathMayProvideSkills) || extraSkillMounts.length > 0;
   const skills: SkillsResolver =
     options.skills ??
     (async ({ requestContext }) => {
@@ -322,10 +321,11 @@ export function databricksWorkspaceConfig(
     resolverCount: resolvers.length,
     configuredPaths,
     customMounts: Object.keys(options.mounts ?? {}).length,
-    customSkillsResolver: Boolean(options.skills),
+    skillsConfigured: options.skills !== undefined || hasSkillPaths,
+    customSkillsResolver: options.skills !== undefined,
     checkSkillFileMtime,
     bm25,
-    extraSkillPaths: extraSkillPaths.length,
+    extraSkillMounts: extraSkillMounts.length,
     sandbox: sandbox ? sandboxName(options.sandbox) : "disabled",
   });
 
@@ -337,7 +337,8 @@ export function databricksWorkspaceConfig(
     cache: _cache,
     pluginContext: _pluginContext,
     sandbox: _sandbox,
-    extraSkillPaths: _extraSkillPaths,
+    fallbackToTmp: _fallbackToTmp,
+    extraSkillMounts: _extraSkillMounts,
     ...workspaceOptions
   } = options;
   return {
@@ -345,7 +346,7 @@ export function databricksWorkspaceConfig(
     id,
     name,
     filesystem: resolveFilesystem,
-    ...(resolvers.length > 0 || options.skills
+    ...(options.skills !== undefined || hasSkillPaths
       ? {
           skills,
           checkSkillFileMtime,
@@ -393,6 +394,13 @@ export function resolveDatabricksWorkspacePaths(
   ];
 }
 
+/** Whether one included path can contribute Mastra skill paths. */
+function pathMayProvideSkills(path: DatabricksWorkspacePathValue): boolean {
+  if (typeof path === "function") return true;
+  if (path === false || typeof path === "string") return false;
+  return (path.skills?.length ?? 0) > 0;
+}
+
 /* ---------------------------- private helpers ---------------------------- */
 
 function workspaceTools(configured: WorkspaceToolsConfig | undefined): WorkspaceToolsConfig {
@@ -408,7 +416,7 @@ function resolveWorkspaceSandbox(
   workspaceId: string,
   workspaceName: string,
 ): WorkspaceSandbox | WorkspaceSandboxResolver | undefined {
-  const configured = selection ?? "monty";
+  const configured = selection ?? false;
   if (configured === false) return undefined;
   if (configured === "monty") return new MontySandbox();
   if (typeof configured === "function" || isSandbox(configured)) return configured;
@@ -462,9 +470,9 @@ function isSandbox(value: unknown): value is WorkspaceSandbox {
 }
 
 function sandboxName(selection: WorkspaceSandboxSelection | undefined): string {
-  if (selection === undefined || selection === "monty") return "monty";
+  if (selection === undefined || selection === false) return "disabled";
+  if (selection === "monty") return "monty";
   if (selection === "databricks") return "databricks";
-  if (selection === false) return "disabled";
   if (typeof selection === "function") return "resolver";
   return isSandbox(selection) ? selection.provider : (selection.provider ?? "databricks");
 }
@@ -504,14 +512,14 @@ async function resolveFilesCacheScope(context: DatabricksWorkspaceContext): Prom
   };
 }
 
-/** 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}`);
+/** Join one relative skill path to its actual composite mount path. */
+function mountedSkillPath(mount: string, skillPath: string): string {
+  if (posixPath.isAbsolute(skillPath)) {
+    throw new TypeError(`Skill path must be relative to its mount: ${skillPath}`);
   }
-  const normalized = posixPath.normalize(skillRoot);
+  const normalized = posixPath.normalize(skillPath);
   if (!normalized.ok) {
-    throw new TypeError(`Skill path escapes its mount: ${skillRoot}`);
+    throw new TypeError(`Skill path escapes its mount: ${skillPath}`);
   }
   return posixPath.join(posixPath.normalizeRoot(mount), normalized.path.slice(1));
 }
@@ -523,19 +531,21 @@ function isWorkspaceRoot(root: string): boolean {
 }
 
 /**
- * Mount resolver for the named skill folders.
+ * Mount resolver for configured Databricks and temporary paths.
  *
  * Gates on workspace file scope (or development mode), then mounts every
  * folder whose location resolves for this request.
  */
-async function resolveSkillFolderMounts(
+async function resolveWorkspacePathMounts(
   paths: readonly DatabricksWorkspacePathValue[],
   context: DatabricksWorkspaceContext,
   filesCache: FilesCacheExports | undefined,
   cacheConfig: DatabricksWorkspaceCache | undefined,
+  fallbackToTmp: boolean,
 ): Promise<WorkspaceMountContribution> {
   const mounts: Record<string, WorkspaceFilesystem> = {};
   const skillPaths: string[] = [];
+  let hasWritableMount = false;
   const requestContext = context.requestContext;
 
   const canMountDatabricks = Boolean(requestContext && shouldMountSkillFolders(requestContext));
@@ -550,9 +560,8 @@ async function resolveSkillFolderMounts(
     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)));
-      }
+      hasWritableMount = true;
+      skillPaths.push(...(configured.skills ?? []).map((path) => mountedSkillPath(mount, path)));
       continue;
     }
     if (!canMountDatabricks) {
@@ -573,12 +582,15 @@ async function resolveSkillFolderMounts(
       continue;
     }
     mounts[mount] = resolved.filesystem;
-    if (configured.readable !== false) {
-      skillPaths.push(...(configured.skills ?? ["."]).map((path) => mountedSkillPath(mount, path)));
-    }
+    hasWritableMount ||= resolved.writable;
+    skillPaths.push(...(configured.skills ?? []).map((path) => mountedSkillPath(mount, path)));
   }
 
-  logger.debug("skill-folders:mounted", {
+  if (fallbackToTmp && !hasWritableMount) {
+    mounts[SCRATCH_MOUNT] = userTempFilesystem(context, SCRATCH_MOUNT);
+  }
+
+  logger.debug("workspace-paths:mounted", {
     mountKeys: Object.keys(mounts),
     skillPaths,
   });
@@ -593,7 +605,6 @@ interface ResolvedDatabricksWorkspacePath {
   path: string;
   displayName?: string;
   description?: string;
-  readable?: boolean;
   skills?: readonly string[];
   writable?: boolean;
   createRoot?: boolean;
@@ -634,12 +645,13 @@ async function resolveSkillFolderFilesystem(
   | {
       filesystem: WorkspaceFilesystem;
       root?: string;
+      writable: boolean;
     }
   | undefined
 > {
   // A path mount needs the request's OBO client to reach the workspace.
   if (!cache.client) {
-    logger.debug("skill-folder:skipped", {
+    logger.debug("workspace-path:skipped", {
       path: folder.path,
       reason: "missing-obo-client",
     });
@@ -649,12 +661,7 @@ async function resolveSkillFolderFilesystem(
   if (!root) return undefined;
   const writable = folder.writable ?? isWorkspaceRoot(root);
   const cacheOptions = cache.fileSystemCache
-    ? await resolveFileCacheOptions(
-        cacheConfig,
-        context,
-        root,
-        folder.readable === false ? [] : (folder.skills ?? ["."]),
-      )
+    ? await resolveFileCacheOptions(cacheConfig, context, root, folder.skills ?? [])
     : undefined;
   const resolved = await databricksFilesystem(
     cache.client,
@@ -668,7 +675,7 @@ async function resolveSkillFolderFilesystem(
       ...(folder.displayName ? { displayName: folder.displayName } : {}),
     },
   );
-  return resolved ? { ...resolved, root } : undefined;
+  return resolved ? { ...resolved, root, writable } : undefined;
 }
 
 async function resolveCacheConfig(
@@ -782,18 +789,21 @@ function resolveWorkspaceIdentity(options: DatabricksWorkspaceOptions): {
   return { id, name };
 }
 
-/** Collect the skill-folder resolver and any caller-supplied ones. */
+/** Collect the Databricks path resolver and any caller-supplied mounts. */
 function buildMountResolvers(
   paths: readonly DatabricksWorkspacePathValue[],
   mounts: Record<string, WorkspaceFilesystem> | undefined,
   localMounts: WorkspaceMountResolver[],
   filesCache: FilesCacheExports | undefined,
   cacheConfig: DatabricksWorkspaceCache | undefined,
+  fallbackToTmp: boolean,
 ): WorkspaceMountResolver[] {
   const resolvers: WorkspaceMountResolver[] = [];
   const pathCount = paths.length;
-  if (pathCount > 0) {
-    resolvers.push((context) => resolveSkillFolderMounts(paths, context, filesCache, cacheConfig));
+  if (pathCount > 0 || fallbackToTmp) {
+    resolvers.push((context) =>
+      resolveWorkspacePathMounts(paths, context, filesCache, cacheConfig, fallbackToTmp),
+    );
   }
   if (mounts && Object.keys(mounts).length > 0) resolvers.push(() => ({ mounts }));
   resolvers.push(...localMounts);
@@ -830,10 +840,16 @@ function userTempFilesystem(
   });
 }
 
-/** 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) => {
-    const mount = posixPath.normalizeRoot(root);
+/** Mount startup-provisioned local skill trees into Mastra's workspace filesystem. */
+function localSkillMountResolvers(mounts: readonly LocalSkillMount[]): WorkspaceMountResolver[] {
+  const unique = new Map<string, LocalSkillMount>();
+  for (const entry of mounts) {
+    const root = entry.root.trim();
+    if (!root) continue;
+    unique.set(`${entry.mountPath}\0${root}`, { root, mountPath: entry.mountPath });
+  }
+  return [...unique.values()].map(({ root, mountPath }) => {
+    const mount = posixPath.normalizeRoot(mountPath);
     const source = new LocalFileSystem({
       root,
       readOnly: true,
@@ -1055,30 +1071,30 @@ async function resolveWorkspaceFilesystem(
 }
 
 /**
- * Expand skill roots into concrete skill directories and keep the first
+ * Expand configured skill paths 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[],
+  paths: readonly string[],
 ): Promise<string[]> {
   const selected = new Map<string, string>();
-  for (const root of roots) {
+  for (const path of paths) {
     try {
-      const entries = await filesystem.readdir(root);
+      const entries = await filesystem.readdir(path);
       if (entries.some((entry) => entry.type === "file" && entry.name === "SKILL.md")) {
-        const name = posixPath.basename(root);
-        if (!selected.has(name)) selected.set(name, root);
+        const name = posixPath.basename(path);
+        if (!selected.has(name)) selected.set(name, path);
         continue;
       }
       for (const entry of entries) {
         if (entry.type !== "directory" || selected.has(entry.name)) continue;
-        selected.set(entry.name, posixPath.join(root, entry.name));
+        selected.set(entry.name, posixPath.join(path, entry.name));
       }
     } catch (error) {
-      logger.debug("skill-root:skipped", {
-        root,
+      logger.debug("skill-path:skipped", {
+        path,
         error: errorUtils.errorMessage(error),
       });
     }