@dbx-tools/appkit-mastra 0.6.15 → 0.6.36

package/src/genie.ts

@@ -48,14 +48,14 @@ import { plugin } from "@dbx-tools/appkit";
 import { chat, space as genieSpace } from "@dbx-tools/genie";
 import { error, log, string } from "@dbx-tools/shared-core";
 import { genieModel, type GenieMessage } from "@dbx-tools/shared-genie";
-import { wire, type MastraWriter, type StartedEvent } from "@dbx-tools/shared-mastra";
+import type { MastraWriter, 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 } from "@mastra/core/tools";
 import { z } from "zod";
 
 import type { MastraTools } from "./agents.ts";
-import { chartPlannerRequestSchema, prepareChart } from "./chart.ts";
+import { chartPlannerRequestSchema, chartToolOutputSchema, prepareChart } from "./chart.ts";
 import { MASTRA_USER_KEY, resolveUserKey } from "./config.ts";
 import type { MastraPluginConfig, User } from "./config.ts";
 import { fetchStatementData } from "./statement.ts";
@@ -687,9 +687,9 @@ function buildGetStatementTool() {
  * {@link prepareChart} that resolves the dataset by fetching the
  * Genie statement's rows on demand. The tool mints a `chartId`
  * synchronously, caches an empty placeholder, and kicks off the
- * planner in the background so the agent loop never blocks. The
- * host UI resolves `[chart:<chartId>]` markers by reading the
- * cached {@link Chart} entry (1h TTL).
+ * planner in the background so the agent loop never blocks. The result carries
+ * the complete marker to copy; the host UI resolves it by reading the cached
+ * {@link Chart} entry (1h TTL).
  *
  * Space-agnostic: a Genie `statement_id` is workspace-scoped, so
  * one shared `prepare_chart` tool covers every wired Genie space.
@@ -709,20 +709,21 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
     description: string.toDescription([
       `
         Queue a chart for the rows of a Genie statement. Mints a
-        short \`chartId\` synchronously and kicks off a BACKGROUND
+        \`chartId\` plus its complete \`marker\` synchronously and
+        kicks off a BACKGROUND
         task that fetches the statement's rows, runs the
         chart-planner to pick a chart type and Echarts spec, and
         caches the result under the \`chartId\` for one hour. The
         host UI fetches the cached chart on its own once it lands.
       `,
       `
-        To display the chart in your reply, embed
-        \`[chart:<chartId>]\` on its own line at the position you
-        want it to appear, using the EXACT \`chartId\` string this
-        call returned. Never construct a chart id yourself (it is
-        not the \`statement_id\` or any variation of it) - only a
-        value returned by this tool resolves to a real chart. The
-        tool returns immediately - do NOT wait or call it again to
+        To display the chart in your reply, copy the returned
+        \`marker\` VERBATIM onto its own line at the position you
+        want it to appear. Never construct, alter, or invent a
+        marker from \`chartId\` (and never use the \`statement_id\`
+        or any variation of it) - only the complete value returned
+        by this tool resolves to a real chart. The tool returns
+        immediately - do NOT wait or call it again to
         "check progress"; the chart resolves asynchronously on the
         host UI's side.
       `,
@@ -734,7 +735,7 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
       `,
     ]),
     inputSchema: prepareChartRequestSchema,
-    outputSchema: wire.ChartSchema.pick({ chartId: true }),
+    outputSchema: chartToolOutputSchema,
     execute: async (request, ctxRaw) => {
       const ctx = ctxRaw as ToolExecuteCtx;
       const { client, requestContext } = requireClient(ctx, toolId);
@@ -835,20 +836,20 @@ export const GENIE_INSTRUCTIONS = string.toDescription([
             `,
             `
               \`[chart:<chartId>]\` - render the rows as a chart. To
-              get a \`<chartId>\`, call \`prepare_chart\` with the
+              get one, call \`prepare_chart\` with the
               statement's id (and an optional \`title\` / one-line
               \`description\` of the insight to surface). The tool
-              returns the \`chartId\` synchronously and prepares the
-              chart spec in the background; embed the returned id as
-              \`[chart:<chartId>]\` on its own line wherever the
-              chart should appear. Use a chart when the data has a
+              returns the complete \`marker\` synchronously and
+              prepares the chart spec in the background; copy that
+              marker VERBATIM onto its own line wherever the chart
+              should appear. Use a chart when the data has a
               story a visual conveys better than a table (trends,
               rankings, distributions, parts-of-a-whole).
 
-              NEVER invent or hand-build a \`<chartId>\`. A valid
-              \`<chartId>\` is the opaque token a \`prepare_chart\`
-              call returned to you in THIS turn - nothing else. It
-              is NOT a \`statement_id\`, and it is NOT a
+              NEVER invent or hand-build a marker. A valid marker is
+              the complete opaque string a \`prepare_chart\` call
+              returned to you in THIS turn - nothing else. Its id is
+              NOT a \`statement_id\`, and it is NOT a
               \`statement_id\` prefix with a label appended (e.g.
               \`01f1...-region-fill\`). If you have not called
               \`prepare_chart\` and received an id back, do not write

package/src/plugin.ts

@@ -103,10 +103,10 @@ import {
   isMastraRequestAllowed,
   MastraServer,
 } from "./server.ts";
-import { attachChatTurnTraceIo } from "./trace-io.ts";
 import { resolveServingConfig } from "./serving.ts";
 import { fetchStatementData, STATEMENT_ROW_CAP } from "./statement.ts";
 import { threadsRoute } from "./threads.ts";
+import { attachChatTurnTraceIo } from "./trace-io.ts";
 import { invalidFields } from "./validation.ts";
 
 const GENIE_MANIFEST = plugin.data(genie).plugin.manifest;
@@ -595,10 +595,24 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         const id = string.firstNonEmpty(req.params.id);
         const resolve = embedResolvers[type];
         if (!resolve) {
+          this.logger.warn("embed:unsupported", {
+            status: 404,
+            type,
+            id,
+            method: req.method,
+            path: req.path,
+          });
           res.status(404).json({ error: `unsupported embed type: ${type}` });
           return;
         }
         if (!id) {
+          this.logger.warn("embed:invalid", {
+            status: 400,
+            type,
+            method: req.method,
+            path: req.path,
+            error: "id is required",
+          });
           res.status(400).json({ error: "id is required" });
           return;
         }
@@ -616,6 +630,18 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
           return;
         }
         if (result.data === undefined) {
+          // A cache miss is security-deliberately ambiguous: unknown, expired,
+          // or owned by another identity all map to the same 404. Log the
+          // opaque id and those possible causes so a fabricated marker is
+          // diagnosable from the server without disclosing which cause applied.
+          this.logger.warn(`embed:${type}:not-found`, {
+            status: 404,
+            type,
+            id,
+            method: req.method,
+            path: req.path,
+            reason: "unknown, expired, or owned by another identity",
+          });
           res.status(404).json({ error: `${type} not found` });
           return;
         }
@@ -1005,7 +1031,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // every default-workspace agent via `extraSkillPaths`.
     const provisioned = await provisionRemoteSkills(this.config.remoteSkills);
     if (provisioned.skillNames.length > 0) {
-      this.logger.info("remote skills provisioned", {
+      this.logger.info("remote skills configured", {
         skills: provisioned.skillNames,
         databricksBasePath: provisioned.databricksBasePath,
         localSkillPaths: provisioned.localSkillPaths.length,

package/src/remote-skills.ts

@@ -61,15 +61,9 @@ import { error, hash, json, log, net, object, string } from "@dbx-tools/shared-c
 import type { OneOrMany } from "@dbx-tools/shared-core";
 import type { FileSystem } from "@dbx-tools/shared-fs";
 
-const logger = log.logger("mastra/remote-skills");
-
-/** Shared Assistant skills tree in the Databricks workspace (default target). */
-const ASSISTANT_SHARED_SKILLS_PATH = "/Workspace/.assistant/skills";
+import { ASSISTANT_SHARED_SKILLS_PATH, userAssistantSkillsPath } from "./skill-paths.ts";
 
-/** Assistant skills directory for a specific Databricks user. */
-function userAssistantSkillsPath(userEmail: string): string {
-  return `/Users/${userEmail.trim()}/.assistant/skills`;
-}
+const logger = log.logger("mastra/remote-skills");
 
 /**
  * Agent id the `skills` CLI installs a bare `SKILL.md` tree under.
@@ -452,14 +446,19 @@ export async function provisionRemoteSkills(
         if (cached && isFresh(cached, resolveRefreshTtl(sourceOptions, options))) {
           skillNames.push(...cached.skills);
           if (!destination) localSkillPaths.push(cacheFS.root);
-          logger.debug("source:cached", {
+          logger.info("remote skill ready", {
             source: sourceOptions.source,
+            destination: databricksBasePath ?? cacheFS.root,
             downloadedAt: cached.downloadedAt,
             skills: cached.skills,
+            cached: true,
           });
           continue;
         }
 
+        logger.info("installing remote skill", {
+          source: sourceOptions.source,
+        });
         staging ??= await initializedScratch("mastra-remote-skills");
         const stagedDir = await stageSource(sourceOptions, staging.root, options);
         const staged = await collectSkillDirs(stagedDir);
@@ -482,9 +481,9 @@ export async function provisionRemoteSkills(
           localSkillPaths.push(await persistLocally(key, staged, record));
         }
         skillNames.push(...record.skills);
-        logger.debug("source:provisioned", {
+        logger.info("remote skill installed", {
           source: sourceOptions.source,
-          destination: databricksBasePath ?? "local-temp",
+          destination: databricksBasePath ?? localSkillPaths.at(-1),
           skills: record.skills,
         });
       } catch (err) {

package/src/skill-paths.ts

@@ -0,0 +1,19 @@
+/**
+ * Where Databricks Assistant `SKILL.md` trees live.
+ *
+ * Two modules need these paths and must agree on them: `workspaces.ts` MOUNTS
+ * them per request (see `DEFAULT_SKILL_FOLDERS`), and `remote-skills.ts`
+ * WRITES provisioned skills into them at startup. They were previously spelled
+ * out in both, so a change to one silently provisioned skills into a tree the
+ * other never scanned.
+ *
+ * @module
+ */
+
+/** Shared Assistant skills tree, readable by everyone in the workspace. */
+export const ASSISTANT_SHARED_SKILLS_PATH = "/Workspace/.assistant/skills";
+
+/** Assistant skills tree owned by one user (the "save this as a skill" target). */
+export function userAssistantSkillsPath(userEmail: string): string {
+  return `/Users/${userEmail.trim()}/.assistant/skills`;
+}

package/src/workspaces.ts

@@ -2,10 +2,14 @@
  * Mastra workspace factory for Databricks Apps.
  *
  * Builds a per-request {@link Workspace} whose filesystem is a
- * {@link CompositeFilesystem} over Databricks paths resolved from the
- * OBO client on {@link MASTRA_USER_KEY}. Optional mount resolver
- * contributions merge extra filesystems and skill scan roots; built-in
- * Assistant skill trees are toggled with `assistantSkills` (on by default).
+ * {@link CompositeFilesystem} over the NAMED skill folders resolved for that
+ * request. A skill folder maps a name to a location plus its readable /
+ * writable policy: a Databricks path mounted through the OBO client on
+ * {@link MASTRA_USER_KEY}, or any {@link WorkspaceFilesystem} a consuming
+ * library already owns. {@link DEFAULT_SKILL_FOLDERS} supplies the Assistant
+ * trees, and `skillFolders` merges over it - same name overrides, `false`
+ * disables, a new name adds. Optional mount resolvers contribute further
+ * filesystems and skill scan roots on top.
  *
  * Databricks mounts use `@dbx-tools/databricks` {@link DatabricksFileSystem}
  * wrapped by {@link filesystems}; missing roots fall back to
@@ -16,7 +20,7 @@
 
 import type { WorkspaceClient } from "@databricks/sdk-experimental";
 import { DatabricksFileSystem } from "@dbx-tools/databricks";
-import { log, string, token } from "@dbx-tools/shared-core";
+import { error, log, string, token } from "@dbx-tools/shared-core";
 import type { RequestContext } from "@mastra/core/request-context";
 import {
   CompositeFilesystem,
@@ -28,18 +32,10 @@ import {
 
 import { MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, type User } from "./config.ts";
 import { scratchFilesystem, filesystems } from "./filesystems.ts";
+import { ASSISTANT_SHARED_SKILLS_PATH, userAssistantSkillsPath } from "./skill-paths.ts";
 
 /* ------------------------------ constants ------------------------------ */
 
-/** Shared Assistant skills tree in the workspace namespace. */
-const ASSISTANT_SHARED_SKILLS_PATH = "/Workspace/.assistant/skills";
-
-/** Composite mount for {@link ASSISTANT_SHARED_SKILLS_PATH}. */
-const ASSISTANT_WORKSPACE_SKILLS_MOUNT = "/workspace_skills";
-
-/** Composite mount for the caller's `/.assistant/skills` tree. */
-const ASSISTANT_USER_SKILLS_MOUNT = "/workspace_user_skills";
-
 /** OAuth scopes that gate Databricks workspace file mounts. */
 const WORKSPACE_FILE_SCOPES = ["workspace", "workspace.workspace", "all-apis"] as const;
 
@@ -47,23 +43,60 @@ const logger = log.logger("mastra/workspaces");
 
 /* -------------------------------- types -------------------------------- */
 
-/** Per-request context for mount resolvers. */
-interface WorkspaceMountContext {
+/** Per-request context for mount and skill-folder resolvers. */
+export interface WorkspaceMountContext {
   requestContext?: RequestContext;
 }
 
+/**
+ * A skill-folder field given either directly or as a per-request resolver.
+ * A resolver returning `undefined` skips the folder for that request.
+ */
+export type SkillFolderValue<T> =
+  T | ((context: WorkspaceMountContext) => T | undefined | Promise<T | undefined>);
+
+/**
+ * One named skill-folder location and its read / write policy.
+ *
+ * Give {@link path} for a Databricks workspace tree (mounted through the
+ * request's OBO client), or {@link filesystem} for a mount the consumer builds
+ * itself. {@link filesystem} wins when both are set.
+ */
+export interface SkillFolderOptions {
+  /** Absolute Databricks workspace path for this folder. */
+  path?: SkillFolderValue<string>;
+  /** Ready-made mount, for locations the OBO client cannot reach. */
+  filesystem?: SkillFolderValue<WorkspaceFilesystem>;
+  /**
+   * Scan this mount for `SKILL.md` files. Defaults to `true`; `false` mounts
+   * the location for file tools without adding it to skill discovery.
+   */
+  readable?: boolean;
+  /**
+   * Allow writes to a {@link path} mount (and create the root when missing).
+   * Defaults to `false`. A supplied {@link filesystem} carries its own
+   * read-only flag instead.
+   */
+  writable?: boolean;
+  /** Mount point in the composite namespace. Defaults to `/<name>`. */
+  mount?: string;
+}
+
 /** Mount map plus optional Mastra skill scan roots for one resolver. */
-interface WorkspaceMountContribution {
+export interface WorkspaceMountContribution {
   mounts: Record<string, WorkspaceFilesystem>;
   /** Paths within the composite namespace where `SKILL.md` files are scanned. */
   skillPaths?: string[];
 }
 
 /** Contributes filesystem mounts (and optional skill paths) for one request. */
-type WorkspaceMountResolver = (
+export type WorkspaceMountResolver = (
   context: WorkspaceMountContext,
 ) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
 
+/** Names carried by {@link DEFAULT_SKILL_FOLDERS}. */
+export type DefaultSkillFolderName = "workspace-team" | "workspace-team-app";
+
 /** Options for {@link createWorkspace}. */
 export interface CreateWorkspaceOptions {
   /** Workspace id; derived from `name` or `"workspace"` when omitted. */
@@ -71,11 +104,17 @@ export interface CreateWorkspaceOptions {
   /** Display name; derived from `id` when omitted. */
   name?: string;
   /**
-   * Mount read-only Assistant skill trees from `/Workspace/.assistant/skills`
-   * and `/Users/<email>/.assistant/skills`. Defaults to `true`.
+   * Start from {@link DEFAULT_SKILL_FOLDERS}. Defaults to `true`; `false`
+   * starts from an empty map, leaving only the {@link skillFolders} given here.
    */
   assistantSkills?: boolean;
-  /** Extra per-request mount resolvers (run after built-in options). */
+  /**
+   * Named skill folders merged over {@link DEFAULT_SKILL_FOLDERS}: a matching
+   * name overrides that default, `false` disables it, and any other name adds
+   * a folder.
+   */
+  skillFolders?: Record<string, SkillFolderOptions | false>;
+  /** Extra per-request mount resolvers (run after the skill-folder mounts). */
   mounts?: WorkspaceMountResolver[];
   /** Replace the auto-built dynamic skills resolver. */
   skills?: SkillsResolver;
@@ -93,18 +132,56 @@ export interface CreateWorkspaceOptions {
   extraSkillPaths?: string[];
 }
 
+/* ------------------------------- defaults ------------------------------- */
+
+/**
+ * The skill folders every workspace starts with.
+ *
+ * - `workspace-team` - the shared workspace Assistant tree, read-only because
+ *   writing it is a workspace-admin action.
+ * - `workspace-team-app` - the requesting user's own Assistant tree, writable
+ *   so the app can save skills back to it. Skipped when the request carries no
+ *   user email.
+ */
+export const DEFAULT_SKILL_FOLDERS: Readonly<Record<DefaultSkillFolderName, SkillFolderOptions>> = {
+  "workspace-team": {
+    path: ASSISTANT_SHARED_SKILLS_PATH,
+    readable: true,
+    writable: false,
+  },
+  "workspace-team-app": {
+    path: ({ requestContext }) => {
+      const email = resolveScopedEmail(requestContext);
+      return email ? userAssistantSkillsPath(email) : undefined;
+    },
+    readable: true,
+    writable: true,
+  },
+};
+
 /**
  * Create a Mastra {@link Workspace} with per-request Databricks mounts.
  *
- * @example Assistant skills only (default for agents in this plugin)
+ * @example Default skill folders only
  * ```ts
  * createWorkspace()
  * ```
  *
- * @example Assistant skills plus a custom mount resolver
+ * @example Override a default, drop another, and add a location of your own
+ * ```ts
+ * createWorkspace({
+ *   skillFolders: {
+ *     "workspace-team": { path: "/Workspace/Shared/team-skills" },
+ *     "workspace-team-app": false,
+ *     runbooks: { path: "/Workspace/Shared/runbooks/skills", writable: true },
+ *     volume: { filesystem: myVolumeFilesystem },
+ *   },
+ * })
+ * ```
+ *
+ * @example Skill folders plus a custom mount resolver
  * ```ts
  * createWorkspace({
- *   assistantSkills: true,
  *   mounts: [
  *     async ({ requestContext }) => ({
  *       mounts: { "/data": myFilesystem },
@@ -116,20 +193,22 @@ export interface CreateWorkspaceOptions {
  */
 export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace {
   const { id, name } = resolveWorkspaceIdentity(options);
-  const resolvers = buildMountResolvers(options);
+  const skillFolders = resolveSkillFolders(options);
+  const folderNames = Object.keys(skillFolders);
+  const resolvers = buildMountResolvers(skillFolders, options.mounts);
   const extraSkillPaths = options.extraSkillPaths ?? [];
   const skills =
     options.skills ??
     (resolvers.length > 0 || extraSkillPaths.length > 0
       ? buildWorkspaceSkillsResolver(resolvers, extraSkillPaths)
       : undefined);
-  const checkSkillFileMtime = options.checkSkillFileMtime ?? options.assistantSkills !== false;
+  const checkSkillFileMtime = options.checkSkillFileMtime ?? folderNames.length > 0;
   const bm25 = options.bm25 !== false;
   logger.debug("workspace:create", {
     id,
     name,
     resolverCount: resolvers.length,
-    assistantSkills: options.assistantSkills !== false,
+    skillFolders: folderNames,
     customMountResolvers: options.mounts?.length ?? 0,
     customSkillsResolver: Boolean(options.skills),
     checkSkillFileMtime,
@@ -151,16 +230,29 @@ export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace
   });
 }
 
-/* ---------------------------- private helpers ---------------------------- */
-
 /**
- * Map an OBO user email to their Assistant skills directory in the
- * workspace namespace.
+ * Merge the configured skill folders over {@link DEFAULT_SKILL_FOLDERS}.
+ *
+ * `assistantSkills: false` drops the defaults, and a `false` value removes one
+ * entry by name.
  */
-function userAssistantSkillsPath(userEmail: string): string {
-  return `/Users/${userEmail.trim()}/.assistant/skills`;
+export function resolveSkillFolders(
+  options: Pick<CreateWorkspaceOptions, "assistantSkills" | "skillFolders"> = {},
+): Record<string, SkillFolderOptions> {
+  const merged: Record<string, SkillFolderOptions> =
+    options.assistantSkills === false ? {} : { ...DEFAULT_SKILL_FOLDERS };
+  for (const [name, folder] of Object.entries(options.skillFolders ?? {})) {
+    if (folder === false) {
+      delete merged[name];
+    } else {
+      merged[name] = folder;
+    }
+  }
+  return merged;
 }
 
+/* ---------------------------- private helpers ---------------------------- */
+
 /**
  * Return whether the request token carries a scope that allows workspace
  * file API access (`workspace` or `all-apis` on {@link MASTRA_SCOPES_KEY}).
@@ -173,61 +265,81 @@ function hasWorkspaceFileScope(requestContext: RequestContext | undefined): bool
 }
 
 /**
- * Built-in mount resolver for Assistant `SKILL.md` trees.
+ * Mount resolver for the named skill folders.
  *
- * Mounts {@link ASSISTANT_SHARED_SKILLS_PATH} when scope checks pass and
- * `/Users/<email>/.assistant/skills` when {@link MASTRA_USER_EMAIL_KEY} is
- * set. Returns empty mounts when the OBO user or client is missing.
- * Mastra owns filesystem initialization.
+ * Gates on workspace file scope (or development mode), then mounts every
+ * folder whose location resolves for this request.
  */
-async function resolveAssistantSkillsMounts(
+async function resolveSkillFolderMounts(
+  skillFolders: Record<string, SkillFolderOptions>,
   context: WorkspaceMountContext,
 ): Promise<WorkspaceMountContribution> {
   const mounts: Record<string, WorkspaceFilesystem> = {};
+  const skillPaths: string[] = [];
   const requestContext = context.requestContext;
 
-  if (!shouldMountAssistantSkills(requestContext)) {
-    logger.debug("assistant-skills:skipped", {
+  if (!requestContext || !shouldMountSkillFolders(requestContext)) {
+    logger.debug("skill-folders:skipped", {
       reason: !requestContext ? "no-request-context" : "missing-workspace-scope",
       nodeEnv: process.env.NODE_ENV,
-      scopes: context.requestContext?.get(MASTRA_SCOPES_KEY),
+      scopes: requestContext?.get(MASTRA_SCOPES_KEY),
     });
-    return { mounts, skillPaths: [] };
+    return { mounts, skillPaths };
   }
 
-  const user = requestContext!.get(MASTRA_USER_KEY) as User | undefined;
+  const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
   const client = user?.executionContext.client as WorkspaceClient | undefined;
-  if (!client) {
-    logger.debug("assistant-skills:skipped", {
-      reason: "missing-obo-client",
-      userId: user?.id,
-    });
-    return { mounts, skillPaths: [] };
-  }
-
-  mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = await databricksFilesystem(
-    client,
-    ASSISTANT_SHARED_SKILLS_PATH,
-  );
 
-  const email = resolveScopedEmail(requestContext);
-  if (email) {
-    mounts[ASSISTANT_USER_SKILLS_MOUNT] = await databricksFilesystem(
-      client,
-      userAssistantSkillsPath(email),
-      false,
-    );
+  for (const [name, folder] of Object.entries(skillFolders)) {
+    const filesystem = await resolveSkillFolderFilesystem(name, folder, context, client);
+    if (!filesystem) continue;
+    const mount = folder.mount ?? `/${name}`;
+    mounts[mount] = filesystem;
+    if (folder.readable !== false) skillPaths.push(mount);
   }
 
-  logger.debug("assistant-skills:mounted", {
-    sharedPath: ASSISTANT_SHARED_SKILLS_PATH,
-    sharedMount: ASSISTANT_WORKSPACE_SKILLS_MOUNT,
-    userMount: email ? ASSISTANT_USER_SKILLS_MOUNT : undefined,
-    userPath: email ? userAssistantSkillsPath(email) : undefined,
+  logger.debug("skill-folders:mounted", {
     mountKeys: Object.keys(mounts),
+    skillPaths,
   });
 
-  return { mounts, skillPaths: Object.keys(mounts) };
+  return { mounts, skillPaths };
+}
+
+/**
+ * Resolve one skill folder to a Mastra filesystem, or `undefined` to skip it
+ * for this request.
+ */
+async function resolveSkillFolderFilesystem(
+  name: string,
+  folder: SkillFolderOptions,
+  context: WorkspaceMountContext,
+  client: WorkspaceClient | undefined,
+): Promise<WorkspaceFilesystem | undefined> {
+  if (folder.filesystem !== undefined) {
+    return resolveSkillFolderValue(folder.filesystem, context);
+  }
+  // A path mount needs the request's OBO client to reach the workspace.
+  if (folder.path === undefined || !client) {
+    logger.debug("skill-folder:skipped", {
+      name,
+      reason: folder.path === undefined ? "no-location" : "missing-obo-client",
+    });
+    return undefined;
+  }
+  const root = string.trimToNull(await resolveSkillFolderValue(folder.path, context));
+  if (!root) return undefined;
+  return databricksFilesystem(client, root, folder.writable !== true);
+}
+
+/** Read a {@link SkillFolderValue}, calling it when it is a per-request resolver. */
+function resolveSkillFolderValue<T>(
+  value: SkillFolderValue<T>,
+  context: WorkspaceMountContext,
+): T | undefined | Promise<T | undefined> {
+  return typeof value === "function"
+    ? (value as (context: WorkspaceMountContext) => T | undefined | Promise<T | undefined>)(context)
+    : value;
 }
 
 /**
@@ -249,19 +361,21 @@ function resolveWorkspaceIdentity(options: CreateWorkspaceOptions): {
   return { id, name };
 }
 
-/** Collect built-in and caller-supplied mount resolvers for one workspace. */
-function buildMountResolvers(options: CreateWorkspaceOptions): WorkspaceMountResolver[] {
+/** Collect the skill-folder resolver and any caller-supplied ones. */
+function buildMountResolvers(
+  skillFolders: Record<string, SkillFolderOptions>,
+  mounts: WorkspaceMountResolver[] | undefined,
+): WorkspaceMountResolver[] {
   const resolvers: WorkspaceMountResolver[] = [];
-  const { assistantSkills = true, mounts } = options;
-  if (assistantSkills) {
-    resolvers.push(resolveAssistantSkillsMounts);
+  const folderCount = Object.keys(skillFolders).length;
+  if (folderCount > 0) {
+    resolvers.push((context) => resolveSkillFolderMounts(skillFolders, context));
   }
   if (mounts?.length) {
     resolvers.push(...mounts);
   }
   logger.debug("mounts:resolvers", {
-    assistantSkills,
-    builtInResolver: assistantSkills,
+    skillFolderCount: folderCount,
     customResolverCount: mounts?.length ?? 0,
     totalResolverCount: resolvers.length,
   });
@@ -269,23 +383,19 @@ function buildMountResolvers(options: CreateWorkspaceOptions): WorkspaceMountRes
 }
 
 /**
- * Gate Assistant skill mounts on request context.
+ * Gate skill-folder mounts on the request's token.
  *
  * Always allows mounts in development; in other environments requires
  * {@link hasWorkspaceFileScope}.
  */
-function shouldMountAssistantSkills(
-  requestContext: RequestContext | undefined,
-): requestContext is RequestContext {
-  if (!requestContext) return false;
+function shouldMountSkillFolders(requestContext: RequestContext): boolean {
   if (process.env.NODE_ENV === "development") return true;
   return hasWorkspaceFileScope(requestContext);
 }
 
 /** Read the trimmed OBO user email stamped on {@link MASTRA_USER_EMAIL_KEY}. */
 function resolveScopedEmail(requestContext: RequestContext | undefined): string | undefined {
-  const email = requestContext?.get(MASTRA_USER_EMAIL_KEY) as string | undefined;
-  return email?.trim() || undefined;
+  return string.trimToNull(requestContext?.get(MASTRA_USER_EMAIL_KEY)) ?? undefined;
 }
 
 /**
@@ -313,7 +423,7 @@ async function databricksFilesystem(
     logger.debug("databricks-mount:scratch-fallback", {
       root,
       readOnly,
-      error: err instanceof Error ? err.message : String(err),
+      error: error.errorMessage(err),
     });
   }
   return scratchFilesystem();