@dbx-tools/appkit-mastra 0.9.95 → 0.9.99

package/lib/src/skill-paths.js

@@ -2,7 +2,7 @@
  * 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`
+ * them per request (see `DEFAULT_DATABRICKS_WORKSPACE_PATHS`), and `remote-skills.ts`
  * WRITES provisioned skills into them at startup. They live here rather than being
  * spelled out in both, where a change to one would silently provision skills into a
  * tree the other never scanned.
@@ -21,4 +21,4 @@ export function personalWorkspacePath(userEmail) {
 export function personalSkillsPath(userEmail) {
     return `${personalWorkspacePath(userEmail)}/.assistant/skills`;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2tpbGwtcGF0aHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2tpbGwtcGF0aHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7R0FVRztBQUVILHlFQUF5RTtBQUN6RSxNQUFNLENBQUMsTUFBTSwyQkFBMkIsR0FBRyx1QkFBdUIsQ0FBQztBQUVuRSx1RUFBdUU7QUFDdkUsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsR0FBRywyQkFBMkIsU0FBUyxDQUFDO0FBRWhGLHdDQUF3QztBQUN4QyxNQUFNLFVBQVUscUJBQXFCLENBQUMsU0FBaUI7SUFDckQsT0FBTyxvQkFBb0IsU0FBUyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUM7QUFDaEQsQ0FBQztBQUVELDhDQUE4QztBQUM5QyxNQUFNLFVBQVUsa0JBQWtCLENBQUMsU0FBaUI7SUFDbEQsT0FBTyxHQUFHLHFCQUFxQixDQUFDLFNBQVMsQ0FBQyxvQkFBb0IsQ0FBQztBQUNqRSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBXaGVyZSBEYXRhYnJpY2tzIEFzc2lzdGFudCBgU0tJTEwubWRgIHRyZWVzIGxpdmUuXG4gKlxuICogVHdvIG1vZHVsZXMgbmVlZCB0aGVzZSBwYXRocyBhbmQgbXVzdCBhZ3JlZSBvbiB0aGVtOiBgd29ya3NwYWNlcy50c2AgTU9VTlRTXG4gKiB0aGVtIHBlciByZXF1ZXN0IChzZWUgYERFRkFVTFRfU0tJTExfRk9MREVSU2ApLCBhbmQgYHJlbW90ZS1za2lsbHMudHNgXG4gKiBXUklURVMgcHJvdmlzaW9uZWQgc2tpbGxzIGludG8gdGhlbSBhdCBzdGFydHVwLiBUaGV5IGxpdmUgaGVyZSByYXRoZXIgdGhhbiBiZWluZ1xuICogc3BlbGxlZCBvdXQgaW4gYm90aCwgd2hlcmUgYSBjaGFuZ2UgdG8gb25lIHdvdWxkIHNpbGVudGx5IHByb3Zpc2lvbiBza2lsbHMgaW50byBhXG4gKiB0cmVlIHRoZSBvdGhlciBuZXZlciBzY2FubmVkLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG4vKiogT3JnYW5pemF0aW9uIEFzc2lzdGFudCByb290LCBtb3VudGVkIGF0IGl0cyBhY3R1YWwgd29ya3NwYWNlIHBhdGguICovXG5leHBvcnQgY29uc3QgT1JHQU5JWkFUSU9OX0FTU0lTVEFOVF9QQVRIID0gXCIvV29ya3NwYWNlLy5hc3Npc3RhbnRcIjtcblxuLyoqIE9yZ2FuaXphdGlvbiBza2lsbHMgdHJlZSwgcmVhZGFibGUgYnkgZXZlcnlvbmUgaW4gdGhlIHdvcmtzcGFjZS4gKi9cbmV4cG9ydCBjb25zdCBPUkdBTklaQVRJT05fU0tJTExTX1BBVEggPSBgJHtPUkdBTklaQVRJT05fQVNTSVNUQU5UX1BBVEh9L3NraWxsc2A7XG5cbi8qKiBXb3Jrc3BhY2UgaG9tZSByb290IGZvciBvbmUgdXNlci4gKi9cbmV4cG9ydCBmdW5jdGlvbiBwZXJzb25hbFdvcmtzcGFjZVBhdGgodXNlckVtYWlsOiBzdHJpbmcpOiBzdHJpbmcge1xuICByZXR1cm4gYC9Xb3Jrc3BhY2UvVXNlcnMvJHt1c2VyRW1haWwudHJpbSgpfWA7XG59XG5cbi8qKiBQZXJzb25hbCBza2lsbHMgdHJlZSBvd25lZCBieSBvbmUgdXNlci4gKi9cbmV4cG9ydCBmdW5jdGlvbiBwZXJzb25hbFNraWxsc1BhdGgodXNlckVtYWlsOiBzdHJpbmcpOiBzdHJpbmcge1xuICByZXR1cm4gYCR7cGVyc29uYWxXb3Jrc3BhY2VQYXRoKHVzZXJFbWFpbCl9Ly5hc3Npc3RhbnQvc2tpbGxzYDtcbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2tpbGwtcGF0aHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2tpbGwtcGF0aHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7R0FVRztBQUVILHlFQUF5RTtBQUN6RSxNQUFNLENBQUMsTUFBTSwyQkFBMkIsR0FBRyx1QkFBdUIsQ0FBQztBQUVuRSx1RUFBdUU7QUFDdkUsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsR0FBRywyQkFBMkIsU0FBUyxDQUFDO0FBRWhGLHdDQUF3QztBQUN4QyxNQUFNLFVBQVUscUJBQXFCLENBQUMsU0FBaUI7SUFDckQsT0FBTyxvQkFBb0IsU0FBUyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUM7QUFDaEQsQ0FBQztBQUVELDhDQUE4QztBQUM5QyxNQUFNLFVBQVUsa0JBQWtCLENBQUMsU0FBaUI7SUFDbEQsT0FBTyxHQUFHLHFCQUFxQixDQUFDLFNBQVMsQ0FBQyxvQkFBb0IsQ0FBQztBQUNqRSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBXaGVyZSBEYXRhYnJpY2tzIEFzc2lzdGFudCBgU0tJTEwubWRgIHRyZWVzIGxpdmUuXG4gKlxuICogVHdvIG1vZHVsZXMgbmVlZCB0aGVzZSBwYXRocyBhbmQgbXVzdCBhZ3JlZSBvbiB0aGVtOiBgd29ya3NwYWNlcy50c2AgTU9VTlRTXG4gKiB0aGVtIHBlciByZXF1ZXN0IChzZWUgYERFRkFVTFRfREFUQUJSSUNLU19XT1JLU1BBQ0VfUEFUSFNgKSwgYW5kIGByZW1vdGUtc2tpbGxzLnRzYFxuICogV1JJVEVTIHByb3Zpc2lvbmVkIHNraWxscyBpbnRvIHRoZW0gYXQgc3RhcnR1cC4gVGhleSBsaXZlIGhlcmUgcmF0aGVyIHRoYW4gYmVpbmdcbiAqIHNwZWxsZWQgb3V0IGluIGJvdGgsIHdoZXJlIGEgY2hhbmdlIHRvIG9uZSB3b3VsZCBzaWxlbnRseSBwcm92aXNpb24gc2tpbGxzIGludG8gYVxuICogdHJlZSB0aGUgb3RoZXIgbmV2ZXIgc2Nhbm5lZC5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuLyoqIE9yZ2FuaXphdGlvbiBBc3Npc3RhbnQgcm9vdCwgbW91bnRlZCBhdCBpdHMgYWN0dWFsIHdvcmtzcGFjZSBwYXRoLiAqL1xuZXhwb3J0IGNvbnN0IE9SR0FOSVpBVElPTl9BU1NJU1RBTlRfUEFUSCA9IFwiL1dvcmtzcGFjZS8uYXNzaXN0YW50XCI7XG5cbi8qKiBPcmdhbml6YXRpb24gc2tpbGxzIHRyZWUsIHJlYWRhYmxlIGJ5IGV2ZXJ5b25lIGluIHRoZSB3b3Jrc3BhY2UuICovXG5leHBvcnQgY29uc3QgT1JHQU5JWkFUSU9OX1NLSUxMU19QQVRIID0gYCR7T1JHQU5JWkFUSU9OX0FTU0lTVEFOVF9QQVRIfS9za2lsbHNgO1xuXG4vKiogV29ya3NwYWNlIGhvbWUgcm9vdCBmb3Igb25lIHVzZXIuICovXG5leHBvcnQgZnVuY3Rpb24gcGVyc29uYWxXb3Jrc3BhY2VQYXRoKHVzZXJFbWFpbDogc3RyaW5nKTogc3RyaW5nIHtcbiAgcmV0dXJuIGAvV29ya3NwYWNlL1VzZXJzLyR7dXNlckVtYWlsLnRyaW0oKX1gO1xufVxuXG4vKiogUGVyc29uYWwgc2tpbGxzIHRyZWUgb3duZWQgYnkgb25lIHVzZXIuICovXG5leHBvcnQgZnVuY3Rpb24gcGVyc29uYWxTa2lsbHNQYXRoKHVzZXJFbWFpbDogc3RyaW5nKTogc3RyaW5nIHtcbiAgcmV0dXJuIGAke3BlcnNvbmFsV29ya3NwYWNlUGF0aCh1c2VyRW1haWwpfS8uYXNzaXN0YW50L3NraWxsc2A7XG59XG4iXX0=

package/lib/src/workspaces.d.ts

@@ -1,16 +1,10 @@
 /**
  * Mastra workspace factory for Databricks Apps.
  *
- * Builds a {@link Workspace} with Databricks Sandbox command execution, an
- * isolated `/tmp` scratch mount, and a {@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.
+ * Builds native Mastra workspace configuration from Databricks paths. Paths
+ * mount at the same path by default, `~` resolves to the current user's
+ * Databricks workspace home, and `/tmp[/subpath]` resolves to stable
+ * user-scoped storage under the host's ephemeral temp directory.
  *
  * Databricks mounts use `@dbx-tools/databricks` {@link DatabricksFileSystem}
  * wrapped by {@link filesystems}; inaccessible roots are skipped independently.
@@ -18,30 +12,21 @@
  * @module
  */
 import { pluginRegistry } from "@dbx-tools/appkit";
+import { type PathMatchInput } from "@dbx-tools/path";
+import { type CacheableFileSystemOperation } from "@dbx-tools/shared-fs";
 import type { RequestContext } from "@mastra/core/request-context";
-import { Workspace, type SkillsResolver, type WorkspaceFilesystem, type WorkspaceSandbox, type WorkspaceSandboxResolver, type WorkspaceToolsConfig } from "@mastra/core/workspace";
+import { Workspace, type SkillsResolver, type WorkspaceConfig, type WorkspaceFilesystem, type WorkspaceSandbox, type WorkspaceSandboxResolver } from "@mastra/core/workspace";
 import { type DatabricksWorkspaceSandboxOptions } from "./sandbox.ts";
 /** Per-request context for mount and skill-folder resolvers. */
-export interface WorkspaceMountContext {
+export interface DatabricksWorkspaceContext {
     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.
+ * One Databricks path mounted into a Mastra workspace.
  */
-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 root mounted at its actual path. */
-    path?: SkillFolderValue<string>;
-    /** Ready-made mount, for locations the OBO client cannot reach. */
-    filesystem?: SkillFolderValue<WorkspaceFilesystem>;
+export interface DatabricksWorkspacePathOptions {
+    /** Absolute Databricks path or `~` shortcut for the current user's workspace home. */
+    path: string;
     /** Human-friendly mount name shown in filesystem listings. */
     displayName?: string;
     /** Mount description shown in filesystem listings and workspace instructions. */
@@ -70,51 +55,44 @@ export interface SkillFolderOptions {
     /** Mount point in the composite namespace. Databricks paths default to their actual root. */
     mount?: string;
 }
-/** Mount map plus optional Mastra skill scan roots for one resolver. */
-export interface WorkspaceMountContribution {
-    mounts: Record<string, WorkspaceFilesystem>;
-    /** Paths within the composite namespace where `SKILL.md` files are scanned. */
-    skillPaths?: string[];
+/** String shorthand or full options for one Databricks workspace path. */
+export type DatabricksWorkspacePath = string | DatabricksWorkspacePathOptions;
+/** Fixed or request-dependent Databricks path entry. */
+export type DatabricksWorkspacePathValue = DatabricksWorkspacePath | false | ((context: DatabricksWorkspaceContext) => DatabricksWorkspacePath | false | undefined | Promise<DatabricksWorkspacePath | false | undefined>);
+/** Operations and path globs cached by the Databricks filesystem shortcut. */
+export interface DatabricksWorkspaceCacheFilter {
+    /** Cached filesystem operations. Omit for `exists`, `readFile`, `readdir`, and `stat`. */
+    operations?: CacheableFileSystemOperation | readonly CacheableFileSystemOperation[];
+    /** Absolute or root-relative globs and predicates. `~` expands per request. */
+    paths?: PathMatchInput | readonly PathMatchInput[];
 }
-/** Contributes filesystem mounts (and optional skill paths) for one request. */
-export type WorkspaceMountResolver = (context: WorkspaceMountContext) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
-/** Names carried by {@link DEFAULT_SKILL_FOLDERS}. */
-export type DefaultSkillFolderName = "organization-skills" | "personal-skills";
+/** Fixed or request-dependent filesystem cache selection. */
+export type DatabricksWorkspaceCache = boolean | DatabricksWorkspaceCacheFilter | readonly DatabricksWorkspaceCacheFilter[] | ((context: DatabricksWorkspaceContext) => boolean | DatabricksWorkspaceCacheFilter | readonly DatabricksWorkspaceCacheFilter[] | undefined | Promise<boolean | DatabricksWorkspaceCacheFilter | readonly DatabricksWorkspaceCacheFilter[] | undefined>);
 /**
- * Sandbox selection for {@link createWorkspace}. Databricks is the default;
+ * Sandbox selection for {@link databricksWorkspace}. Monty is the default;
  * `false` disables command execution, and a Mastra provider or resolver is an
  * explicit replacement.
  */
 export type WorkspaceSandboxSelection = false | "databricks" | "monty" | DatabricksWorkspaceSandboxOptions | WorkspaceSandbox | WorkspaceSandboxResolver;
-/** Options for {@link createWorkspace}. */
-export interface CreateWorkspaceOptions {
-    /** Workspace id; derived from `name` or `"workspace"` when omitted. */
-    id?: string;
-    /** Display name; derived from `id` when omitted. */
-    name?: string;
+/** Native Mastra workspace options plus Databricks path shortcuts. */
+export interface DatabricksWorkspaceOptions extends Omit<WorkspaceConfig, "filesystem" | "mounts" | "sandbox" | "skills"> {
     /**
-     * Start from {@link DEFAULT_SKILL_FOLDERS}. Defaults to `true`; `false`
-     * starts from an empty map, leaving only the {@link skillFolders} given here.
+     * Start from {@link DEFAULT_DATABRICKS_WORKSPACE_PATHS}. Defaults to `true`.
      */
-    assistantSkills?: boolean;
+    assistantPaths?: boolean;
     /**
-     * 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.
+     * Databricks paths appended after the defaults. A string is shorthand for
+     * `{ path }`; a resolver may return either form per request.
      */
-    skillFolders?: Record<string, SkillFolderOptions | false>;
-    /** Extra per-request mount resolvers (run after the skill-folder mounts). */
-    mounts?: WorkspaceMountResolver[];
+    paths?: readonly DatabricksWorkspacePathValue[];
+    /** Native Mastra filesystems composed beside the Databricks paths. */
+    mounts?: Record<string, WorkspaceFilesystem>;
     /** Replace the auto-built dynamic skills resolver. */
     skills?: SkillsResolver;
-    /** Forwarded to Mastra when skill discovery is enabled. */
-    checkSkillFileMtime?: boolean;
-    /** Additional native Mastra workspace tool configuration and overrides. */
-    tools?: WorkspaceToolsConfig;
+    /** Filesystem cache filters. Ignored when the AppKit files-cache plugin is absent. */
+    cache?: DatabricksWorkspaceCache;
     /** AppKit plugin context used to discover optional sibling capabilities. */
     pluginContext?: pluginRegistry.PluginContextLike;
-    /** Enable BM25 keyword search over indexed workspace content. */
-    bm25?: boolean;
     /**
      * Command sandbox. Defaults to Monty. Pass `"databricks"` or an options
      * object for Databricks Sandbox, `false` to disable command execution, or an
@@ -131,54 +109,37 @@ export interface CreateWorkspaceOptions {
     extraSkillPaths?: string[];
 }
 /**
- * The skill folders every workspace starts with.
- *
- * - `organization-skills` - `/Workspace/.assistant` with `skills`; write
- *   attempts require approval and remain subject to Databricks permissions.
- * - `personal-skills` - the requesting user's `/Workspace/Users/<email>` root
- *   with `.assistant/skills`, writable and skipped without an email.
+ * Default Databricks paths for shared and current-user Agent Skills.
  */
-export declare const DEFAULT_SKILL_FOLDERS: Readonly<Record<DefaultSkillFolderName, SkillFolderOptions>>;
+export declare const DEFAULT_DATABRICKS_WORKSPACE_PATHS: readonly DatabricksWorkspacePathOptions[];
 /**
  * Create a Mastra {@link Workspace} with per-request Databricks mounts.
  *
- * @example Default skill folders only
+ * @example Default Databricks paths
  * ```ts
