@dbx-tools/appkit-mastra 0.9.118 → 0.9.119

package/package.json

@@ -34,20 +34,21 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.118",
-    "@dbx-tools/core": "^0.9.118",
-    "@dbx-tools/databricks": "^0.9.118",
-    "@dbx-tools/fs": "^0.9.118",
-    "@dbx-tools/genie": "^0.9.118",
-    "@dbx-tools/model": "^0.9.118",
-    "@dbx-tools/model-protocol": "^0.9.118",
-    "@dbx-tools/path": "^0.9.118",
-    "@dbx-tools/postgres": "^0.9.118",
-    "@dbx-tools/shared-core": "^0.9.118",
-    "@dbx-tools/shared-fs": "^0.9.118",
-    "@dbx-tools/shared-genie": "^0.9.118",
-    "@dbx-tools/shared-mastra": "^0.9.118",
-    "@dbx-tools/shared-model": "^0.9.118",
+    "@dbx-tools/appkit": "^0.9.119",
+    "@dbx-tools/cache": "^0.9.119",
+    "@dbx-tools/core": "^0.9.119",
+    "@dbx-tools/databricks": "^0.9.119",
+    "@dbx-tools/fs": "^0.9.119",
+    "@dbx-tools/genie": "^0.9.119",
+    "@dbx-tools/model": "^0.9.119",
+    "@dbx-tools/model-protocol": "^0.9.119",
+    "@dbx-tools/path": "^0.9.119",
+    "@dbx-tools/postgres": "^0.9.119",
+    "@dbx-tools/shared-core": "^0.9.119",
+    "@dbx-tools/shared-fs": "^0.9.119",
+    "@dbx-tools/shared-genie": "^0.9.119",
+    "@dbx-tools/shared-mastra": "^0.9.119",
+    "@dbx-tools/shared-model": "^0.9.119",
     "@mastra/ai-sdk": "1.10.5",
     "@mastra/core": "1.71.0",
     "@mastra/express": "1.5.15",
@@ -68,7 +69,6 @@
     "ai": "^7.0.0",
     "express": "^5.1.0",
     "fuse.js": "^7.4.2",
-    "lru-cache": "11.5.3",
     "pg": "^8.22.0",
     "yaml": "^2.9.0",
     "zod": "4.3.6"
@@ -164,10 +164,6 @@
         "types": "./lib/src/rest.d.ts",
         "default": "./lib/src/rest.js"
       },
-      "./sandbox": {
-        "types": "./lib/src/sandbox.d.ts",
-        "default": "./lib/src/sandbox.js"
-      },
       "./server": {
         "types": "./lib/src/server.d.ts",
         "default": "./lib/src/server.js"
@@ -223,7 +219,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.118",
+  "version": "0.9.119",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -316,10 +312,6 @@
       "types": "./lib/src/rest.d.ts",
       "default": "./lib/src/rest.js"
     },
