@dbx-tools/appkit-mastra 0.9.74 → 0.9.79

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/agents.ts","../src/chart.ts","../src/chat.ts","../src/config.ts","../src/defaults.ts","../src/evaluation.ts","../src/filesystems.ts","../src/genie.ts","../src/identity.ts","../src/mcp.ts","../src/memory.ts","../src/mlflow.ts","../src/model.ts","../src/monty-sandbox.ts","../src/observability.ts","../src/openapi-tool.ts","../src/plugin.ts","../src/processors.ts","../src/remote-skills.ts","../src/rest.ts","../src/sandbox.ts","../src/server.ts","../src/serving-sanitize.ts","../src/serving.ts","../src/skill-cache.ts","../src/skill-paths.ts","../src/statement.ts","../src/storage-schema.ts","../src/style.ts","../src/summarize.ts","../src/telemetry.ts","../src/trace-attributes.ts","../src/validation.ts","../src/workspaces.ts","../src/writer.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/agents.ts","../src/chart.ts","../src/chat.ts","../src/config.ts","../src/defaults.ts","../src/evaluation.ts","../src/filesystems.ts","../src/genie.ts","../src/identity.ts","../src/mcp.ts","../src/memory.ts","../src/mlflow.ts","../src/model.ts","../src/monty-native.ts","../src/monty-sandbox.ts","../src/observability.ts","../src/openapi-tool.ts","../src/plugin.ts","../src/processors.ts","../src/remote-skills.ts","../src/rest.ts","../src/sandbox.ts","../src/server.ts","../src/serving-sanitize.ts","../src/serving.ts","../src/skill-cache.ts","../src/skill-paths.ts","../src/skill-search.ts","../src/statement.ts","../src/storage-schema.ts","../src/style.ts","../src/summarize.ts","../src/telemetry.ts","../src/trace-attributes.ts","../src/validation.ts","../src/workspaces.ts","../src/writer.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -34,19 +34,19 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.74",
-    "@dbx-tools/core": "^0.9.74",
-    "@dbx-tools/databricks": "^0.9.74",
-    "@dbx-tools/fs": "^0.9.74",
-    "@dbx-tools/genie": "^0.9.74",
-    "@dbx-tools/model": "^0.9.74",
-    "@dbx-tools/path": "^0.9.74",
-    "@dbx-tools/postgres": "^0.9.74",
-    "@dbx-tools/shared-core": "^0.9.74",
-    "@dbx-tools/shared-fs": "^0.9.74",
-    "@dbx-tools/shared-genie": "^0.9.74",
-    "@dbx-tools/shared-mastra": "^0.9.74",
-    "@dbx-tools/shared-model": "^0.9.74",
+    "@dbx-tools/appkit": "^0.9.79",
+    "@dbx-tools/core": "^0.9.79",
+    "@dbx-tools/databricks": "^0.9.79",
+    "@dbx-tools/fs": "^0.9.79",
+    "@dbx-tools/genie": "^0.9.79",
+    "@dbx-tools/model": "^0.9.79",
+    "@dbx-tools/path": "^0.9.79",
+    "@dbx-tools/postgres": "^0.9.79",
+    "@dbx-tools/shared-core": "^0.9.79",
+    "@dbx-tools/shared-fs": "^0.9.79",
+    "@dbx-tools/shared-genie": "^0.9.79",
+    "@dbx-tools/shared-mastra": "^0.9.79",
+    "@dbx-tools/shared-model": "^0.9.79",
     "@mastra/ai-sdk": "1.10.5",
     "@mastra/core": "1.71.0",
     "@mastra/express": "1.5.15",
@@ -61,9 +61,12 @@
     "@opentelemetry/core": "2.11.0",
     "@opentelemetry/sdk-trace-base": "2.8.0",
     "@opentelemetry/sdk-trace-node": "2.8.0",
-    "@pydantic/monty": "0.0.23",
+    "@pydantic/monty": "1.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"
   },
   "main": "./lib/index.js",
@@ -129,6 +132,10 @@
         "types": "./lib/src/model.d.ts",
         "default": "./lib/src/model.js"
       },
