@dbx-tools/appkit-mastra 0.9.117 → 0.9.119

package/src/remote-skills.ts

@@ -5,7 +5,7 @@
  * {@link AITOOLS_SOURCE} constant, a GitHub `owner/repo`, any git / GitLab URL,
  * or a direct download URL - and optional per-source policy.
  * {@link provisionRemoteSkills} materializes every source into a local
- * `SKILL.md` tree at app boot and returns read-only backing directories plus
+ * `SKILL.md` tree at app boot and returns read-only filesystem backings plus
  * their stable virtual workspace mounts.
  *
  * Resolution per source, in order:
@@ -26,25 +26,16 @@
  * source (or the top-level call) sets `failOnError: false`, in which case it is
  * logged and skipped so one bad source never takes the app down.
  *
- * Every provisioned tree carries a {@link METADATA_FILE} recording when each
- * source was last downloaded, and a source is only re-downloaded once that
- * record is older than {@link DEFAULT_REFRESH_TTL_MS} (seven days). This runs at app
- * BOOT, so without it a container that restarts a dozen times an hour re-pulls
- * the whole AI Tools set a dozen times for content that changes rarely. The
- * record travels WITH the tree rather than in process memory, so the reuse
- * survives a restart - which is the only way it helps a Databricks App at all.
- * Pass `refreshTtlMs: 0` to download on every boot.
+ * AI Tools uses the shared `@dbx-tools/cache` project cache with a one-day TTL,
+ * then hydrates one process-memory filesystem mounted at
+ * {@link AITOOLS_SKILLS_MOUNT} for every default workspace. Other sources keep
+ * a {@link METADATA_FILE} beside their provisioned tree and default to a
+ * seven-day refresh window. Pass `refreshTtlMs: 0` to download on every boot.
  *
- * The default destination is the Databricks workspace Assistant skills tree
- * (`/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 `/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
- * {@link openWritableWorkspace}) - the tree is written under
- * {@link localFS.tmpFS} and exposed through a stable read-only virtual mount
- * for the current process. Storage location degrades; the skills themselves do not.
+ * For non-AI-Tools sources, the default destination is the Databricks workspace
+ * Assistant skills tree (`/Workspace/.assistant/skills`). Pass `userEmail` or
+ * `databricksBasePath` to select another destination. When it is unavailable,
+ * the tree is exposed through a stable read-only local mount instead.
  *
  * @module
  */
@@ -55,6 +46,7 @@ import { dirname, join, posix } from "node:path";
 import type { WorkspaceClient } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
 import type { WorkspaceClientLike } from "@dbx-tools/appkit";
+import { flushCache, getOrSet, projectCache } from "@dbx-tools/cache/cache";
 import { exec } from "@dbx-tools/core";
 import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { localFS, type LocalFileSystem } from "@dbx-tools/fs";
@@ -70,7 +62,7 @@ import {
   stringUtils,
 } from "@dbx-tools/shared-core";
 import type { OneOrMany } from "@dbx-tools/shared-core";
-import type { FileSystem } from "@dbx-tools/shared-fs";
+import { MemoryFileSystem, type FileSystem } from "@dbx-tools/shared-fs";
 
 import { ORGANIZATION_SKILLS_PATH, personalSkillsPath } from "./skill-paths.ts";
 
@@ -116,9 +108,17 @@ const METADATA_FILE = ".metadata.json";
 /** Shape marker for {@link METADATA_FILE}; an unknown version is ignored, not read. */
 const METADATA_VERSION = 1;
 
-/** How long a provisioned source is reused before being downloaded again. */
+/** How long a general provisioned source is reused before being downloaded again. */
 const DEFAULT_REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
+/** How long the shared Databricks AI Tools snapshot is reused. */
+export const AITOOLS_REFRESH_TTL_MS = 24 * 60 * 60 * 1000;
+
+const aiToolsCache = projectCache("mastra-aitools", {
+  ttl: AITOOLS_REFRESH_TTL_MS,
+  maxEntries: 32,
+});
+
 /* ------------------------------ AI Tools ------------------------------ */
 
 /**
@@ -203,14 +203,25 @@ export type RemoteSkillsOption =
 /** A source entry with its `source` flattened to a plain string. */
 type NormalizedSource = Omit<RemoteSkillSourceOptions, "source"> & { source: string };
 