-    "./sandbox": {
-      "types": "./lib/src/sandbox.d.ts",
-      "default": "./lib/src/sandbox.js"
-    },
     "./server": {
       "types": "./lib/src/server.d.ts",
       "default": "./lib/src/server.js"

package/src/agents.ts

@@ -767,7 +767,7 @@ export async function buildAgents(opts: {
         fallbackToTmp: config.workspaceFallbackToTmp,
         ...(config.workspaceTools !== undefined ? { tools: config.workspaceTools } : {}),
         pluginContext: context,
-        sandbox: config.sandbox === true ? "databricks" : config.sandbox,
+        sandbox: config.sandbox,
       });
       markDefaultWorkspace(workspace);
     } else if (workspace) {

package/src/config.ts

@@ -20,14 +20,17 @@ import type { BrandContext } from "@dbx-tools/shared-core";
 import type { AgentConfig } from "@mastra/core/agent";
 import type { RequestContext } from "@mastra/core/request-context";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
-import type { WorkspaceToolsConfig } from "@mastra/core/workspace";
+import type {
+  WorkspaceSandbox,
+  WorkspaceSandboxResolver,
+  WorkspaceToolsConfig,
+} from "@mastra/core/workspace";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
 import type { AnyMastraAgentDefinition, MastraTools } from "./agents.ts";
 import type { GenieSpacesConfig } from "./genie.ts";
 import { IDENTITY_MODES, type MastraIdentityMode } from "./identity.ts";
-import type { RemoteSkillsOption } from "./remote-skills.ts";
-import type { DatabricksWorkspaceSandboxOptions } from "./sandbox.ts";
+import type { LocalSkillMount, RemoteSkillsOption } from "./remote-skills.ts";
 
 /**
  * `RequestContext` key under which {@link MastraServer} stores the
@@ -226,20 +229,22 @@ export interface MastraPluginConfig extends BasePluginConfig {
    */
   memory?: boolean | MastraMemoryConfig;
   /**
-   * Expose executable tools from each agent definition through native Mastra
-   * Code Mode. Defaults on whenever the agent has executable tools. The plugin
-   * selects Mastra's isolated-vm transport once during startup and falls back
-   * to Mastra QuickJS when the native transport is unavailable. Set `false` to
+   * Expose executable tools available to the current request through native
+   * Mastra Code Mode. Defaults on whenever the request has executable tools.
+   * The plugin selects Mastra's isolated-vm transport once during startup and
+   * falls back to Mastra QuickJS when the native transport is unavailable.
+   * These transports do not execute through the workspace command sandbox;
+   * SSH is used only when an exposed SSH-backed tool is called. Set `false` to
    * opt out.
    */
   codeMode?: boolean | MastraCodeModeConfig;
   /**
    * Sandbox for auto-created agent workspaces. Defaults to Monty. `false`
-   * disables command execution; `true`, `"databricks"`, or an object
-   * selects/configures Databricks Sandbox. An agent with an explicit custom
-   * `workspace` keeps that workspace and its sandbox.
+   * disables command execution; `true` or `"monty"` selects Monty; an explicit
+   * Mastra sandbox or resolver supplies a remote transport. An agent with an
+   * explicit custom `workspace` keeps that workspace and its sandbox.
    */
-  sandbox?: boolean | "databricks" | "monty" | DatabricksWorkspaceSandboxOptions;
+  sandbox?: boolean | "monty" | WorkspaceSandbox | WorkspaceSandboxResolver;
   /** Add user-scoped `/tmp` only when no configured workspace path mounts writable. */
   workspaceFallbackToTmp?: boolean;
   /** Native Mastra workspace tool availability, approval, and hook configuration. */
@@ -634,10 +639,10 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * without it, a URL source is fetched directly. A source that resolves
    * through neither fails startup unless `failOnError: false`.
    *
-   * Provisioned skills are written to the Databricks user's Assistant skills
-   * folder (`/Workspace/Users/<email>/.assistant/skills`, the personal skill
-   * target) so they persist and are picked up by the built-in Assistant-skills
-   * mount. With no writable workspace, they go to a local temp dir instead.
+   * AI Tools is cached daily with `@dbx-tools/cache` and served to every
+   * auto-created workspace from the shared `/.databricks/skills` memory mount.
+   * Other sources are written to the Databricks user's Assistant skills folder
+   * when writable, with a read-only local-memory fallback.
    *
    * @example
    * ```ts
@@ -651,6 +656,8 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * ```
    */
   remoteSkills?: RemoteSkillsOption;
+  /** Read-only local skill trees mounted into every default agent workspace. */
+  localSkillMounts?: LocalSkillMount[];
 }
 
 /**
@@ -677,7 +684,7 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     remoteSkills: {
       type: ["string", "array", "object"],
       description:
-        'Remote Agent-Skill sources provisioned at startup: "aitools" for Databricks\' own skill set (read from the public databricks/databricks-agent-skills repo, no CLI needed), a GitHub owner/repo, a git/GitLab URL, or a direct SKILL.md/archive URL. Non-aitools sources prefer the optional `skills` npm CLI, else a direct fetch; fails startup on error unless failOnError:false. Written to the Databricks user Assistant skills folder, or read-only local backing storage exposed at stable virtual workspace mounts.',
+        'Remote Agent-Skill sources provisioned at startup: "aitools" for Databricks\' own skill set (daily @dbx-tools/cache snapshot served from the shared in-memory /.databricks/skills mount), a GitHub owner/repo, a git/GitLab URL, or a direct SKILL.md/archive URL. Non-aitools sources prefer the optional `skills` npm CLI, else a direct fetch; fails startup on error unless failOnError:false. Other sources write to the Databricks user Assistant skills folder or a read-only local-memory fallback.',
     },
     storage: {
       type: ["boolean", "object"],
@@ -692,12 +699,12 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     codeMode: {
       type: ["boolean", "object"],
       description:
-        "Expose all executable tools available to the current request, including native workspace tools, through dynamically generated Mastra Code Mode for sandboxed TypeScript batching, aggregation, and arithmetic. The plugin selects Mastra isolated-vm once during startup and falls back to Mastra QuickJS when native initialization is unavailable. False disables it.",
+        "Expose all executable tools available to the current request through native Mastra Code Mode for TypeScript batching, aggregation, and arithmetic. The plugin uses Mastra isolated-vm with the existing QuickJS fallback; neither transport runs through the workspace command sandbox, so SSH is used only when an SSH-backed tool is called. False disables it.",
     },
     sandbox: {
       type: ["boolean", "string", "object"],
       description:
-        'Command sandbox for auto-created agent workspaces. Defaults to Monty. False disables command execution; true, "databricks", or an object selects/configures Databricks Sandbox.',
+        'Command sandbox for auto-created agent workspaces. Defaults to Monty. False disables command execution; true or "monty" selects Monty; an explicit sandbox or resolver supplies another transport.',
     },
     workspaceFallbackToTmp: {
       type: "boolean",

package/src/defaults.ts

@@ -53,9 +53,9 @@ const STATEMENT_CACHE_TTL_SEC = 5 * 60;
 export const modelCatalogueDefaults: ExecuteSettings = {
   default: {
     // Cache disabled here because `listServingEndpoints` already memoizes the
-    // catalogue through the same `CacheManager`, keyed by workspace host with
-    // `config.modelCacheTtlMs`. That entry is shared across identities; a
-    // second interceptor cache would duplicate it once per user.
+    // catalogue in the shared model cache, keyed by workspace host and trusted
+    // credential identity with `config.modelCacheTtlMs`. A second interceptor
+    // cache would duplicate it once per user.
     cache: { enabled: false },
     // Retry enabled: listing endpoints is an idempotent GET, and the listing
     // is on the chat UI's load path, so a transient 5xx should not blank the

package/src/genie.ts

@@ -45,6 +45,7 @@ import {
 } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
 import { pluginRegistry } from "@dbx-tools/appkit";
+import { createCache } from "@dbx-tools/cache/cache";
 import { chat, space as genieSpace } from "@dbx-tools/genie";
 import { errorUtils, log, stringUtils } from "@dbx-tools/shared-core";
 import { genieModel, type GenieMessage } from "@dbx-tools/shared-genie";
@@ -52,7 +53,6 @@ import type { StartedEvent } from "@dbx-tools/shared-mastra";
 import type { RequestContext } from "@mastra/core/request-context";
 import { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import { createTool, type ToolExecutionContext } from "@mastra/core/tools";
-import { LRUCache } from "lru-cache";
 import { z } from "zod";
 
 import type { MastraTools } from "./agents.ts";
@@ -1091,19 +1091,19 @@ const SUGGESTION_LIMIT = 6;
 const SUGGESTION_CACHE_TTL_MS = 10 * 60_000;
 
 /** Bounded process-local cache of parsed sample questions by Genie space id. */