+      "./monty-native": {
+        "types": "./lib/src/monty-native.d.ts",
+        "default": "./lib/src/monty-native.js"
+      },
       "./monty-sandbox": {
         "types": "./lib/src/monty-sandbox.d.ts",
         "default": "./lib/src/monty-sandbox.js"
@@ -181,6 +188,10 @@
         "types": "./lib/src/skill-paths.d.ts",
         "default": "./lib/src/skill-paths.js"
       },
+      "./skill-search": {
+        "types": "./lib/src/skill-search.d.ts",
+        "default": "./lib/src/skill-search.js"
+      },
       "./statement": {
         "types": "./lib/src/statement.d.ts",
         "default": "./lib/src/statement.js"
@@ -220,7 +231,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.74",
+  "version": "0.9.79",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -285,6 +296,10 @@
       "types": "./lib/src/model.d.ts",
       "default": "./lib/src/model.js"
     },
+    "./monty-native": {
+      "types": "./lib/src/monty-native.d.ts",
+      "default": "./lib/src/monty-native.js"
+    },
     "./monty-sandbox": {
       "types": "./lib/src/monty-sandbox.d.ts",
       "default": "./lib/src/monty-sandbox.js"
@@ -337,6 +352,10 @@
       "types": "./lib/src/skill-paths.d.ts",
       "default": "./lib/src/skill-paths.js"
     },
