@dbx-tools/appkit-mastra 0.9.93 → 0.9.99

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/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"}
+{"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-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"}

package/package.json

@@ -34,19 +34,19 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@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",
+    "@dbx-tools/appkit": "^0.9.99",
+    "@dbx-tools/core": "^0.9.99",
+    "@dbx-tools/databricks": "^0.9.99",
+    "@dbx-tools/fs": "^0.9.99",
+    "@dbx-tools/genie": "^0.9.99",
+    "@dbx-tools/model": "^0.9.99",
+    "@dbx-tools/path": "^0.9.99",
+    "@dbx-tools/postgres": "^0.9.99",
+    "@dbx-tools/shared-core": "^0.9.99",
+    "@dbx-tools/shared-fs": "^0.9.99",
+    "@dbx-tools/shared-genie": "^0.9.99",
+    "@dbx-tools/shared-mastra": "^0.9.99",
+    "@dbx-tools/shared-model": "^0.9.99",
     "@mastra/ai-sdk": "1.10.5",
     "@mastra/core": "1.71.0",
     "@mastra/express": "1.5.15",
@@ -176,18 +176,10 @@
         "types": "./lib/src/serving.d.ts",
         "default": "./lib/src/serving.js"
       },
-      "./skill-cache": {
-        "types": "./lib/src/skill-cache.d.ts",
-        "default": "./lib/src/skill-cache.js"
-      },
       "./skill-paths": {
         "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"
@@ -227,7 +219,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.93",
+  "version": "0.9.99",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -336,18 +328,10 @@
       "types": "./lib/src/serving.d.ts",
       "default": "./lib/src/serving.js"
     },
-    "./skill-cache": {
-      "types": "./lib/src/skill-cache.d.ts",
-      "default": "./lib/src/skill-cache.js"
-    },
     "./skill-paths": {
       "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

@@ -49,10 +49,9 @@ 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, workspaceSkillCatalogueResolver } from "./workspaces.ts";
+import { bindDatabricksWorkspaceContext, databricksWorkspace } from "./workspaces.ts";
 
 /**
  * Tool record accepted by every Mastra `Agent.tools` field and by the
@@ -169,8 +168,8 @@ function deriveToolId(description: string): string {
  * ```
  *
  * Adds the package's default workspace when the definition omits one. That
- * workspace carries Databricks skill mounts and Databricks Sandbox command
- * execution. An explicit workspace remains the caller's complete override.
+ * workspace carries Databricks skill mounts and Monty command execution. An
+ * explicit workspace remains the caller's complete override.
  */
 export function createAgent<
   TRequestContext extends Record<string, unknown> | unknown = unknown,
@@ -178,7 +177,7 @@ export function createAgent<
     MastraAgentDefinition<TRequestContext>,
 >(def: TDefinition): TDefinition {
   if (def.workspace) return { ...def };
-  const workspace = createWorkspace();
+  const workspace = databricksWorkspace();
   markDefaultWorkspace(workspace);
   return { ...def, workspace };
 }
@@ -188,16 +187,16 @@ export function createAgent<
  * options, so {@link buildAgents} may rebuild it with startup-provisioned
  * `extraSkillPaths` (a caller-supplied workspace is never touched).
  */
-const DEFAULT_WORKSPACE = Symbol.for("dbx-tools/appkit-mastra/default-workspace");
+const defaultWorkspaces = new WeakSet<Workspace>();
 
 /** Brand `workspace` as the auto-created default. */
 function markDefaultWorkspace(workspace: Workspace): void {
-  (workspace as unknown as Record<symbol, boolean>)[DEFAULT_WORKSPACE] = true;
+  defaultWorkspaces.add(workspace);
 }
 
 /** Whether `workspace` was auto-created by {@link createAgent}. */
 function isDefaultWorkspace(workspace: Workspace | undefined): boolean {
-  return Boolean(workspace && (workspace as unknown as Record<symbol, boolean>)[DEFAULT_WORKSPACE]);
+  return workspace !== undefined && defaultWorkspaces.has(workspace);
 }
 
 /**
@@ -339,7 +338,7 @@ export interface MastraAgentDefinition<
   /**
    * Mastra {@link Workspace} for this agent (filesystem, sandbox, or other
    * providers). Assistant skills from Databricks workspace paths are wired
-   * via {@link createWorkspace}.
+   * via {@link databricksWorkspace}.
    */
   workspace?: Workspace | MastraAgentWorkspaceResolver;
 }