- * createWorkspace()
+ * databricksWorkspace()
  * ```
  *
- * @example Override a default, drop another, and add a location of your own
+ * @example Use only explicit paths
  * ```ts
- * createWorkspace({
- *   skillFolders: {
- *     "organization-skills": {
- *       path: "/Workspace/Shared/.assistant",
- *       skills: ["skills"],
- *     },
- *     "personal-skills": false,
- *     runbooks: { path: "/Workspace/Shared/runbooks/skills", writable: true },
- *     volume: { filesystem: myVolumeFilesystem },
- *   },
+ * databricksWorkspace({
+ *   assistantPaths: false,
+ *   paths: ["~/project", "/tmp/project", "/Volumes/main/default/data"],
  * })
  * ```
  *
- * @example Skill folders plus a custom mount resolver
+ * @example Build a standard Mastra workspace yourself
  * ```ts
- * createWorkspace({
- *   mounts: [
- *     async ({ requestContext }) => ({
- *       mounts: { "/data": myFilesystem },
- *       skillPaths: [],
- *     }),
- *   ],
+ * new Workspace({
+ *   ...databricksWorkspaceConfig({ paths: ["~/project"] }),
+ *   sandbox: mySandbox,
  * })
  * ```
  */
-export declare function createWorkspace(options?: CreateWorkspaceOptions): Workspace;
+export declare function databricksWorkspaceConfig(options?: DatabricksWorkspaceOptions): WorkspaceConfig;
+/** Create a native Mastra {@link Workspace} from {@link databricksWorkspaceConfig}. */
+export declare function databricksWorkspace(options?: DatabricksWorkspaceOptions): Workspace;
 /**
- * Merge the configured skill folders over {@link DEFAULT_SKILL_FOLDERS}.
- *
- * `assistantSkills: false` drops the defaults, and a `false` value removes one
- * entry by name.
+ * Resolve default and caller-provided Databricks paths in priority order.
  */
-export declare function resolveSkillFolders(options?: Pick<CreateWorkspaceOptions, "assistantSkills" | "skillFolders">): Record<string, SkillFolderOptions>;
+export declare function resolveDatabricksWorkspacePaths(options?: Pick<DatabricksWorkspaceOptions, "assistantPaths" | "paths">): DatabricksWorkspacePathValue[];