@dbx-tools/appkit-mastra 0.9.108 → 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";
 
@@ -172,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
@@ -207,19 +208,21 @@ export interface DatabricksWorkspaceOptions extends Omit<
   /** 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 paths 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 ------------------------------- */
@@ -273,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;
@@ -284,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) =>
@@ -296,7 +300,7 @@ export function databricksWorkspaceConfig(
       retainFilesystemSource ? mountFilesCache : undefined,
       filesystemSourceKey,
     );
-  const hasSkillPaths = paths.some(pathMayProvideSkills) || extraSkillPaths.length > 0;
+  const hasSkillPaths = paths.some(pathMayProvideSkills) || extraSkillMounts.length > 0;
   const skills: SkillsResolver =
     options.skills ??
     (async ({ requestContext }) => {
@@ -321,7 +325,7 @@ export function databricksWorkspaceConfig(
     customSkillsResolver: options.skills !== undefined,
     checkSkillFileMtime,
     bm25,
-    extraSkillPaths: extraSkillPaths.length,
+    extraSkillMounts: extraSkillMounts.length,
     sandbox: sandbox ? sandboxName(options.sandbox) : "disabled",
   });
 
@@ -333,7 +337,8 @@ export function databricksWorkspaceConfig(
     cache: _cache,
     pluginContext: _pluginContext,
     sandbox: _sandbox,
-    extraSkillPaths: _extraSkillPaths,
+    fallbackToTmp: _fallbackToTmp,
+    extraSkillMounts: _extraSkillMounts,
     ...workspaceOptions
   } = options;
   return {
@@ -411,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;
@@ -465,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");
 }
@@ -536,9 +541,11 @@ async function resolveWorkspacePathMounts(
   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));
@@ -553,6 +560,7 @@ async function resolveWorkspacePathMounts(
     if (posixPath.isWithinRoot(SCRATCH_MOUNT, configured.path)) {
       const mount = configured.mount ?? configured.path;
       mounts[mount] = userTempFilesystem(context, configured.path);
+      hasWritableMount = true;
       skillPaths.push(...(configured.skills ?? []).map((path) => mountedSkillPath(mount, path)));
       continue;
     }
@@ -574,9 +582,14 @@ async function resolveWorkspacePathMounts(
       continue;
     }
     mounts[mount] = resolved.filesystem;
+    hasWritableMount ||= resolved.writable;
     skillPaths.push(...(configured.skills ?? []).map((path) => mountedSkillPath(mount, path)));
   }
 
+  if (fallbackToTmp && !hasWritableMount) {
+    mounts[SCRATCH_MOUNT] = userTempFilesystem(context, SCRATCH_MOUNT);
+  }
+
   logger.debug("workspace-paths:mounted", {
     mountKeys: Object.keys(mounts),
     skillPaths,
@@ -632,6 +645,7 @@ async function resolveSkillFolderFilesystem(
   | {
       filesystem: WorkspaceFilesystem;
       root?: string;
+      writable: boolean;
     }
   | undefined
 > {
@@ -661,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,12 +796,13 @@ function buildMountResolvers(
   localMounts: WorkspaceMountResolver[],
   filesCache: FilesCacheExports | undefined,
   cacheConfig: DatabricksWorkspaceCache | undefined,
+  fallbackToTmp: boolean,
 ): WorkspaceMountResolver[] {
   const resolvers: WorkspaceMountResolver[] = [];
   const pathCount = paths.length;
-  if (pathCount > 0) {
+  if (pathCount > 0 || fallbackToTmp) {
     resolvers.push((context) =>
-      resolveWorkspacePathMounts(paths, context, filesCache, cacheConfig),
+      resolveWorkspacePathMounts(paths, context, filesCache, cacheConfig, fallbackToTmp),
     );
   }
   if (mounts && Object.keys(mounts).length > 0) resolvers.push(() => ({ mounts }));
@@ -825,10 +840,16 @@ function userTempFilesystem(
   });
 }
 
-/** Mount startup-provisioned local skill paths 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,