@@ -577,17 +576,19 @@ export async function buildAgents(opts: {
       (def.workspace === undefined && !workspace) ||
       ((extraSkillPaths?.length ||
         config.sandbox !== undefined ||
-        config.workspaceSkillRefreshTtlMs !== undefined) &&
+        config.workspaceTools !== undefined ||
+        context !== undefined) &&
         isDefaultWorkspace(workspace))
     ) {
-      workspace = createWorkspace({
+      workspace = databricksWorkspace({
         extraSkillPaths,
-        ...(config.workspaceSkillRefreshTtlMs !== undefined
-          ? { workspaceSkillRefreshTtlMs: config.workspaceSkillRefreshTtlMs }
-          : {}),
+        ...(config.workspaceTools !== undefined ? { tools: config.workspaceTools } : {}),
+        pluginContext: context,
         sandbox: config.sandbox === true ? "databricks" : config.sandbox,
       });
       markDefaultWorkspace(workspace);
+    } else if (workspace) {
+      workspace = bindDatabricksWorkspaceContext(workspace, context);
     }
     const gated = approvalGatedToolIds(tools);
     if (gated.length > 0) approvalGatedByAgent.push({ agentId: id, toolIds: gated });
@@ -668,21 +669,9 @@ function toolErrorLoggingProcessor(logger: log.Logger): OutputProcessor {
 function workspaceSkillInputProcessors(
   workspace: Workspace | undefined,
   config: MastraPluginConfig,
-): 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 } : {}),
-      }),
-    ];
-  }
+): SkillSearchProcessor[] {
+  if (!workspace || config.workspaceSkills === false) return [];
+  const options = typeof config.workspaceSkills === "object" ? config.workspaceSkills : undefined;
   if (!workspace.skills) return [];
   return [
     new SkillSearchProcessor({

package/src/chat.ts

@@ -4,9 +4,16 @@
  * @module
  */
 
+import { errorUtils, log } from "@dbx-tools/shared-core";
 import { routes } from "@dbx-tools/shared-mastra";
+import {
+  isStaleMastraResumeError,
+  STALE_MASTRA_RESUME_STREAM_TEXT,
+} from "@dbx-tools/shared-mastra/resume";
 import { chatRoute } from "@mastra/ai-sdk";
 
+const logger = log.logger("mastra/chat");
+
 /** Register the official AI SDK chat stream plus its approval continuation. */
 export function agentChatRoutes() {
   const path = `${routes.MASTRA_ROUTES.chat}/:agentId` as `${string}:agentId`;
@@ -15,6 +22,23 @@ export function agentChatRoutes() {
       path,
       sendReasoning: true,
       sendSources: true,
+      onError: serializeChatStreamError,
     }),
   ];
 }
+
+/**
+ * Keep a late or duplicate resume from failing the UI stream. Mastra's
+ * `chatRoute` already swallows a couple of resume ids on the v6 approval
+ * path; this covers the generic workflow errors `consumeStream` still
+ * surfaces on v5.
+ */
+function serializeChatStreamError(error: unknown): string {
+  if (isStaleMastraResumeError(error)) {
+    logger.warn("ignored stale mastra resume", {
+      error: errorUtils.errorMessage(error),
+    });
+    return STALE_MASTRA_RESUME_STREAM_TEXT;
+  }
+  return errorUtils.errorMessage(error);
+}

package/src/config.ts

@@ -20,6 +20,7 @@ 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 { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
 import type { AnyMastraAgentDefinition, MastraTools } from "./agents.ts";
@@ -147,8 +148,8 @@ export type MastraMemoryConfig = PgVectorConfig & {
   id?: string;
 };
 
-/** On-demand workspace skill search configuration. */
-export interface MastraSkillSearchConfig {
+/** Mastra native workspace skill-search configuration. */
+export interface MastraWorkspaceSkillsConfig {
   /** Maximum skill matches returned by one search. Defaults to 5. */
   topK?: number;
   /** Minimum BM25 relevance score. Defaults to 0.1. */
@@ -217,16 +218,13 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * custom `workspace` keeps that workspace and its sandbox.
    */
   sandbox?: boolean | "databricks" | "monty" | DatabricksWorkspaceSandboxOptions;
+  /** Native Mastra workspace tool availability, approval, and hook configuration. */
+  workspaceTools?: WorkspaceToolsConfig;
   /**
-   * Refresh TTL for the complete user-scoped workspace skill catalogue.
-   * Defaults to five minutes; auxiliary files remain uncached.
+   * Use Mastra's native workspace skill manager. Defaults to true. Pass an
+   * object to tune on-demand discovery and loaded-skill state.
    */
-  workspaceSkillRefreshTtlMs?: number;
-  /**
-   * Use dbx-tools catalogue-backed on-demand skill search. Defaults to true.
-   * Pass an object to tune search.
-   */
-  workspaceSkillSearch?: boolean | MastraSkillSearchConfig;
+  workspaceSkills?: boolean | MastraWorkspaceSkillsConfig;
   /**
    * Code-defined agents. Accepts three shapes for convenience:
    *
@@ -613,7 +611,7 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * through neither fails startup unless `failOnError: false`.
    *
    * Provisioned skills are written to the Databricks user's Assistant skills
-   * folder (`/Users/<email>/.assistant/skills`, the "save this as a skill"
+   * 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.
    *
@@ -667,15 +665,15 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
       description:
         '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",
+    workspaceSkills: {
+      type: ["boolean", "object"],
       description:
-        "Refresh TTL in milliseconds for the complete user-scoped workspace skill catalogue. Defaults to 5 minutes; auxiliary file reads stay fresh.",
+        "Use Mastra's native on-demand workspace skill search and writable skill saves. Defaults to true.",
     },
-    workspaceSkillSearch: {
-      type: ["boolean", "object"],
+    workspaceTools: {
+      type: "object",
       description:
-        "Use dbx-tools catalogue-backed on-demand skill search with lazy auxiliary reads. Defaults to true.",
+        "Native Mastra workspace tool configuration for availability, approvals, read-before-write, output limits, and hooks.",
     },
     defaultAgent: {
       type: "string",

package/src/filesystems.ts

@@ -22,12 +22,14 @@ import {
   FileExistsError,
   FileNotFoundError,
   IsDirectoryError,
+  CompositeFilesystem,
   MastraFilesystem,
   NotDirectoryError,
   PermissionError,
   WorkspaceReadOnlyError,
 } from "@mastra/core/workspace";
 import type {
+  CompositeFilesystemConfig,
   CopyOptions,
   FileContent,
   FileEntry,
@@ -49,6 +51,15 @@ export interface MastraFileSystemAdapterOptions extends MastraFilesystemOptions
   /** Override the Mastra display name. Defaults to `MastraFileSystemAdapter`. */
   name?: string;
 
+  /** Human-friendly mount name surfaced by composite filesystem listings. */
+  displayName?: string;
+
+  /** Mount description surfaced by composite filesystem listings and help. */
+  description?: string;
+
+  /** Replace the generated filesystem usage instructions. */
+  instructions?: string;
+
   /**
    * Override the Mastra provider id. Defaults to the source
    * {@link FileSystem.backend}.
@@ -117,6 +128,14 @@ export class MastraFileSystemAdapter extends MastraFilesystem {
     return this.options.provider ?? this.fs.backend;
   }
 
+  get displayName(): string | undefined {
+    return this.options.displayName;
+  }
+
+  get description(): string | undefined {
+    return this.options.description;
+  }
+
   get readOnly(): boolean {
     return this.options.readOnly === true || this.fs.readOnly;
   }
@@ -145,7 +164,9 @@ export class MastraFileSystemAdapter extends MastraFilesystem {
   }
 
   getInstructions(): string {
+    if (this.options.instructions !== undefined) return this.options.instructions;
     return [
+      ...(this.description ? [this.description] : []),
       `Files are served by a ${this.fs.backend} filesystem rooted at ${this.fs.root}.`,
       "Workspace paths are absolute within this mount (for example `/notes/report.md`).",
     ].join(" ");
@@ -298,6 +319,28 @@ export class MastraFileSystemAdapter extends MastraFilesystem {
   }
 }
 
+/**
+ * Composite mount namespace whose virtual root has no repository-level
+ * `.gitignore`. Mastra's list tool probes that relative file before walking;
+ * an empty result keeps native ignore handling enabled without routing the
+ * virtual-root lookup into an unrelated mount.
+ */
+export class MountedCompositeFilesystem extends CompositeFilesystem {
+  constructor(config: CompositeFilesystemConfig) {
+    super(config);
+  }
+
+  override async readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer> {
+    if (
+      (inputPath === ".gitignore" || inputPath === "/.gitignore") &&
+      !this.getFilesystemForPath(inputPath)
+    ) {
+      return options?.encoding ? "" : Buffer.alloc(0);
+    }
+    return super.readFile(inputPath, options);
+  }
+}
+
 /** Fresh writable local temp mount on a root unique to this call. */
 export function scratchFilesystem(): MastraFileSystemAdapter {
   return filesystems(localFS.scratchFS("mastra"));

package/src/monty-sandbox.ts

@@ -11,12 +11,13 @@
 
 import { configUtils } from "@dbx-tools/core";
 import { errorUtils, functionUtils, log } from "@dbx-tools/shared-core";
+import { availableParallelism } from "node:os";
 import type {
   CommandResult,
   ExecuteCommandOptions,
   SandboxInfo,
-  WorkspaceSandbox,
 } from "@mastra/core/workspace";
+import { MastraSandbox, type ProviderStatus } from "@mastra/core/workspace";
 import type { CheckoutOptions, Monty, MontyCrashedError, MontySession } from "@pydantic/monty";
 
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
@@ -38,6 +39,11 @@ interface MontyContext {
   pool: MontyPool;
 }
 
+/** @internal Size the shared worker pool from the host's available processors. */
+export function montyMaxProcesses(parallelism: number = availableParallelism()): number {
+  return Math.max(4, Math.floor(parallelism) * 2);
+}
+
 const montyContext = functionUtils.memoize(async (): Promise<MontyContext> => {
   const errors: Error[] = [];
   const targets = configUtils.boolean(undefined, "MONTY_FORCE_WASM")
@@ -47,12 +53,13 @@ const montyContext = functionUtils.memoize(async (): Promise<MontyContext> => {
     try {
       const module = await target.load();
       logger.debug(`${target.name} module available`);
+      const maxProcesses = montyMaxProcesses();
       const pool = await module.Monty.create({
         minProcesses: 1,
-        maxProcesses: 4,
+        maxProcesses,
         requestTimeout: 35,
       });
-      logger.debug(`${target.name} pool created`);
+      logger.debug(`${target.name} pool created`, { maxProcesses });
       return {
         crashedError: module.MontyCrashedError,
         pool,
@@ -82,12 +89,11 @@ export interface MontySandboxOptions {
 }
 
 /** Python-only, deny-by-default sandbox backed by Monty's selected worker pool. */
-export class MontySandbox implements WorkspaceSandbox {
+export class MontySandbox extends MastraSandbox {
   readonly id: string;
   readonly name: string;
   readonly provider = "monty";
-  status: WorkspaceSandbox["status"] = "pending";
-  error?: string;
+  status: ProviderStatus = "pending";
 
   private readonly commandTimeoutMs: number;
   private readonly maxMemoryBytes: number;
@@ -96,8 +102,10 @@ export class MontySandbox implements WorkspaceSandbox {
   private lastUsedAt?: Date;
 
   constructor(options: MontySandboxOptions = {}) {
+    const name = options.name ?? "Pydantic Monty";
+    super({ name });
     this.id = options.id ?? "monty";
-    this.name = options.name ?? "Pydantic Monty";
+    this.name = name;
     this.commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
     this.maxMemoryBytes = options.maxMemoryBytes ?? DEFAULT_MAX_MEMORY_BYTES;
     this.typeCheck = options.typeCheck ?? false;
@@ -105,33 +113,14 @@ export class MontySandbox implements WorkspaceSandbox {
 
   /** Warm the shared crash-isolated worker pool. */
   async start(): Promise<void> {
-    if (this.status === "running") return;
-    this.status = "starting";
-    this.error = undefined;
-    try {
-      await montyContext();
-      this.status = "running";
-    } catch (caught) {
-      this.status = "error";
-      this.error = errorUtils.errorMessage(caught);
-      throw caught;
-    }
+    await montyContext();
   }
 
   /** The process-wide pool stays warm; this instance carries no open session. */
-  async stop(): Promise<void> {
-    this.status = "stopped";
-  }
+  async stop(): Promise<void> {}
 
   /** The process-wide pool stays warm; each command closes its own checkout. */
-  async destroy(): Promise<void> {
-    this.status = "destroyed";
-  }
-
-  /** Monty sessions are ephemeral and do not provide persistent checkpoints. */
-  async snapshot(): Promise<void> {}
-
-  readonly supportsCheckpoints = false;
+  async destroy(): Promise<void> {}
 
   /** Execute Python source and map Monty output to Mastra's command result. */
   async executeCommand(

package/src/openapi-tool.ts

@@ -9,16 +9,7 @@ import { urlBuilder, type UrlBuilder } from "@dbx-tools/shared-core/net";
 import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
 
-const HTTP_METHODS = [
-  "GET",
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE",
-  "OPTIONS",
-  "HEAD",
-  "TRACE",
-] as const;
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE"] as const;
 
 const JsonObjectSchema = z
   .record(z.string(), z.unknown())
@@ -208,7 +199,7 @@ function operationUrl(document: OpenApiDocument, sourceUrl: URL | undefined, pat
       ? base.withPathAppend(path).toString()
       : `${server.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
   }
-  return sourceUrl ? urlBuilder(sourceUrl)?.withPathReplace(path).toString() ?? path : path;
+  return sourceUrl ? (urlBuilder(sourceUrl)?.withPathReplace(path).toString() ?? path) : path;
 }
 
 function resolveReferences(

package/src/plugin.ts

@@ -111,6 +111,7 @@ import { buildObservability, configureOtelPropagation } from "./observability.ts
 import { provisionRemoteSkills } from "./remote-skills.ts";
 import {
   attachRoutePatchMiddleware,
+  attachStaleResumeRecovery,
   createRequestContext,
   isMastraRequestAllowed,
   MastraServer,
@@ -1185,6 +1186,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       customApiRoutes: agentChatRoutes(),
     });
     await this.mastraServer.init();
+    attachStaleResumeRecovery(this.mastraApp);
     this.logger.info("ready", {
       agents: Object.keys(this.built.agents),
       defaultAgent: this.built.defaultAgentId,

package/src/remote-skills.ts

@@ -36,10 +36,9 @@
  * Pass `refreshTtlMs: 0` to download on every boot.
  *
  * The default destination is the Databricks workspace Assistant skills tree
- * (`/Workspace/.assistant/skills`, the same tree a "save this as a skill"
- * action writes to), so provisioned skills persist across restarts and are
+ * (`/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 `/Users/<email>/.assistant/skills`
+ * 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
@@ -73,8 +72,7 @@ import {
 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";
+import { ORGANIZATION_SKILLS_PATH, personalSkillsPath } from "./skill-paths.ts";
 
 const logger = log.logger("mastra/remote-skills");
 
@@ -208,7 +206,7 @@ export interface ProvisionRemoteSkillsOptions {
   failOnError?: boolean;
   /**
    * Absolute Databricks path that roots the destination Assistant skills tree.
-   * Defaults to the OBO user's `/Users/<email>/.assistant/skills`.
+   * Defaults to the OBO user's `/Workspace/Users/<email>/.assistant/skills`.
    */
   databricksBasePath?: string;
   /** Auth-scoped Databricks client. Defaults to the AppKit execution context. */
@@ -442,7 +440,6 @@ 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];
@@ -491,7 +488,6 @@ export async function provisionRemoteSkills(
           // 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));
         }
@@ -520,12 +516,6 @@ export async function provisionRemoteSkills(
     }
   }
 
-  if (workspaceUpdated && client?.config?.getHost) {
-    await clearWorkspaceSkillCache({
-      host: (await client.config.getHost()).toString(),
-    });
-  }
-
   return { localSkillPaths, databricksBasePath, skillNames };
 }
 
@@ -603,7 +593,7 @@ function resolveDatabricksBasePath(
   // A named user targets their personal Assistant tree (the "save a skill"
   // target); otherwise the shared workspace Assistant tree, which the built-in
   // Assistant-skills mount already scans.
-  return email ? userAssistantSkillsPath(email) : ASSISTANT_SHARED_SKILLS_PATH;
+  return email ? personalSkillsPath(email) : ORGANIZATION_SKILLS_PATH;
 }
 
 /**

package/src/server.ts

@@ -6,8 +6,9 @@
  */
 
 import { getExecutionContext } from "@databricks/appkit";
-import { hash, http, log, object, stringUtils, token } from "@dbx-tools/shared-core";
+import { errorUtils, hash, http, log, object, stringUtils, token } from "@dbx-tools/shared-core";
 import { feedback, thread } from "@dbx-tools/shared-mastra";
+import { isStaleMastraResumeError } from "@dbx-tools/shared-mastra/resume";
 import {
   MASTRA_RESOURCE_ID_KEY,
   MASTRA_THREAD_ID_KEY,
@@ -42,6 +43,7 @@ import { recordActiveTraceAuth, recordActiveTraceUser } from "./telemetry.ts";
  * when no SDK is registered, which must never be surfaced as a trace to
  * attach feedback to.
  */
+const logger = log.logger("mastra/server");
 const INVALID_TRACE_ID = "0".repeat(32);
 const TRUSTED_REQUEST_CONTEXT_KEYS = [
   MASTRA_RESOURCE_ID_KEY,
@@ -460,3 +462,35 @@ export function attachRoutePatchMiddleware(app: express.Express): void {
     next();
   });
 }
+
+/**
+ * Finish a chat request when Mastra throws because the workflow is no
+ * longer suspended. Duplicate approve/resume and late `consumeStream`
+ * both hit that path; the client already has (or will reload) the
+ * completed turn.
+ */
+export function attachStaleResumeRecovery(app: express.Express): void {
+  app.use(
+    (error: unknown, req: express.Request, res: express.Response, next: express.NextFunction) => {
+      if (!isStaleMastraResumeError(error)) {
+        next(error);
+        return;
+      }
+      logger.warn("ignored stale mastra resume", {
+        path: req.path,
+        error: errorUtils.errorMessage(error),
+      });
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      res.status(200);
+      res.setHeader("content-type", "text/event-stream; charset=utf-8");
+      res.setHeader("cache-control", "no-cache");
+      res.write(`data: ${JSON.stringify({ type: "start" })}\n\n`);
+      res.write(`data: ${JSON.stringify({ type: "finish" })}\n\n`);
+      res.write("data: [DONE]\n\n");
+      res.end();
+    },
+  );
+}