+    "./skill-search": {
+      "types": "./lib/src/skill-search.d.ts",
+      "default": "./lib/src/skill-search.js"
+    },
     "./statement": {
       "types": "./lib/src/statement.d.ts",
       "default": "./lib/src/statement.js"

package/src/agents.ts

@@ -25,7 +25,7 @@ import type {
 } from "@databricks/appkit/beta";
 import { pluginRegistry, toolkitEntries } from "@dbx-tools/appkit";
 import type { AgentToolExecutionContext } from "@dbx-tools/appkit/tool-provider";
-import { log, object, stringUtils } from "@dbx-tools/shared-core";
+import { errorUtils, log, object, stringUtils } from "@dbx-tools/shared-core";
 import { TOOL_PROGRESS_PART_TYPE, ToolProgressEventSchema } from "@dbx-tools/shared-mastra/wire";
 import type {
   AgentConfig,
@@ -35,6 +35,7 @@ import type {
 } from "@mastra/core/agent";
 import { Agent } from "@mastra/core/agent";
 import { SkillSearchProcessor } from "@mastra/core/processors";
+import type { OutputProcessor } from "@mastra/core/processors";
 import { MASTRA_RESOURCE_ID_KEY } from "@mastra/core/request-context";
 import type { Tool } from "@mastra/core/tools";
 import { createTool } from "@mastra/core/tools";
@@ -48,9 +49,10 @@ import type { MemoryBuilder } from "./memory.ts";
 import { buildModel, RESPONSES_PROVIDER_OPTIONS } from "./model.ts";
 import { stripStaleChartsProcessor } from "./processors.ts";
 import { MASTRA_RESOLVED_MODEL_KEY } from "./serving.ts";
+import { CatalogueSkillSearchProcessor } from "./skill-search.ts";
 import { TYPOGRAPHY_RULE } from "./style.ts";
 import { buildSummarizeTool } from "./summarize.ts";
-import { createWorkspace } from "./workspaces.ts";
+import { createWorkspace, workspaceSkillCatalogueResolver } from "./workspaces.ts";
 
 /**
  * Tool record accepted by every Mastra `Agent.tools` field and by the
@@ -583,8 +585,7 @@ export async function buildAgents(opts: {
         ...(config.workspaceSkillRefreshTtlMs !== undefined
           ? { workspaceSkillRefreshTtlMs: config.workspaceSkillRefreshTtlMs }
           : {}),
-        sandbox:
-          config.sandbox === undefined || config.sandbox === true ? "databricks" : config.sandbox,
+        sandbox: config.sandbox === true ? "databricks" : config.sandbox,
       });
       markDefaultWorkspace(workspace);
     }
@@ -613,6 +614,7 @@ export async function buildAgents(opts: {
       ...(memory ? { memory } : {}),
       ...(workspace ? { workspace } : {}),
       inputProcessors: [...inputProcessors, ...workspaceSkillInputProcessors(workspace, config)],
+      outputProcessors: [toolErrorLoggingProcessor(log)],
     });
     // Surface the effective default model per agent so operators can
     // see at a glance which endpoint each agent points at without
@@ -644,13 +646,44 @@ export async function buildAgents(opts: {
   return { agents, defaultAgentId, defaultModels, ambientTools };
 }
 
+/** Log failed tool calls without changing the chunks returned to the client. */
+function toolErrorLoggingProcessor(logger: log.Logger): OutputProcessor {
+  return {
+    id: "tool-error-logger",
+    async processOutputStream({ part }) {
+      if (part.type === "tool-error") {
+        const error = errorUtils.toError(part.payload.error);
+        logger.error("tool execution failed", {
+          toolName: part.payload.toolName,
+          toolCallId: part.payload.toolCallId,
+          error: error.message,
+          stack: error.stack,
+        });
+      }
+      return part;
+    },
+  };
+}
+
 function workspaceSkillInputProcessors(
   workspace: Workspace | undefined,
   config: MastraPluginConfig,
-): SkillSearchProcessor[] {
-  if (!workspace?.skills || config.workspaceSkillSearch === false) return [];
+): Array<SkillSearchProcessor | CatalogueSkillSearchProcessor> {
+  if (!workspace || config.workspaceSkillSearch === false) return [];
   const options =
     typeof config.workspaceSkillSearch === "object" ? config.workspaceSkillSearch : undefined;
+  const catalogue = workspaceSkillCatalogueResolver(workspace);
+  if (catalogue) {
+    return [
+      new CatalogueSkillSearchProcessor({
+        resolve: catalogue,
+        topK: options?.topK ?? 5,
+        minScore: options?.minScore ?? 0.1,
+        ...(options?.ttlMs !== undefined ? { ttlMs: options.ttlMs } : {}),
+      }),
+    ];
+  }
+  if (!workspace.skills) return [];
   return [
     new SkillSearchProcessor({
       workspace,

package/src/config.ts

@@ -211,20 +211,20 @@ export interface MastraPluginConfig extends BasePluginConfig {
    */
   memory?: boolean | MastraMemoryConfig;
   /**
-   * Sandbox for auto-created agent workspaces. Defaults to Databricks Sandbox.
-   * `true` selects Databricks with defaults, an object configures its lifecycle,
-   * and `false` disables workspace command execution. An agent with an explicit
+   * Sandbox for auto-created agent workspaces. Defaults to Monty. `true`,
+   * `"databricks"`, or an object selects/configures Databricks Sandbox, and
+   * `false` disables workspace command execution. An agent with an explicit
    * custom `workspace` keeps that workspace and its sandbox.
    */
   sandbox?: boolean | "databricks" | "monty" | DatabricksWorkspaceSandboxOptions;
   /**
-   * AppKit cache TTL for user-scoped Databricks workspace skill files.
-   * Defaults to five minutes.
+   * Refresh TTL for the complete user-scoped workspace skill catalogue.
+   * Defaults to five minutes; auxiliary files remain uncached.
    */
   workspaceSkillRefreshTtlMs?: number;
   /**
-   * Use Mastra's on-demand skill search instead of injecting the full skill
-   * catalogue. Defaults to true. Pass an object to tune search.
+   * Use dbx-tools catalogue-backed on-demand skill search. Defaults to true.
+   * Pass an object to tune search.
    */
   workspaceSkillSearch?: boolean | MastraSkillSearchConfig;
   /**
@@ -665,17 +665,17 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     sandbox: {
       type: ["boolean", "string", "object"],
       description:
-        'Command sandbox for auto-created agent workspaces. Defaults to Databricks Sandbox with Monty fallback; false disables command execution, "monty" selects Monty directly, and an object configures Databricks lifecycle/fallback settings.',
+        'Command sandbox for auto-created agent workspaces. Defaults to Monty; false disables command execution, and true, "databricks", or an object selects/configures Databricks Sandbox with optional fallback.',
     },
     workspaceSkillRefreshTtlMs: {
       type: "number",
       description:
-        "AppKit cache TTL in milliseconds for user-scoped Databricks workspace skill files. Defaults to 5 minutes.",
+        "Refresh TTL in milliseconds for the complete user-scoped workspace skill catalogue. Defaults to 5 minutes; auxiliary file reads stay fresh.",
     },
     workspaceSkillSearch: {
       type: ["boolean", "object"],
       description:
-        "Use Mastra on-demand skill search instead of injecting every skill description. Defaults to true.",
+        "Use dbx-tools catalogue-backed on-demand skill search with lazy auxiliary reads. Defaults to true.",
     },
     defaultAgent: {
       type: "string",

package/src/genie.ts

@@ -52,6 +52,7 @@ 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";
@@ -1089,26 +1090,20 @@ const SUGGESTION_LIMIT = 6;
  */
 const SUGGESTION_CACHE_TTL_MS = 10 * 60_000;
 
-/** Space-id -> cached sample questions with an absolute expiry. */
-const _suggestionCache = new Map<string, { questions: string[]; expires: number }>();
+/** Bounded process-local cache of parsed sample questions by Genie space id. */
+const _suggestionCache = new LRUCache<string, string[]>({
+  max: 128,
+  ttl: SUGGESTION_CACHE_TTL_MS,
+});
 
 /** Read a space's cached questions, or `undefined` on miss / expiry. */
 function readSuggestionCache(spaceId: string): string[] | undefined {
-  const entry = _suggestionCache.get(spaceId);
-  if (!entry) return undefined;
-  if (entry.expires <= Date.now()) {
-    _suggestionCache.delete(spaceId);
-    return undefined;
-  }
-  return entry.questions;
+  return _suggestionCache.get(spaceId);
 }
 
 /** Cache a space's parsed questions for {@link SUGGESTION_CACHE_TTL_MS}. */
 function writeSuggestionCache(spaceId: string, questions: string[]): void {
-  _suggestionCache.set(spaceId, {
-    questions,
-    expires: Date.now() + SUGGESTION_CACHE_TTL_MS,
-  });
+  _suggestionCache.set(spaceId, questions);
 }
 
 /**

package/src/mlflow.ts

@@ -30,8 +30,8 @@ import { appkit } from "@dbx-tools/appkit";
 import { asyncUtils, errorUtils, log, object } from "@dbx-tools/shared-core";
 import { feedback } from "@dbx-tools/shared-mastra";
 import { TraceLocationType, TraceMetadataKey } from "@mlflow/core";
-import { TraceInfo } from "@mlflow/core/dist/core/entities/trace_info";
-import { TraceState } from "@mlflow/core/dist/core/entities/trace_state";
+import { TraceInfo } from "@mlflow/core/dist/core/entities/trace_info.js";
+import { TraceState } from "@mlflow/core/dist/core/entities/trace_state.js";
 import type { Context } from "@opentelemetry/api";
 import type { ReadableSpan, Span as SdkSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import type { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
@@ -455,7 +455,7 @@ async function detectedDirectMlflowTraceLocation(
     const client = new mlflow.MlflowClient({ trackingUri, authProvider });
     const experiment = await client.getExperiment(experimentId);
     if (!experiment) return undefined;
-    const { ucLocationFromExperimentTags } = await import("@mlflow/core/dist/core/destination");
+    const { ucLocationFromExperimentTags } = await import("@mlflow/core/dist/core/destination.js");
     const location = ucLocationFromExperimentTags(experiment.tags);
     if (!location?.tablePrefix) return undefined;
     return {
@@ -505,7 +505,7 @@ export async function initializeDirectMlflowTracing(): Promise<boolean> {
     }
     const [{ DatabricksUCTableSpanExporter, DatabricksUCTableSpanProcessor }, sdk] =
       await Promise.all([
-        import("@mlflow/core/dist/exporters/uc_table"),
+        import("@mlflow/core/dist/exporters/uc_table.js"),
         import("@opentelemetry/sdk-trace-node"),
       ]);
     const authProvider = mlflow.createAuthProvider({

package/src/monty-native.ts

@@ -0,0 +1,149 @@
+/**
+ * Ensures Monty's platform native package is present before the Node addon loads.
+ *
+ * `@pydantic/monty` ships `@pydantic/monty-<platform>` as optionalDependencies.
+ * npm can skip those (https://github.com/npm/cli/issues/4828), which surfaces as
+ * "Cannot find native binding". This module installs only the current platform
+ * package, at the already-installed `@pydantic/monty` version, without rewriting
+ * package.json.
+ *
+ * @module
+ */
+
+import { createRequire } from "node:module";
+import { COMMAND_NOT_FOUND_EXIT_CODE, exec } from "@dbx-tools/core";
+import { errorUtils, log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("mastra/monty-native");
+const requireFromHere = createRequire(import.meta.url);
+
+/** Result of spawning the package installer. */
+export interface MontyNativeInstallResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Installer used by {@link ensureMontyNativeBinding}. */
+export type MontyNativeInstaller = (
+  command: string,
+  args: readonly string[],
+  options: { cwd: string },
+) => Promise<MontyNativeInstallResult>;
+
+/** Overrides for {@link ensureMontyNativeBinding} (tests inject resolve/install). */
+export interface EnsureMontyNativeBindingOptions {
+  /** Working directory for the in-place install. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Module resolver; defaults to `createRequire(import.meta.url).resolve`. */
+  resolve?: (specifier: string) => string;
+  /** Package installer; defaults to npm, then bun when npm is missing. */
+  install?: MontyNativeInstaller;
+}
+
+/**
+ * npm package that ships Monty's `.node` addon and `monty` binary for this
+ * process. Matches `@pydantic/monty`'s `platformTriple()` / optionalDependencies.
+ */
+export function montyNativeBindingPackage(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | undefined {
+  if (platform === "darwin" && (arch === "x64" || arch === "arm64")) {
+    return `@pydantic/monty-darwin-${arch}`;
+  }
+  if (platform === "linux" && (arch === "x64" || arch === "arm64")) {
+    return `@pydantic/monty-linux-${arch}-gnu`;
+  }
+  if (platform === "win32" && arch === "x64") {
+    return "@pydantic/monty-win32-x64-msvc";
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the current platform's Monty native package, installing it in place
+ * when npm omitted the optional dependency.
+ */
+export async function ensureMontyNativeBinding(
+  options: EnsureMontyNativeBindingOptions = {},
+): Promise<void> {
+  const pkg = montyNativeBindingPackage();
+  if (!pkg) return;
+
+  const resolve = options.resolve ?? ((specifier: string) => requireFromHere.resolve(specifier));
+  if (isResolvable(pkg, resolve)) return;
+
+  const version = montyPackageVersion(resolve);
+  const spec = `${pkg}@${version}`;
+  const cwd = options.cwd ?? process.cwd();
+  logger.warn("native-binding:missing", { package: spec, cwd });
+
+  const install = options.install ?? defaultInstaller;
+  const output = await installNativePackage(spec, cwd, install);
+  if (!isResolvable(pkg, resolve)) {
+    throw new Error(
+      `Monty native binding ${spec} is still missing after ${output.command}. ${output.detail}`,
+    );
+  }
+  logger.info("native-binding:installed", { package: spec, command: output.command });
+}
+
+function isResolvable(specifier: string, resolve: (specifier: string) => string): boolean {
+  try {
+    resolve(`${specifier}/package.json`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function montyPackageVersion(resolve: (specifier: string) => string): string {
+  const pkg = requireFromHere(resolve("@pydantic/monty/package.json")) as { version?: string };
+  const version = pkg.version?.trim();
+  if (!version) throw new Error("Installed @pydantic/monty has no version");
+  return version;
+}
+
+async function installNativePackage(
+  spec: string,
+  cwd: string,
+  install: MontyNativeInstaller,
+): Promise<{ command: string; detail: string }> {
+  const npm = await install("npm", ["install", spec, "--no-save", "--no-package-lock"], { cwd });
+  if (npm.exitCode === 0) return { command: `npm install ${spec}`, detail: npm.stdout };
+  if (npm.exitCode !== COMMAND_NOT_FOUND_EXIT_CODE) {
+    throw new Error(
+      `Failed to install ${spec} with npm (exit ${npm.exitCode}): ${installDetail(npm)}`,
+    );
+  }
+
+  const bun = await install("bun", ["add", spec, "--no-save"], { cwd });
+  if (bun.exitCode === 0) return { command: `bun add ${spec}`, detail: bun.stdout };
+  throw new Error(
+    `Failed to install ${spec}: npm was not found, bun add exited ${bun.exitCode}: ${installDetail(bun)}`,
+  );
+}
+
+async function defaultInstaller(
+  command: string,
+  args: readonly string[],
+  options: { cwd: string },
+): Promise<MontyNativeInstallResult> {
+  const result = await exec.spawn(command, [...args], {
+    cwd: options.cwd,
+    stdout: "capture",
+    stderr: "capture",
+    stdin: "ignore",
+    check: false,
+  });
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+function installDetail(result: MontyNativeInstallResult): string {
+  return errorUtils.errorMessage(result.stderr || result.stdout || `exit ${result.exitCode}`);
+}

package/src/monty-sandbox.ts

@@ -17,10 +17,15 @@ import type {
 } from "@mastra/core/workspace";
 import type { CheckoutOptions, Monty as MontyPool, MontySession } from "@pydantic/monty/node";
 
+import { ensureMontyNativeBinding } from "./monty-native.ts";
+
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_MEMORY_BYTES = 10_000_000;
 
-const montyModule = functionUtils.memoize(() => import("@pydantic/monty/node"));
+const montyModule = functionUtils.memoize(async () => {
+  await ensureMontyNativeBinding();
+  return import("@pydantic/monty/node");
+});
 const montyPool = functionUtils.memoize(async (): Promise<MontyPool> => {
   const { Monty } = await montyModule();
   return Monty.create({
@@ -140,7 +145,7 @@ export class MontySandbox implements WorkspaceSandbox {
       pool,
       {
         limits: {
-          maxDurationSecs: Math.max(0.001, timeout / 1_000),
+          maxFeedDurationSecs: Math.max(0.001, timeout / 1_000),
           maxMemory: this.maxMemoryBytes,
         },
         typeCheck: this.typeCheck,

package/src/remote-skills.ts

@@ -74,6 +74,7 @@ import type { OneOrMany } from "@dbx-tools/shared-core";
 import type { FileSystem } from "@dbx-tools/shared-fs";
 
 import { ASSISTANT_SHARED_SKILLS_PATH, userAssistantSkillsPath } from "./skill-paths.ts";
+import { clearWorkspaceSkillCache } from "./skill-cache.ts";
 
 const logger = log.logger("mastra/remote-skills");
 
@@ -441,6 +442,7 @@ export async function provisionRemoteSkills(
   const localSkillPaths: string[] = [];
   const skillNames: string[] = [];
   let staging: LocalFileSystem | undefined;
+  let workspaceUpdated = false;
 
   try {
     const sources = Array.isArray(options.sources) ? options.sources : [options.sources];
@@ -452,7 +454,8 @@ export async function provisionRemoteSkills(
         // the source's own stable local dir.
         const key = cacheKey(sourceOptions);
         const cacheFS = destination ?? localSkillsFS(key);
-        const cached = (await readMetadata(cacheFS))?.sources[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);
@@ -483,10 +486,12 @@ export async function provisionRemoteSkills(
           ...(policy ? { policy } : {}),
         };
         if (destination && databricksBasePath) {
+          await removeDeletedSkills(destination, key, metadata, record.skills);
           await copySkillDirs(destination, staged);
           // Only after the copy lands: a metadata entry written first would
           // mark a failed provision as fresh and suppress the retry for a day.
           await writeMetadata(destination, key, record);
+          workspaceUpdated = true;
         } else {
           localSkillPaths.push(await persistLocally(key, staged, record));
         }
@@ -515,9 +520,35 @@ export async function provisionRemoteSkills(
     }
   }
 
+  if (workspaceUpdated && client?.config?.getHost) {
+    await clearWorkspaceSkillCache({
+      host: (await client.config.getHost()).toString(),
+    });
+  }
+
   return { localSkillPaths, databricksBasePath, skillNames };
 }
 
+/** Remove directories dropped by one source unless another source still owns them. */
+async function removeDeletedSkills(
+  destination: FileSystem,
+  key: string,
+  metadata: RemoteSkillsMetadata | undefined,
+  nextSkills: readonly string[],
+): Promise<void> {
+  const previous = metadata?.sources[key]?.skills ?? [];
+  const retained = new Set(nextSkills);
+  for (const [sourceKey, entry] of Object.entries(metadata?.sources ?? {})) {
+    if (sourceKey === key) continue;
+    for (const skill of entry.skills) retained.add(skill);
+  }
+  await Promise.all(
+    previous
+      .filter((skill) => !retained.has(skill))
+      .map((skill) => destination.rmdir(skill, { force: true, recursive: true })),
+  );
+}
+
 /** Probe file {@link openWritableWorkspace} writes and removes. */
 const WRITE_PROBE_FILE = ".dbx-tools-write-probe";