-/** Read-only local backing storage exposed at a stable virtual workspace path. */
-export interface LocalSkillMount {
+/** Read-only local directory exposed at a stable virtual workspace path. */
+export interface LocalSkillDirectoryMount {
   /** Physical local directory containing the provisioned `SKILL.md` tree. */
   root: string;
   /** Virtual path agents see inside the composed Mastra workspace. */
   mountPath: string;
 }
 
+/** Read-only process-local filesystem exposed at a stable virtual workspace path. */
+export interface MemorySkillMount {
+  /** Process-shared filesystem containing the provisioned `SKILL.md` tree. */
+  filesystem: FileSystem;
+  /** Virtual path agents see inside the composed Mastra workspace. */
+  mountPath: string;
+}
+
+/** Local skill backing accepted by every auto-created workspace. */
+export type LocalSkillMount = LocalSkillDirectoryMount | MemorySkillMount;
+
 /** Top-level remote-skills provisioning options. */
 export interface ProvisionRemoteSkillsOptions {
   /** Sources to materialize at startup. */
@@ -233,8 +244,8 @@ export interface ProvisionRemoteSkillsOptions {
   maxDownloadBytes?: number;
   /**
    * How long a provisioned tree is reused before its source is downloaded
-   * again, in milliseconds. Defaults to seven days; `0` re-downloads on every
-   * boot. A per-source `refreshTtlMs` wins over this.
+   * again, in milliseconds. AI Tools defaults to one day and other sources to
+   * seven days; `0` re-downloads on every boot. A per-source `refreshTtlMs` wins.
    */
   refreshTtlMs?: number;
 }
@@ -242,9 +253,10 @@ export interface ProvisionRemoteSkillsOptions {
 /** What {@link provisionRemoteSkills} resolved. */
 export interface ProvisionedRemoteSkills {
   /**
-   * Extra read-only LOCAL skill mounts to hand Mastra when a source couldn't
-   * be written to Databricks. Physical temp/cache paths remain hidden behind
-   * stable virtual workspace paths.
+   * Extra read-only local or process-memory skill mounts to hand Mastra. AI
+   * Tools always uses process memory; other sources use this fallback when
+   * they could not be written to Databricks. Physical paths remain hidden
+   * behind stable virtual workspace paths.
    */
   localSkillMounts: LocalSkillMount[];
   /** Absolute Databricks destination each source was written to, if any. */
@@ -257,8 +269,8 @@ export interface ProvisionedRemoteSkills {
 }
 
 /**
- * What one source's last download left behind, as recorded in
- * {@link METADATA_FILE}.
+ * Metadata for one resolved source snapshot. General remote sources store it
+ * in {@link METADATA_FILE}; AI Tools stores it with the cache-package value.
  */
 export interface RemoteSkillCacheEntry {
   /** The source string this entry was downloaded from, for readability. */
@@ -281,6 +293,20 @@ export interface RemoteSkillsMetadata {
   sources: Record<string, RemoteSkillCacheEntry>;
 }
 
+interface CachedSkillFile {
+  path: string;
+  content: string;
+}
+
+interface CachedAiToolsTree {
+  files: CachedSkillFile[];
+  record: RemoteSkillCacheEntry;
+}
+
+interface ResolvedAiToolsTree extends CachedAiToolsTree {
+  cached: boolean;
+}
+
 /* ------------------------------- helpers ------------------------------- */
 
 /** Normalize the `remoteSkills` option into a flat options bag. */
@@ -381,12 +407,16 @@ function remoteSourceIdentifier(source: string): string {
   return `${url.hostname}-${path}`;
 }
 
-/** The effective reuse window: per-source, then top-level, then seven days. */
+/** The effective reuse window: per-source, top-level, then the source default. */
 function resolveRefreshTtl(
   sourceOptions: NormalizedSource,
   options: ProvisionRemoteSkillsOptions,
 ): number {
-  return sourceOptions.refreshTtlMs ?? options.refreshTtlMs ?? DEFAULT_REFRESH_TTL_MS;
+  return (
+    sourceOptions.refreshTtlMs ??
+    options.refreshTtlMs ??
+    (isAiToolsSource(sourceOptions.source) ? AITOOLS_REFRESH_TTL_MS : DEFAULT_REFRESH_TTL_MS)
+  );
 }
 
 /**
@@ -465,12 +495,17 @@ export async function provisionRemoteSkills(
   if (!options) return empty;
 
   const failDefault = options.failOnError !== false;
+  const sources = (Array.isArray(options.sources) ? options.sources : [options.sources]).map(
+    toSourceOptions,
+  );
   const client = options.client ?? appkit.tryGetExecutionContext()?.client;
   // Probed rather than assumed: an identity that cannot write the workspace
   // tree falls back to the local one instead of failing startup. The probe also
   // creates the root, which the first cache READ needs - `copySkillDirs` would
   // otherwise be the first thing to create it, which is too late.
-  const requestedBasePath = resolveDatabricksBasePath(options, client);
+  const requestedBasePath = sources.some((source) => !isAiToolsSource(source.source))
+    ? resolveDatabricksBasePath(options, client)
+    : undefined;
   const destination = requestedBasePath
     ? await openWritableWorkspace(requestedBasePath, client as WorkspaceClient)
     : undefined;
@@ -481,15 +516,30 @@ export async function provisionRemoteSkills(
   let staging: LocalFileSystem | undefined;
 
   try {
-    const sources = Array.isArray(options.sources) ? options.sources : [options.sources];
-    for (const entry of sources) {
-      const sourceOptions = toSourceOptions(entry);
+    for (const sourceOptions of sources) {
       const failOnError = sourceOptions.failOnError ?? failDefault;
       try {
         // Where this source's bookkeeping lives: the shared Databricks tree, or
         // the source's own stable local dir.
         const key = cacheKey(sourceOptions);
         const mountPath = localSkillMountPath(sourceOptions, key);
+        if (isAiToolsSource(sourceOptions.source)) {
+          staging ??= await initializedScratch("mastra-remote-skills");
+          const tree = await cachedAiToolsTree(sourceOptions, staging.root, options, key);
+          localSkillMounts.push({
+            filesystem: await memorySkillTree(tree.files, `aitools-${key}`),
+            mountPath,
+          });
+          skillNames.push(...tree.record.skills);
+          logger.info("remote skill ready", {
+            source: sourceOptions.source,
+            destination: mountPath,
+            downloadedAt: tree.record.downloadedAt,
+            skills: tree.record.skills,
+            cached: tree.cached,
+          });
+          continue;
+        }
         const cacheFS = destination ?? localSkillsFS(key);
         const metadata = await readMetadata(cacheFS);
         const cached = metadata?.sources[key];
@@ -563,17 +613,87 @@ export async function provisionRemoteSkills(
   return { localSkillMounts, databricksBasePath, skillNames };
 }
 
+async function cachedAiToolsTree(
+  sourceOptions: NormalizedSource,
+  stagingRoot: string,
+  options: ProvisionRemoteSkillsOptions,
+  key: string,
+): Promise<ResolvedAiToolsTree> {
+  const ttl = resolveRefreshTtl(sourceOptions, options);
+  let loaded = false;
+  const load = async (): Promise<CachedAiToolsTree> => {
+    loaded = true;
+    const stagedDir = await stageAiTools(
+      sourceOptions,
+      join(stagingRoot, `aitools-${hash.id()}`),
+      options,
+    );
+    const staged = await collectSkillDirs(stagedDir);
+    if (staged.length === 0) {
+      throw new Error(`no SKILL.md found for source "${sourceOptions.source}"`);
+    }
+    const policy = cachePolicy(sourceOptions);
+    return {
+      files: await serializeSkillDirs(staged),
+      record: {
+        source: sourceOptions.source,
+        downloadedAt: new Date().toISOString(),
+        skills: staged.map((dir) => dir.name),
+        ...(policy ? { policy } : {}),
+      },
+    };
+  };
+  const tree =
+    ttl <= 0
+      ? await load()
+      : await getOrSet(aiToolsCache, key, load, {
+          ttl,
+          throwErrors: true,
+        });
+  if (!tree) throw new Error(`AI Tools cache returned no tree for ${key}`);
+  await flushCache(aiToolsCache);
+  return { ...tree, cached: !loaded };
+}
+
+async function serializeSkillDirs(dirs: readonly StagedSkillDir[]): Promise<CachedSkillFile[]> {
+  const files: CachedSkillFile[] = [];
+  for (const dir of dirs) {
+    for (const relative of find.findFiles("**/*", { cwd: dir.absolutePath, nodir: true })) {
+      files.push({
+        path: posix.join(dir.name, relative.split(/[\\/]/).join("/")),
+        content: (await readFile(join(dir.absolutePath, relative))).toString("base64"),
+      });
+    }
+  }
+  return files;
+}
+
+async function memorySkillTree(
+  files: readonly CachedSkillFile[],
+  id: string,
+): Promise<MemoryFileSystem> {
+  const filesystem = new MemoryFileSystem({ id, root: "/" });
+  await filesystem.init();
+  for (const file of files) {
+    await filesystem.writeFile(file.path, Buffer.from(file.content, "base64"), {
+      overwrite: true,
+    });
+  }
+  return filesystem;
+}
+
 /** Fail before workspace composition when two sources claim one virtual mount. */
 function assertUniqueLocalSkillMounts(mounts: readonly LocalSkillMount[]): void {
   const rootsByMount = new Map<string, string>();
   for (const mount of mounts) {
+    const identity = "root" in mount ? mount.root : mount.filesystem.id;
     const previousRoot = rootsByMount.get(mount.mountPath);
-    if (previousRoot && previousRoot !== mount.root) {
+    if (previousRoot && previousRoot !== identity) {
       throw new Error(
         `multiple remote skill sources resolve to virtual mount "${mount.mountPath}"; give each source a unique name`,
       );
     }
-    rootsByMount.set(mount.mountPath, mount.root);
+    rootsByMount.set(mount.mountPath, identity);
   }
 }
 

package/src/server.ts

@@ -409,6 +409,10 @@ const AGENT_METADATA = /^\/agents(\/[^/]+)?$/;
 const AGENT_SUSPENDED_RUNS = /^\/agents\/[^/]+\/suspended-runs$/i;
 /** Official AI SDK UI stream route, including `resumeData` continuations. */
 const AGENT_CHAT = /^\/chat\/[^/]+$/i;
+/** Durable run observation for one agent-owned chat stream. */
+const AGENT_CHAT_RUN = /^\/chat\/[^/]+\/runs\/[^/]+$/i;
+/** Explicit cancellation for one durable chat run. */
+const AGENT_CHAT_RUN_ABORT = /^\/chat\/[^/]+\/runs\/[^/]+\/abort$/i;
 /** Native resource-scoped memory reads used by history and the thread list. */
 const MEMORY_READ = /^\/memory\/threads(?:\/[^/]+(?:\/messages)?)?$/i;
 /** Native thread rename/delete routes. */
@@ -438,6 +442,8 @@ export function isMastraRequestAllowed(
   if (opts.mcpEnabled && (p === "/mcp" || p.startsWith("/mcp/"))) return true;
   const m = method.toUpperCase();
   if (m === "POST" && AGENT_CHAT.test(p)) return true;
+  if (m === "GET" && AGENT_CHAT_RUN.test(p)) return true;
+  if (m === "POST" && AGENT_CHAT_RUN_ABORT.test(p)) return true;
   if (m === "POST" && AGENT_INFERENCE.test(p)) return true;
   if (m === "GET" && (AGENT_METADATA.test(p) || AGENT_SUSPENDED_RUNS.test(p))) return true;
   if (m === "GET" && MEMORY_READ.test(p)) return true;

package/src/workspaces.ts

@@ -15,7 +15,6 @@
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { ConfigurationError, createWorkspaceClient } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
 import { appkit, pluginRegistry } from "@dbx-tools/appkit";
 import {
@@ -25,7 +24,7 @@ import {
 } from "@dbx-tools/appkit/files-cache";
 import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { LocalFileSystem } from "@dbx-tools/fs";
-import { match, type PathMatchInput } from "@dbx-tools/path";
+import { find, match, type PathMatchInput } from "@dbx-tools/path";
 import { errorUtils, log, object, stringUtils, token } from "@dbx-tools/shared-core";
 import {
   fs as sharedFS,
@@ -61,7 +60,6 @@ import {
 } from "./filesystems.ts";
 import { MontySandbox } from "./monty-sandbox.ts";
 import type { LocalSkillMount } from "./remote-skills.ts";
-import { DatabricksSandbox, type DatabricksWorkspaceSandboxOptions } from "./sandbox.ts";
 import { ORGANIZATION_ASSISTANT_PATH, personalWorkspacePath } from "./skill-paths.ts";
 
 /* ------------------------------ constants ------------------------------ */
@@ -79,6 +77,7 @@ const CACHEABLE_FILESYSTEM_OPERATIONS = [
 const logger = log.logger("mastra/workspaces");
 let workspaceSourceSequence = 0;
 const databricksWorkspaceOptions = new WeakMap<Workspace, DatabricksWorkspaceOptions>();
+const sharedSkillFilesystems = new Map<string, Promise<FileSystem>>();
 
 /* -------------------------------- types -------------------------------- */
 
@@ -174,16 +173,10 @@ type WorkspaceMountResolver = (
 
 /**
  * Sandbox selection for {@link databricksWorkspace}. Monty is the default;
- * command execution can be disabled or replaced with Databricks Sandbox or any
- * Mastra provider/resolver.
+ * command execution can be disabled or replaced with any Mastra provider/resolver.
  */
 export type WorkspaceSandboxSelection =
-  | false
-  | "databricks"
-  | "monty"
-  | DatabricksWorkspaceSandboxOptions
-  | WorkspaceSandbox
-  | WorkspaceSandboxResolver;
+  false | true | "monty" | WorkspaceSandbox | WorkspaceSandboxResolver;
 
 /** Native Mastra workspace options plus Databricks path shortcuts. */
 export interface DatabricksWorkspaceOptions extends Omit<
@@ -208,9 +201,8 @@ export interface DatabricksWorkspaceOptions extends Omit<
   /** AppKit plugin context used to discover optional sibling capabilities. */
   pluginContext?: pluginRegistry.PluginContextLike;
   /**
-   * Command sandbox. Defaults to Monty. Pass `false` to disable it,
-   * `"databricks"` or Databricks Sandbox options to select the remote provider,
-   * or an explicit Mastra sandbox/provider resolver.
+   * Command sandbox. Defaults to Monty. Pass `false` to disable it, or an
+   * explicit Mastra sandbox/provider resolver for a remote transport.
    */
   sandbox?: WorkspaceSandboxSelection;
   /** Add user-scoped `/tmp` only when no configured Databricks path mounts writable. */
@@ -418,49 +410,9 @@ function resolveWorkspaceSandbox(
 ): WorkspaceSandbox | WorkspaceSandboxResolver | undefined {
   const configured = selection ?? "monty";
   if (configured === false) return undefined;
-  if (configured === "monty") return new MontySandbox();
+  if (configured === true || configured === "monty") return new MontySandbox();
   if (typeof configured === "function" || isSandbox(configured)) return configured;
-
-  const options: DatabricksWorkspaceSandboxOptions =
-    configured === "databricks" ? { provider: "databricks" } : configured;
-  return ({ requestContext }) => {
-    const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
-    if (!user) {
-      throw ConfigurationError.resourceNotFound(
-        "Databricks sandbox user context",
-        "Invoke command tools from an agent turn served by the Mastra plugin.",
-      );
-    }
-    const configuredId =
-      typeof options.sandboxId === "function"
-        ? options.sandboxId({ requestContext })
-        : options.sandboxId;
-    const sandboxId = configuredId ?? defaultSandboxId(workspaceId, user.id);
-    const client =
-      typeof options.client === "function"
-        ? options.client({ requestContext })
-        : (options.client ?? createWorkspaceClient());
-    const {
-      provider: _provider,
-      sandboxId: _sandboxId,
-      client: _client,
-      ...sandboxOptions
-    } = options;
-    return new DatabricksSandbox({
-      ...sandboxOptions,
-      client,
-      sandboxId,
-      displayName: options.displayName ?? `Mastra ${workspaceName}`,
-    });
-  };
-}
-
-function defaultSandboxId(workspaceId: string, userId: string): string {
-  const digest = createHash("sha256")
-    .update(object.toStableKey({ workspaceId, userId }))
-    .digest("hex")
-    .slice(0, 32);
-  return `mastra-${digest}`;
+  throw new TypeError(`Unsupported workspace sandbox for ${workspaceId} (${workspaceName})`);
 }
 
 function isSandbox(value: unknown): value is WorkspaceSandbox {
@@ -471,10 +423,9 @@ function isSandbox(value: unknown): value is WorkspaceSandbox {
 
 function sandboxName(selection: WorkspaceSandboxSelection | undefined): string {
   if (selection === undefined || selection === false) return "disabled";
-  if (selection === "monty") return "monty";
-  if (selection === "databricks") return "databricks";
+  if (selection === true || selection === "monty") return "monty";
   if (typeof selection === "function") return "resolver";
-  return isSandbox(selection) ? selection.provider : (selection.provider ?? "databricks");
+  return selection.provider;
 }
 
 /**
@@ -844,25 +795,58 @@ function userTempFilesystem(
 function localSkillMountResolvers(mounts: readonly LocalSkillMount[]): WorkspaceMountResolver[] {
   const unique = new Map<string, LocalSkillMount>();
   for (const entry of mounts) {
-    const root = entry.root.trim();
-    if (!root) continue;
-    unique.set(`${entry.mountPath}\0${root}`, { root, mountPath: entry.mountPath });
+    const identity = "root" in entry ? entry.root.trim() : entry.filesystem.id;
+    if (!identity) continue;
+    unique.set(`${entry.mountPath}\0${identity}`, entry);
   }
-  return [...unique.values()].map(({ root, mountPath }) => {
-    const mount = posixPath.normalizeRoot(mountPath);
-    const source = new LocalFileSystem({
-      root,
-      readOnly: true,
-      createRoot: false,
-    });
-    const filesystem = filesystems(source, { readOnly: true });
-    return () => ({
-      mounts: { [mount]: filesystem },
-      skillPaths: [mount],
-    });
+  return [...unique.values()].map((entry) => {
+    const mount = posixPath.normalizeRoot(entry.mountPath);
+    const filesystem = inMemorySkillFilesystem(entry);
+    return async () => {
+      const source = await filesystem;
+      return {
+        mounts: { [mount]: filesystems(source, { readOnly: true }) },
+        skillPaths: [mount],
+      };
+    };
   });
 }
 
+function inMemorySkillFilesystem(mount: LocalSkillMount): Promise<FileSystem> {
+  const key = "root" in mount ? `root:${mount.root}` : `filesystem:${mount.filesystem.id}`;
+  const existing = sharedSkillFilesystems.get(key);
+  if (existing) return existing;
+  const loaded = loadInMemorySkillFilesystem(mount).catch((error) => {
+    if (sharedSkillFilesystems.get(key) === loaded) sharedSkillFilesystems.delete(key);
+    throw error;
+  });
+  sharedSkillFilesystems.set(key, loaded);
+  return loaded;
+}
+
+async function loadInMemorySkillFilesystem(mount: LocalSkillMount): Promise<FileSystem> {
+  if ("filesystem" in mount) {
+    await mount.filesystem.init();
+    return mount.filesystem;
+  }
+  const source = new LocalFileSystem({
+    root: mount.root,
+    readOnly: true,
+    createRoot: false,
+  });
+  await source.init();
+  const memory = new MemoryFileSystem({
+    id: `skills-${createHash("sha256").update(mount.root).digest("hex").slice(0, 16)}`,
+    root: "/",
+  });
+  await memory.init();
+  for (const relative of find.findFiles("**/*", { cwd: mount.root, nodir: true })) {
+    await memory.writeFile(relative, await source.readFile(relative), { overwrite: true });
+  }
+  await source.close();
+  return memory;
+}
+
 /**
  * Gate skill-folder mounts on the request's token.
  *

package/lib/src/sandbox.d.ts

@@ -1,108 +0,0 @@
-/**
- * Databricks Sandbox adapter for Mastra workspaces.
- *
- * Implements Mastra's foreground command surface over the Databricks Sandbox
- * REST API. Sandboxes are created lazily, retain their home directory across
- * inactivity stops, and execute untrusted shell commands outside the App
- * container.
- *
- * @module
- */
-import type { WorkspaceClient } from "@databricks/appkit";
-import type { RequestContext } from "@mastra/core/request-context";
-import type { CommandResult, ExecuteCommandOptions, ProviderStatus, SandboxInfo, WorkspaceSandbox } from "@mastra/core/workspace";
-import { type MontySandboxOptions } from "./monty-sandbox.ts";
-/** Options for one Databricks-backed Mastra sandbox. */
-export interface DatabricksSandboxOptions {
-    /** AppKit workspace client used for every sandbox API call. */
-    client: WorkspaceClient;
-    /** Resource id, with or without the `sandboxes/` prefix. */
-    sandboxId: string;
-    /** Human-readable Databricks label. */
-    displayName?: string;
-    /** Server-side idle timeout in protobuf duration form. Defaults to `900s`. */
-    inactivityTimeout?: string;
-    /** Maximum time to wait for the sandbox to become runnable. */
-    startupTimeoutMs?: number;
-    /** Default command timeout. Per-call `options.timeout` wins. */
-    commandTimeoutMs?: number;
-    /**
-     * Provider used only when Databricks Sandbox is definitively unavailable.
-     * Disabled by default. Pass `"monty"`, Monty options, or another Mastra
-     * sandbox to enable a fallback explicitly.
-     */
-    fallback?: false | "monty" | MontySandboxOptions | WorkspaceSandbox;
-}
-/** Databricks options accepted by the higher-level workspace factory. */
-export interface DatabricksWorkspaceSandboxOptions extends Omit<DatabricksSandboxOptions, "client" | "sandboxId"> {
-    /** Provider discriminator. Defaults to `databricks`. */
-    provider?: "databricks";
-    /**
-     * Credential source. Defaults to a fresh AppKit client using the normal
-     * environment/profile chain, which is the app service principal in a
-     * Databricks App.
-     */
-    client?: WorkspaceClient | ((context: {
-        requestContext: RequestContext;
-    }) => WorkspaceClient);
-    /**
-     * Fixed id or per-request resolver. Omit to derive a stable, opaque id from
-     * the workspace and attributed user.
-     */
-    sandboxId?: string | ((context: {
-        requestContext: RequestContext;
-    }) => string);
-}
-/** Mastra sandbox backed by Databricks serverless Sandbox compute. */
-export declare class DatabricksSandbox implements WorkspaceSandbox {
-    readonly id: string;
-    readonly name: string;
-    status: ProviderStatus;
-    error?: string;
-    private readonly client;
-    private readonly displayName;
-    private readonly inactivityTimeout;
-    private readonly startupTimeoutMs;
-    private readonly commandTimeoutMs;
-    private readonly fallbackConfig;
-    private readonly createdAt;
-    private remoteCreatedAt?;
-    private lastUsedAt?;
-    private activeFallback?;
-    private fallbackPromise?;
-    private startPromise?;
-    constructor(options: DatabricksSandboxOptions);
-    get provider(): string;
-    /** Ensure the remote sandbox exists and has reached its running state. */
-    start(): Promise<void>;
-    private startWithSignal;
-    private performStart;
-    /** Databricks home persistence is not a cloneable Mastra checkpoint. */
-    snapshot(): Promise<void>;
-    get supportsCheckpoints(): boolean;
-    /** Stop compute while preserving the sandbox home directory. */
-    stop(): Promise<void>;
-    /** Permanently delete the sandbox and its persisted home directory. */
-    destroy(): Promise<void>;
-    /** Execute one foreground shell command in the remote sandbox. */
-    executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<CommandResult>;
-    /** Activate the configured fallback once across concurrent command failures. */
-    private activateFallback;
-    /** Start and publish the configured fallback after rechecking active state. */
-    private startFallback;
-    /** Execute through the active fallback or return an unsupported result. */
-    private executeFallback;
-    /** Whether the adapter currently knows the remote sandbox to be running. */
-    isReady(): Promise<boolean>;
-    /** Report Mastra-facing sandbox metadata. */
-    getInfo(): Promise<SandboxInfo>;
-    /** Explain the Databricks execution boundary to the agent. */
-    getInstructions(): string;
-    private get resourcePath();
-    private getOrCreate;
-    private get;
-    private mutate;
-    private waitForState;
-    private rememberCreatedAt;
-    private request;
-}