@dbx-tools/appkit-mastra 0.9.74 → 0.9.93

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-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.93",
+    "@dbx-tools/core": "^0.9.93",
+    "@dbx-tools/databricks": "^0.9.93",
+    "@dbx-tools/fs": "^0.9.93",
+    "@dbx-tools/genie": "^0.9.93",
+    "@dbx-tools/model": "^0.9.93",
+    "@dbx-tools/path": "^0.9.93",
+    "@dbx-tools/postgres": "^0.9.93",
+    "@dbx-tools/shared-core": "^0.9.93",
+    "@dbx-tools/shared-fs": "^0.9.93",
+    "@dbx-tools/shared-genie": "^0.9.93",
+    "@dbx-tools/shared-mastra": "^0.9.93",
+    "@dbx-tools/shared-model": "^0.9.93",
     "@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",
@@ -181,6 +184,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 +227,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.74",
+  "version": "0.9.93",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -337,6 +344,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-sandbox.ts

@@ -1,33 +1,70 @@
 /**
  * Pydantic Monty fallback for Mastra command execution.
  *
- * Uses the Node subprocess-worker build of Monty. It executes Python source
+ * Prefers Monty's native Node subprocess workers and falls back to its WASM
+ * workers when the native package is unavailable. It executes Python source
  * with no host filesystem, network, environment, shell, or third-party package
- * access unless a future caller explicitly adds those capabilities.
+ * access.
  *
  * @module
  */
 
-import { errorUtils, functionUtils } from "@dbx-tools/shared-core";
+import { configUtils } from "@dbx-tools/core";
+import { errorUtils, functionUtils, log } from "@dbx-tools/shared-core";
 import type {
   CommandResult,
   ExecuteCommandOptions,
   SandboxInfo,
   WorkspaceSandbox,
 } from "@mastra/core/workspace";
-import type { CheckoutOptions, Monty as MontyPool, MontySession } from "@pydantic/monty/node";
+import type { CheckoutOptions, Monty, MontyCrashedError, MontySession } from "@pydantic/monty";
 
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_MEMORY_BYTES = 10_000_000;
+const NATIVE_MONTY_TARGET = {
+  name: "native Monty",
+  load: () => import("@pydantic/monty/node"),
+} as const;
+const WASM_MONTY_TARGET = {
+  name: "WASM Monty",
+  load: () => import("@pydantic/monty/wasm"),
+} as const;
+const logger = log.logger("mastra/monty");
+
+type MontyPool = Pick<Monty, "checkout">;
+
+interface MontyContext {
+  crashedError: typeof MontyCrashedError;
+  pool: MontyPool;
+}
 
-const montyModule = functionUtils.memoize(() => import("@pydantic/monty/node"));
-const montyPool = functionUtils.memoize(async (): Promise<MontyPool> => {
-  const { Monty } = await montyModule();
-  return Monty.create({
-    minProcesses: 1,
-    maxProcesses: 4,
-    requestTimeout: 35,
-  });
+const montyContext = functionUtils.memoize(async (): Promise<MontyContext> => {
+  const errors: Error[] = [];
+  const targets = configUtils.boolean(undefined, "MONTY_FORCE_WASM")
+    ? [WASM_MONTY_TARGET]
+    : [NATIVE_MONTY_TARGET, WASM_MONTY_TARGET];
+  for (const target of targets) {
+    try {
+      const module = await target.load();
+      logger.debug(`${target.name} module available`);
+      const pool = await module.Monty.create({
+        minProcesses: 1,
+        maxProcesses: 4,
+        requestTimeout: 35,
+      });
+      logger.debug(`${target.name} pool created`);
+      return {
+        crashedError: module.MontyCrashedError,
+        pool,
+      };
+    } catch (error) {
+      errors.push(errorUtils.toError(error));
+      logger.debug(`${target.name} unavailable`, {
+        error: errorUtils.errorMessage(error),
+      });
+    }
+  }
+  throw new AggregateError(errors, "Failed to create Monty pool");
 });
 
 /** Resource controls for the Monty Python fallback. */
@@ -44,7 +81,7 @@ export interface MontySandboxOptions {
   typeCheck?: boolean;
 }
 
-/** Python-only, deny-by-default sandbox backed by Monty's Node worker pool. */
+/** Python-only, deny-by-default sandbox backed by Monty's selected worker pool. */
 export class MontySandbox implements WorkspaceSandbox {
   readonly id: string;
   readonly name: string;
@@ -72,7 +109,7 @@ export class MontySandbox implements WorkspaceSandbox {
     this.status = "starting";
     this.error = undefined;
     try {
-      await montyPool();
+      await montyContext();
       this.status = "running";
     } catch (caught) {
       this.status = "error";
@@ -135,12 +172,12 @@ export class MontySandbox implements WorkspaceSandbox {
 
     await this.start();
     const timeout = options.timeout ?? this.commandTimeoutMs;
-    const pool = await montyPool();
+    const pool = (await montyContext()).pool;
     const session = await checkoutSession(
       pool,
       {
         limits: {
-          maxDurationSecs: Math.max(0.001, timeout / 1_000),
+          maxFeedDurationSecs: Math.max(0.001, timeout / 1_000),
           maxMemory: this.maxMemoryBytes,
         },
         typeCheck: this.typeCheck,
@@ -183,8 +220,8 @@ export class MontySandbox implements WorkspaceSandbox {
       }
       const message = errorUtils.errorMessage(caught);
       output.emit("stderr", output.stderr.value ? `\n${message}` : message);
-      const { MontyCrashedError } = await montyModule();
-      const timedOut = caught instanceof MontyCrashedError && caught.timedOut;
+      const { crashedError } = await montyContext();
+      const timedOut = caught instanceof crashedError && caught.timedOut;
       return {
         command,
         args,
@@ -404,3 +441,10 @@ function failedResult(
     executionTimeMs: performance.now() - started,
   };
 }
+
+if (import.meta.main) {
+  const sandbox = new MontySandbox();
+  await sandbox.start();
+  console.log(await sandbox.executeCommand("print('Hello, world!')"));
+  await sandbox.stop();
+}

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";