-const _suggestionCache = new LRUCache<string, string[]>({
-  max: 128,
+const _suggestionCache = createCache({
+  maxEntries: 128,
   ttl: SUGGESTION_CACHE_TTL_MS,
 });
 
 /** Read a space's cached questions, or `undefined` on miss / expiry. */
-function readSuggestionCache(spaceId: string): string[] | undefined {
-  return _suggestionCache.get(spaceId);
+function readSuggestionCache(spaceId: string): Promise<string[] | undefined> {
+  return _suggestionCache.get<string[]>(spaceId);
 }
 
 /** Cache a space's parsed questions for {@link SUGGESTION_CACHE_TTL_MS}. */
-function writeSuggestionCache(spaceId: string, questions: string[]): void {
-  _suggestionCache.set(spaceId, questions);
+async function writeSuggestionCache(spaceId: string, questions: string[]): Promise<void> {
+  await _suggestionCache.set(spaceId, questions);
 }
 
 /**
@@ -1128,7 +1128,7 @@ export async function collectSpaceSuggestions(opts: {
   const seen = new Set<string>();
 
   for (const { spaceId } of Object.values(opts.spaces)) {
-    let questions = readSuggestionCache(spaceId);
+    let questions = await readSuggestionCache(spaceId);
     if (!questions) {
       try {
         const space = await genieSpace.getGenieSpace(spaceId, {
@@ -1136,7 +1136,7 @@ export async function collectSpaceSuggestions(opts: {
           ...(opts.signal ? { context: opts.signal } : {}),
         });
         questions = genieSpace.genieSampleQuestions(space);
-        writeSuggestionCache(spaceId, questions);
+        await writeSuggestionCache(spaceId, questions);
       } catch (err) {
         logger.warn("suggestions:fetch-error", {
           spaceId,

package/src/plugin.ts

@@ -1126,7 +1126,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       context: this.context,
       memoryBuilder,
       log: this.logger,
-      extraSkillMounts: provisioned.localSkillMounts,
+      extraSkillMounts: [...(this.config.localSkillMounts ?? []), ...provisioned.localSkillMounts],
     });
 
     // `mastra.server.apiRoutes` is only honored by Mastra's standalone

package/src/remote-skills.ts

@@ -5,7 +5,7 @@
  * {@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 read-only backing directories plus
+ * `SKILL.md` tree at app boot and returns read-only filesystem backings plus
  * their stable virtual workspace mounts.
  *
  * Resolution per source, in order:
@@ -26,25 +26,16 @@
  * source (or the top-level call) sets `failOnError: false`, in which case it is
  * logged and skipped so one bad source never takes the app down.
  *
- * Every provisioned tree carries a {@link METADATA_FILE} recording when each
- * source was last downloaded, and a source is only re-downloaded once that
- * record is older than {@link DEFAULT_REFRESH_TTL_MS} (seven days). This runs at app
- * BOOT, so without it a container that restarts a dozen times an hour re-pulls
- * the whole AI Tools set a dozen times for content that changes rarely. The
- * record travels WITH the tree rather than in process memory, so the reuse
- * survives a restart - which is the only way it helps a Databricks App at all.
- * Pass `refreshTtlMs: 0` to download on every boot.
+ * AI Tools uses the shared `@dbx-tools/cache` project cache with a one-day TTL,
+ * then hydrates one process-memory filesystem mounted at
+ * {@link AITOOLS_SKILLS_MOUNT} for every default workspace. Other sources keep
+ * a {@link METADATA_FILE} beside their provisioned tree and default to a
+ * seven-day refresh window. Pass `refreshTtlMs: 0` to download on every boot.
  *
- * The default destination is the Databricks workspace Assistant skills tree
- * (`/Workspace/.assistant/skills`), so provisioned skills persist across restarts and are
- * discovered by the built-in Assistant-skills mount. Pass `userEmail` (or an
- * explicit `databricksBasePath`) to target `/Workspace/Users/<email>/.assistant/skills`
- * instead. When no Databricks client is resolvable at startup - or the resolved
- * 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 exposed through a stable read-only virtual mount
- * for the current process. Storage location degrades; the skills themselves do not.
+ * For non-AI-Tools sources, the default destination is the Databricks workspace
+ * Assistant skills tree (`/Workspace/.assistant/skills`). Pass `userEmail` or
+ * `databricksBasePath` to select another destination. When it is unavailable,
+ * the tree is exposed through a stable read-only local mount instead.
  *
  * @module
  */
@@ -55,6 +46,7 @@ import { dirname, join, posix } from "node:path";
 import type { WorkspaceClient } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
 import type { WorkspaceClientLike } from "@dbx-tools/appkit";
+import { flushCache, getOrSet, projectCache } from "@dbx-tools/cache/cache";
 import { exec } from "@dbx-tools/core";
 import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { localFS, type LocalFileSystem } from "@dbx-tools/fs";
@@ -70,7 +62,7 @@ import {
   stringUtils,
 } from "@dbx-tools/shared-core";
 import type { OneOrMany } from "@dbx-tools/shared-core";
-import type { FileSystem } from "@dbx-tools/shared-fs";
+import { MemoryFileSystem, type FileSystem } from "@dbx-tools/shared-fs";
 
 import { ORGANIZATION_SKILLS_PATH, personalSkillsPath } from "./skill-paths.ts";
 
@@ -116,9 +108,17 @@ const METADATA_FILE = ".metadata.json";
 /** Shape marker for {@link METADATA_FILE}; an unknown version is ignored, not read. */
 const METADATA_VERSION = 1;
 
-/** How long a provisioned source is reused before being downloaded again. */
+/** How long a general provisioned source is reused before being downloaded again. */
 const DEFAULT_REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
+/** How long the shared Databricks AI Tools snapshot is reused. */
+export const AITOOLS_REFRESH_TTL_MS = 24 * 60 * 60 * 1000;
+
+const aiToolsCache = projectCache("mastra-aitools", {
+  ttl: AITOOLS_REFRESH_TTL_MS,
+  maxEntries: 32,
+});
+
 /* ------------------------------ AI Tools ------------------------------ */
 
 /**
@@ -203,14 +203,25 @@ 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 {
+/** Read-only local directory exposed at a stable virtual workspace path. */
+export interface LocalSkillDirectoryMount {
   /** Physical local directory containing the provisioned `SKILL.md` tree. */
   root: string;
   /** Virtual path agents see inside the composed Mastra workspace. */
   mountPath: string;
 }
 
+/** Read-only process-local filesystem exposed at a stable virtual workspace path. */
+export interface MemorySkillMount {
+  /** Process-shared filesystem containing the provisioned `SKILL.md` tree. */
+  filesystem: FileSystem;
+  /** Virtual path agents see inside the composed Mastra workspace. */
+  mountPath: string;
+}
+
+/** Local skill backing accepted by every auto-created workspace. */
+export type LocalSkillMount = LocalSkillDirectoryMount | MemorySkillMount;
+
 /** Top-level remote-skills provisioning options. */
 export interface ProvisionRemoteSkillsOptions {
   /** Sources to materialize at startup. */
@@ -233,8 +244,8 @@ export interface ProvisionRemoteSkillsOptions {
   maxDownloadBytes?: number;
   /**
    * How long a provisioned tree is reused before its source is downloaded
-   * again, in milliseconds. Defaults to seven days; `0` re-downloads on every
-   * boot. A per-source `refreshTtlMs` wins over this.
+   * again, in milliseconds. AI Tools defaults to one day and other sources to
+   * seven days; `0` re-downloads on every boot. A per-source `refreshTtlMs` wins.
    */
   refreshTtlMs?: number;
 }
@@ -242,9 +253,10 @@ export interface ProvisionRemoteSkillsOptions {
 /** What {@link provisionRemoteSkills} resolved. */
 export interface ProvisionedRemoteSkills {
   /**
-   * 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.
+   * Extra read-only local or process-memory skill mounts to hand Mastra. AI
+   * Tools always uses process memory; other sources use this fallback when
+   * they could not be written to Databricks. Physical paths remain hidden
+   * behind stable virtual workspace paths.
    */
   localSkillMounts: LocalSkillMount[];
   /** Absolute Databricks destination each source was written to, if any. */
@@ -257,8 +269,8 @@ export interface ProvisionedRemoteSkills {
 }
 
 /**
- * What one source's last download left behind, as recorded in
- * {@link METADATA_FILE}.
+ * Metadata for one resolved source snapshot. General remote sources store it
+ * in {@link METADATA_FILE}; AI Tools stores it with the cache-package value.
  */
 export interface RemoteSkillCacheEntry {
   /** The source string this entry was downloaded from, for readability. */
@@ -281,6 +293,20 @@ export interface RemoteSkillsMetadata {
   sources: Record<string, RemoteSkillCacheEntry>;
 }
 
+interface CachedSkillFile {
+  path: string;
+  content: string;
+}
+
+interface CachedAiToolsTree {
+  files: CachedSkillFile[];
+  record: RemoteSkillCacheEntry;
+}
+
+interface ResolvedAiToolsTree extends CachedAiToolsTree {
+  cached: boolean;
+}
+
 /* ------------------------------- helpers ------------------------------- */
 
 /** Normalize the `remoteSkills` option into a flat options bag. */
@@ -381,12 +407,16 @@ function remoteSourceIdentifier(source: string): string {
   return `${url.hostname}-${path}`;
 }
 
-/** The effective reuse window: per-source, then top-level, then seven days. */
+/** The effective reuse window: per-source, top-level, then the source default. */
 function resolveRefreshTtl(
   sourceOptions: NormalizedSource,
   options: ProvisionRemoteSkillsOptions,
 ): number {
-  return sourceOptions.refreshTtlMs ?? options.refreshTtlMs ?? DEFAULT_REFRESH_TTL_MS;
+  return (
+    sourceOptions.refreshTtlMs ??
+    options.refreshTtlMs ??
+    (isAiToolsSource(sourceOptions.source) ? AITOOLS_REFRESH_TTL_MS : DEFAULT_REFRESH_TTL_MS)
+  );
 }
 
 /**
@@ -465,12 +495,17 @@ export async function provisionRemoteSkills(
   if (!options) return empty;
 
   const failDefault = options.failOnError !== false;
+  const sources = (Array.isArray(options.sources) ? options.sources : [options.sources]).map(
+    toSourceOptions,
+  );
   const client = options.client ?? appkit.tryGetExecutionContext()?.client;
   // Probed rather than assumed: an identity that cannot write the workspace
   // tree falls back to the local one instead of failing startup. The probe also
   // creates the root, which the first cache READ needs - `copySkillDirs` would
   // otherwise be the first thing to create it, which is too late.
-  const requestedBasePath = resolveDatabricksBasePath(options, client);
+  const requestedBasePath = sources.some((source) => !isAiToolsSource(source.source))
+    ? resolveDatabricksBasePath(options, client)
+    : undefined;
   const destination = requestedBasePath
     ? await openWritableWorkspace(requestedBasePath, client as WorkspaceClient)
     : undefined;
@@ -481,15 +516,30 @@ export async function provisionRemoteSkills(
   let staging: LocalFileSystem | undefined;
 
   try {
-    const sources = Array.isArray(options.sources) ? options.sources : [options.sources];
-    for (const entry of sources) {
-      const sourceOptions = toSourceOptions(entry);
+    for (const sourceOptions of sources) {
       const failOnError = sourceOptions.failOnError ?? failDefault;
       try {
         // 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);
+        if (isAiToolsSource(sourceOptions.source)) {
+          staging ??= await initializedScratch("mastra-remote-skills");
+          const tree = await cachedAiToolsTree(sourceOptions, staging.root, options, key);
+          localSkillMounts.push({
+            filesystem: await memorySkillTree(tree.files, `aitools-${key}`),
+            mountPath,
+          });
+          skillNames.push(...tree.record.skills);
+          logger.info("remote skill ready", {
+            source: sourceOptions.source,
+            destination: mountPath,
+            downloadedAt: tree.record.downloadedAt,
+            skills: tree.record.skills,
+            cached: tree.cached,
+          });
+          continue;
+        }
         const cacheFS = destination ?? localSkillsFS(key);
         const metadata = await readMetadata(cacheFS);
         const cached = metadata?.sources[key];
@@ -563,17 +613,87 @@ export async function provisionRemoteSkills(
   return { localSkillMounts, databricksBasePath, skillNames };
 }
 
+async function cachedAiToolsTree(
+  sourceOptions: NormalizedSource,
+  stagingRoot: string,
+  options: ProvisionRemoteSkillsOptions,
+  key: string,
+): Promise<ResolvedAiToolsTree> {
+  const ttl = resolveRefreshTtl(sourceOptions, options);
+  let loaded = false;
+  const load = async (): Promise<CachedAiToolsTree> => {
+    loaded = true;
+    const stagedDir = await stageAiTools(
+      sourceOptions,
+      join(stagingRoot, `aitools-${hash.id()}`),
+      options,
+    );
+    const staged = await collectSkillDirs(stagedDir);
+    if (staged.length === 0) {
+      throw new Error(`no SKILL.md found for source "${sourceOptions.source}"`);
+    }
+    const policy = cachePolicy(sourceOptions);
+    return {
+      files: await serializeSkillDirs(staged),
+      record: {
+        source: sourceOptions.source,
+        downloadedAt: new Date().toISOString(),
+        skills: staged.map((dir) => dir.name),
+        ...(policy ? { policy } : {}),
+      },
+    };
+  };
+  const tree =
+    ttl <= 0
+      ? await load()
+      : await getOrSet(aiToolsCache, key, load, {
+          ttl,
+          throwErrors: true,
+        });
+  if (!tree) throw new Error(`AI Tools cache returned no tree for ${key}`);
+  await flushCache(aiToolsCache);
+  return { ...tree, cached: !loaded };
+}
+
+async function serializeSkillDirs(dirs: readonly StagedSkillDir[]): Promise<CachedSkillFile[]> {
+  const files: CachedSkillFile[] = [];
+  for (const dir of dirs) {
+    for (const relative of find.findFiles("**/*", { cwd: dir.absolutePath, nodir: true })) {
+      files.push({
+        path: posix.join(dir.name, relative.split(/[\\/]/).join("/")),
+        content: (await readFile(join(dir.absolutePath, relative))).toString("base64"),
+      });
+    }
+  }
+  return files;
+}
+
+async function memorySkillTree(
+  files: readonly CachedSkillFile[],
+  id: string,
+): Promise<MemoryFileSystem> {
+  const filesystem = new MemoryFileSystem({ id, root: "/" });
+  await filesystem.init();
+  for (const file of files) {
+    await filesystem.writeFile(file.path, Buffer.from(file.content, "base64"), {
+      overwrite: true,
+    });
+  }
+  return filesystem;
+}
+
 /** 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 identity = "root" in mount ? mount.root : mount.filesystem.id;
     const previousRoot = rootsByMount.get(mount.mountPath);
-    if (previousRoot && previousRoot !== mount.root) {
+    if (previousRoot && previousRoot !== identity) {
       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);
+    rootsByMount.set(mount.mountPath, identity);
   }
 }