@dbx-tools/appkit-mastra 0.1.94 → 0.1.95

package/dist/index.js

@@ -1,12 +1,15 @@
 import { ChartSchema, ChartTypeSchema, DEFAULT_COMMENT_NAME, DEFAULT_FEEDBACK_NAME, MASTRA_ROUTES, MLFLOW_TRACE_ID_HEADER, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, MastraFeedbackRequestSchema, MastraUpdateThreadRequestSchema, THREAD_ID_HEADER, THREAD_ID_QUERY } from "@dbx-tools/appkit-mastra-shared";
 import { DEFAULT_FUZZY_THRESHOLD, DEFAULT_MODEL_CACHE_TTL_MS, FALLBACK_MODEL_IDS, ModelClass, ModelClass as ModelClass$1, clearServingEndpointsCache, listServingEndpoints, parseModelClass, selectModel } from "@dbx-tools/model";
-import { apiUtils, appkitUtils, commonUtils, httpUtils, logUtils, netUtils, projectUtils, stringUtils } from "@dbx-tools/shared";
+import { CompositeFilesystem, DirectoryNotEmptyError, DirectoryNotFoundError, FileExistsError, FileNotFoundError, IsDirectoryError, MastraFilesystem, NotDirectoryError, PermissionError, Workspace, WorkspaceReadOnlyError } from "@mastra/core/workspace";
+import { apiUtils, appkitUtils, commonUtils, httpUtils, logUtils, netUtils, projectUtils, stringUtils, tokenUtils } from "@dbx-tools/shared";
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
+import { ApiError, WorkspaceClient } from "@databricks/sdk-experimental";
+import { posix } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CacheManager, Plugin, genie, getExecutionContext, getUsernameWithApiLookup, lakebase, toPlugin } from "@databricks/appkit";
 import { Agent } from "@mastra/core/agent";
 import { createTool, createTool as createTool$1 } from "@mastra/core/tools";
-import { CacheManager, Plugin, genie, getExecutionContext, getUsernameWithApiLookup, lakebase, toPlugin } from "@databricks/appkit";
 import { z } from "zod";
-import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
-import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
 import { GenieMessageSchema } from "@dbx-tools/genie-shared";
 import { MCPServer } from "@mastra/mcp";
@@ -17,7 +20,6 @@ import { registerApiRoute } from "@mastra/core/server";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
-import { randomUUID } from "node:crypto";
 import { Pool } from "pg";
 import { Observability } from "@mastra/observability";
 import { OtelBridge } from "@mastra/otel-bridge";
@@ -54,6 +56,13 @@ const MASTRA_USER_EMAIL_KEY = "mastra__userEmail";
 */
 const MASTRA_REQUEST_ID_KEY = "mastra__requestId";
 /**
+* `RequestContext` key for OAuth scopes parsed from the forwarded
+* access token by {@link MastraServer.configureRequestContextScopes}.
+* Workspace mounts that touch Databricks workspace files require
+* `workspace` or `all-apis` in this list.
+*/
+const MASTRA_SCOPES_KEY = "mastra__scopes";
+/**
 * Canonical list of `RequestContext` keys we want Mastra to extract
 * as metadata on every observability span (agent runs, model calls,
 * tool invocations, workflow steps).
@@ -76,6 +85,965 @@ const TRACE_REQUEST_CONTEXT_KEYS = [
 	"mastra__model_override"
 ];
 
+//#endregion
+//#region packages/appkit-mastra/src/filesystems.ts
+/**
+* Mastra {@link WorkspaceFilesystem} implementations for Databricks Apps.
+*
+* {@link DatabricksWorkspaceFilesystem} maps a Mastra workspace namespace onto
+* an absolute Databricks path (Unity Catalog volume, workspace object tree, or
+* DBFS). {@link emptyFilesystem} is a read-only no-op mount used when no
+* dynamic mounts resolve for a request.
+*
+* Path helpers ({@link normalizeDatabricksBasePath}, {@link isDbfsPath}, …)
+* are exported for tests and callers that need to reason about Databricks
+* paths without constructing a filesystem.
+*/
+const DBFS_READ_CHUNK_BYTES = 1024 * 1024;
+const DBFS_PUT_MAX_BYTES = 1024 * 1024;
+const EMPTY_FILESYSTEM_EPOCH = /* @__PURE__ */ new Date(0);
+/** Normalize a Databricks base path (POSIX, no trailing slash). */
+function normalizeDatabricksBasePath(basePath) {
+	const trimmed = basePath.trim();
+	if (!trimmed.startsWith("/")) throw new Error(`Databricks base path must be absolute: ${basePath}`);
+	return trimmed.replace(/\/+$/, "") || "/";
+}
+/** True when `absolutePath` is served by DBFS rather than the UC Files API. */
+function isDbfsPath(absolutePath) {
+	return absolutePath === "/dbfs" || absolutePath.startsWith("/dbfs/");
+}
+/** True when `absolutePath` is a Databricks workspace object path. */
+function isWorkspaceFilesPath(absolutePath) {
+	return absolutePath === "/Workspace" || absolutePath.startsWith("/Workspace/") || absolutePath.startsWith("/Users/") || absolutePath.startsWith("/Repos/");
+}
+/**
+* Resolve a workspace-relative path to an absolute Databricks path under
+* `basePath`.
+*/
+function resolveDatabricksAbsolutePath(basePath, inputPath) {
+	const root = normalizeDatabricksBasePath(basePath);
+	const trimmed = inputPath.trim();
+	if (!trimmed || trimmed === "/") return root;
+	const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+	if (normalized === root || normalized.startsWith(`${root}/`)) return posix.normalize(normalized);
+	return posix.normalize(posix.join(root, normalized));
+}
+/** Map an absolute Databricks path back to the workspace namespace. */
+function toDatabricksWorkspacePath(basePath, absolutePath) {
+	const root = normalizeDatabricksBasePath(basePath);
+	const normalized = posix.normalize(absolutePath);
+	if (normalized === root) return "/";
+	if (normalized.startsWith(`${root}/`)) return normalized.slice(root.length) || "/";
+	return normalized;
+}
+/** Pick the Databricks Files API backend for an absolute path. */
+function resolveFilesBackend(absolutePath) {
+	if (isDbfsPath(absolutePath)) return "dbfs";
+	if (isWorkspaceFilesPath(absolutePath)) return "workspace";
+	return "uc-files";
+}
+/** Run the handler that matches `absolutePath`'s Databricks backend. */
+async function dispatchFilesBackend(absolutePath, handlers) {
+	const backend = resolveFilesBackend(absolutePath);
+	if (backend === "dbfs") return handlers.dbfs();
+	if (backend === "workspace") return handlers.workspace();
+	return handlers.ucFiles();
+}
+/** Return `buffer` as a string when `encoding` is set, otherwise unchanged. */
+function formatReadResult(buffer, encoding) {
+	return encoding ? buffer.toString(encoding) : buffer;
+}
+/** Drain a fetch `ReadableStream` into a single `Buffer`. */
+async function readResponseBody(contents) {
+	if (!contents) return Buffer.alloc(0);
+	const reader = contents.getReader();
+	const chunks = [];
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) chunks.push(value);
+	}
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+}
+/** Coerce Mastra {@link FileContent} to a `Buffer`. */
+function toBuffer(content) {
+	if (typeof content === "string") return Buffer.from(content, "utf8");
+	return Buffer.from(content);
+}
+/** Decode a DBFS read payload from base64. */
+function decodeDbfsPayload(data) {
+	if (!data) return Buffer.alloc(0);
+	return Buffer.from(data, "base64");
+}
+/** Wrap a `Buffer` as a one-shot `ReadableStream` for UC file uploads. */
+function bufferToReadableStream(buffer) {
+	return new ReadableStream({ start(controller) {
+		controller.enqueue(new Uint8Array(buffer));
+		controller.close();
+	} });
+}
+/** Parse an HTTP date header; returns epoch when missing or invalid. */
+function parseHttpDate(value) {
+	if (!value) return /* @__PURE__ */ new Date(0);
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? new Date(parsed) : /* @__PURE__ */ new Date(0);
+}
+/**
+* Mastra filesystem provider that reads and writes through a Databricks
+* {@link WorkspaceClient}.
+*
+* Workspace paths are absolute within the namespace (`/notes.md` maps to
+* `<basePath>/notes.md`). Unity Catalog volumes use the Files API;
+* `/dbfs/...` paths use DBFS.
+*/
+var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
+	id;
+	name = "DatabricksWorkspaceFilesystem";
+	provider = "databricks";
+	basePath;
+	status = "pending";
+	client;
+	requireBasePath;
+	_readOnly;
+	_basePathMissing;
+	get readOnly() {
+		return this._readOnly;
+	}
+	/**
+	* @param options.client - Defaults to the AppKit execution-context client.
+	* @param options.readOnly - When omitted, {@link init} probes write access.
+	* @param options.requireBasePath - When `false` (default), a missing
+	*   {@link basePath} yields an empty namespace instead of errors.
+	*/
+	constructor(options) {
+		super({
+			name: "DatabricksWorkspaceFilesystem",
+			...options
+		});
+		this.id = options.id ?? `databricks-fs-${commonUtils.fnvHash(options.basePath)}`;
+		this.client = options.client ?? getExecutionContext().client;
+		this.basePath = normalizeDatabricksBasePath(options.basePath);
+		this.requireBasePath = options.requireBasePath ?? false;
+		this._readOnly = options.readOnly;
+	}
+	/** Resolve and sandbox a workspace-relative path under {@link basePath}. */
+	resolvePath(inputPath) {
+		const resolved = resolveDatabricksAbsolutePath(this.basePath, inputPath);
+		if (resolved !== this.basePath && !resolved.startsWith(`${this.basePath}/`)) throw new PermissionError(inputPath, "access");
+		return resolved;
+	}
+	/** Map a Databricks absolute path back to the workspace namespace. */
+	workspacePath(absolutePath) {
+		return toDatabricksWorkspacePath(this.basePath, absolutePath);
+	}
+	/** Throw when the filesystem is read-only. */
+	assertWritable(operation) {
+		if (this.readOnly) throw new WorkspaceReadOnlyError(operation);
+	}
+	/** Map SDK / HTTP errors to Mastra workspace filesystem errors. */
+	rethrow(err, inputPath) {
+		const workspacePath = inputPath.startsWith("/") ? inputPath : this.workspacePath(this.resolvePath(inputPath));
+		if (apiUtils.isNotFoundError(err)) throw new FileNotFoundError(workspacePath);
+		if (err instanceof ApiError && err.errorCode === "RESOURCE_ALREADY_EXISTS") throw new FileExistsError(workspacePath);
+		if (err instanceof ApiError && err.errorCode === "NOT_DIRECTORY") throw new NotDirectoryError(workspacePath);
+		if (err instanceof ApiError && err.errorCode === "NOT_A_FILE") throw new IsDirectoryError(workspacePath);
+		const message = commonUtils.errorMessage(err);
+		throw new Error(`Databricks filesystem ${workspacePath}: ${message}`);
+	}
+	/**
+	* When {@link requireBasePath} is `false`, probe whether {@link basePath}
+	* exists and cache the result on {@link _basePathMissing}.
+	*/
+	async resolveBasePathStatus() {
+		if (this._basePathMissing !== void 0) return;
+		try {
+			await this.assertAbsoluteReadable(this.basePath);
+			this._basePathMissing = false;
+		} catch (err) {
+			if (!this.requireBasePath && apiUtils.isNotFoundError(err)) {
+				this._basePathMissing = true;
+				return;
+			}
+			this.rethrow(err, "/");
+		}
+	}
+	/** Delegate to {@link emptyFilesystem} when the optional base path is missing. */
+	async emptyFallback() {
+		if (this.requireBasePath) return void 0;
+		await this.resolveBasePathStatus();
+		return this._basePathMissing ? emptyFilesystem() : void 0;
+	}
+	async init() {
+		await this.resolveBasePathStatus();
+		if (this._basePathMissing) return;
+		if (!this.readOnly) await this.ensureBaseExists();
+		if (this._readOnly === void 0) await this.probeReadOnly();
+	}
+	/**
+	* Create the base directory when missing and writes are allowed.
+	*
+	* Uses raw SDK errors for the not-found branch so {@link apiUtils.isNotFoundError}
+	* still matches before {@link rethrow} wraps them as Mastra errors.
+	*/
+	async ensureBaseExists() {
+		try {
+			await this.assertAbsoluteReadable(this.basePath);
+		} catch (err) {
+			if (!apiUtils.isNotFoundError(err)) this.rethrow(err, "/");
+			await this.mkdirAbsolute(this.basePath);
+		}
+	}
+	/**
+	* Write and delete a ephemeral probe file to detect read-only access when
+	* {@link DatabricksWorkspaceFilesystemOptions.readOnly} was not set.
+	*
+	* @returns `true` when the probe write (and cleanup) succeeded.
+	*/
+	async probeReadOnly() {
+		const absolutePath = this.resolvePath(`/.__dbx_fs_probe_${commonUtils.id()}`);
+		try {
+			await this.writeAbsolute(absolutePath, Buffer.from("probe\n"), true);
+			this._readOnly = false;
+		} catch {
+			this._readOnly = true;
+			return false;
+		}
+		try {
+			await this.deleteAbsoluteFile(absolutePath);
+		} catch {}
+		return true;
+	}
+	async destroy() {}
+	/** Probe that `absolutePath` exists (file or directory metadata). */
+	async assertAbsoluteReadable(absolutePath) {
+		await dispatchFilesBackend(absolutePath, {
+			dbfs: () => this.client.dbfs.getStatus({ path: absolutePath }),
+			workspace: () => this.client.workspace.getStatus({ path: absolutePath }),
+			ucFiles: () => this.client.files.getDirectoryMetadata({ directory_path: absolutePath })
+		});
+	}
+	/** Read the full contents of `absolutePath` from the matching backend. */
+	async readAbsolute(absolutePath) {
+		return dispatchFilesBackend(absolutePath, {
+			dbfs: () => this.readDbfsFile(absolutePath),
+			workspace: () => this.readWorkspaceFile(absolutePath),
+			ucFiles: async () => {
+				return readResponseBody((await this.client.files.download({ file_path: absolutePath })).contents);
+			}
+		});
+	}
+	/** Write `buffer` to `absolutePath` on the matching backend. */
+	async writeAbsolute(absolutePath, buffer, overwrite) {
+		await dispatchFilesBackend(absolutePath, {
+			dbfs: () => this.writeDbfsFile(absolutePath, buffer, overwrite),
+			workspace: () => this.writeWorkspaceFile(absolutePath, buffer, overwrite),
+			ucFiles: () => this.uploadUcFile(absolutePath, buffer, overwrite)
+		});
+	}
+	/** Upload a buffer to a Unity Catalog Files API path. */
+	uploadUcFile(absolutePath, buffer, overwrite) {
+		return this.client.files.upload({
+			file_path: absolutePath,
+			contents: bufferToReadableStream(buffer),
+			overwrite
+		});
+	}
+	/** Delete a single file at `absolutePath` (non-recursive). */
+	async deleteAbsoluteFile(absolutePath) {
+		await dispatchFilesBackend(absolutePath, {
+			dbfs: () => this.client.dbfs.delete({
+				path: absolutePath,
+				recursive: false
+			}),
+			workspace: () => this.client.workspace.delete({
+				path: absolutePath,
+				recursive: false
+			}),
+			ucFiles: () => this.client.files.delete({ file_path: absolutePath })
+		});
+	}
+	/**
+	* Delete a file or directory at `absolutePath`.
+	*
+	* DBFS and workspace APIs accept `recursive`; UC volumes recurse manually.
+	*/
+	async deleteAbsolutePath(absolutePath, recursive) {
+		await dispatchFilesBackend(absolutePath, {
+			dbfs: async () => {
+				await this.client.dbfs.delete({
+					path: absolutePath,
+					recursive
+				});
+			},
+			workspace: async () => {
+				await this.client.workspace.delete({
+					path: absolutePath,
+					recursive
+				});
+			},
+			ucFiles: async () => {
+				if (recursive) {
+					await this.deleteUcDirectoryRecursive(absolutePath);
+					return;
+				}
+				if ((await this.listAbsoluteDirectory(absolutePath)).length > 0) throw new DirectoryNotEmptyError(this.workspacePath(absolutePath));
+				await this.client.files.deleteDirectory({ directory_path: absolutePath });
+			}
+		});
+	}
+	/** Create `absolutePath` and any missing parents on the matching backend. */
+	async mkdirAbsolute(absolutePath) {
+		await dispatchFilesBackend(absolutePath, {
+			dbfs: () => this.client.dbfs.mkdirs({ path: absolutePath }),
+			workspace: () => this.client.workspace.mkdirs({ path: absolutePath }),
+			ucFiles: () => this.client.files.createDirectory({ directory_path: absolutePath })
+		});
+	}
+	async readDbfsFile(absolutePath) {
+		const chunks = [];
+		let offset = 0;
+		while (true) {
+			const chunk = decodeDbfsPayload((await this.client.dbfs.read({
+				path: absolutePath,
+				offset,
+				length: DBFS_READ_CHUNK_BYTES
+			})).data);
+			if (chunk.length === 0) break;
+			chunks.push(chunk);
+			offset += chunk.length;
+			if (chunk.length < DBFS_READ_CHUNK_BYTES) break;
+		}
+		return Buffer.concat(chunks);
+	}
+	async readWorkspaceFile(absolutePath) {
+		return decodeDbfsPayload((await this.client.workspace.export({
+			path: absolutePath,
+			format: "AUTO"
+		})).content);
+	}
+	async writeDbfsFile(absolutePath, buffer, overwrite) {
+		if (buffer.length <= DBFS_PUT_MAX_BYTES) {
+			await this.client.dbfs.put({
+				path: absolutePath,
+				contents: buffer.toString("base64"),
+				overwrite
+			});
+			return;
+		}
+		const handle = (await this.client.dbfs.create({
+			path: absolutePath,
+			overwrite
+		})).handle;
+		if (handle === void 0) throw new Error(`DBFS create did not return a handle for ${absolutePath}`);
+		for (let offset = 0; offset < buffer.length; offset += DBFS_PUT_MAX_BYTES) {
+			const slice = buffer.subarray(offset, offset + DBFS_PUT_MAX_BYTES);
+			await this.client.dbfs.addBlock({
+				handle,
+				data: slice.toString("base64")
+			});
+		}
+		await this.client.dbfs.close({ handle });
+	}
+	async writeWorkspaceFile(absolutePath, buffer, overwrite) {
+		await this.client.workspace.import({
+			path: absolutePath,
+			format: "AUTO",
+			content: buffer.toString("base64"),
+			overwrite
+		});
+	}
+	getInfo() {
+		return {
+			id: this.id,
+			name: this.name,
+			provider: this.provider,
+			status: this.status,
+			readOnly: this.readOnly,
+			metadata: { basePath: this.basePath }
+		};
+	}
+	getInstructions() {
+		return [
+			`Files live in Databricks under ${this.basePath}.`,
+			"Workspace paths are absolute within this root (for example `/notes/report.md`).",
+			"Workspace paths use `/Workspace/...`, `/Users/...`, or `/Repos/...` base paths.",
+			"Unity Catalog volumes use `/Volumes/<catalog>/<schema>/<volume>/...` base paths."
+		].join(" ");
+	}
+	/** Map a workspace-relative path to the backing Databricks absolute path. */
+	resolveAbsolutePath(inputPath) {
+		return this.resolvePath(inputPath);
+	}
+	/** Read file contents from the workspace namespace. */
+	async readFile(inputPath, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.readFile(inputPath, options);
+		const absolutePath = this.resolvePath(inputPath);
+		try {
+			return formatReadResult(await this.readAbsolute(absolutePath), options?.encoding);
+		} catch (err) {
+			this.rethrow(err, inputPath);
+		}
+	}
+	/** Write file contents into the workspace namespace. */
+	async writeFile(inputPath, content, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.writeFile(inputPath, content, options);
+		this.assertWritable("writeFile");
+		const absolutePath = this.resolvePath(inputPath);
+		const buffer = toBuffer(content);
+		const overwrite = options?.overwrite ?? true;
+		try {
+			if (!overwrite && await this.exists(inputPath)) throw new FileExistsError(inputPath);
+			await this.writeAbsolute(absolutePath, buffer, overwrite);
+		} catch (err) {
+			if (err instanceof FileExistsError) throw err;
+			this.rethrow(err, inputPath);
+		}
+	}
+	/** Append to an existing file, creating it when missing. */
+	async appendFile(inputPath, content) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.appendFile(inputPath, content);
+		this.assertWritable("appendFile");
+		const existing = await this.exists(inputPath) ? await this.readFile(inputPath) : Buffer.alloc(0);
+		const merged = Buffer.concat([Buffer.isBuffer(existing) ? existing : Buffer.from(existing, "utf8"), toBuffer(content)]);
+		await this.writeFile(inputPath, merged, { overwrite: true });
+	}
+	/** Delete a file in the workspace namespace. */
+	async deleteFile(inputPath, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.deleteFile(inputPath, options);
+		this.assertWritable("deleteFile");
+		const absolutePath = this.resolvePath(inputPath);
+		try {
+			if (!await this.exists(inputPath)) {
+				if (options?.force) return;
+				throw new FileNotFoundError(inputPath);
+			}
+			if ((await this.stat(inputPath)).type === "directory") throw new IsDirectoryError(inputPath);
+			await this.deleteAbsoluteFile(absolutePath);
+		} catch (err) {
+			if (err instanceof FileNotFoundError || err instanceof IsDirectoryError) throw err;
+			this.rethrow(err, inputPath);
+		}
+	}
+	/** Copy a file within the workspace namespace. */
+	async copyFile(src, dest, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.copyFile(src, dest, options);
+		this.assertWritable("copyFile");
+		if (!(options?.overwrite ?? true) && await this.exists(dest)) throw new FileExistsError(dest);
+		const content = await this.readFile(src);
+		await this.writeFile(dest, content, { overwrite: true });
+	}
+	/** Move or rename a file within the workspace namespace. */
+	async moveFile(src, dest, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.moveFile(src, dest, options);
+		this.assertWritable("moveFile");
+		const srcAbsolute = this.resolvePath(src);
+		const destAbsolute = this.resolvePath(dest);
+		const overwrite = options?.overwrite ?? true;
+		try {
+			if (!overwrite && await this.exists(dest)) throw new FileExistsError(dest);
+			if (resolveFilesBackend(srcAbsolute) === "dbfs" && resolveFilesBackend(destAbsolute) === "dbfs") {
+				await this.client.dbfs.move({
+					source_path: srcAbsolute,
+					destination_path: destAbsolute
+				});
+				return;
+			}
+			await this.copyFile(src, dest, { overwrite: true });
+			await this.deleteFile(src, { force: true });
+		} catch (err) {
+			if (err instanceof FileExistsError) throw err;
+			this.rethrow(err, dest);
+		}
+	}
+	/** Create a directory in the workspace namespace. */
+	async mkdir(inputPath, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.mkdir(inputPath, options);
+		this.assertWritable("mkdir");
+		const absolutePath = this.resolvePath(inputPath);
+		try {
+			await this.mkdirAbsolute(absolutePath);
+			if (!options?.recursive) return;
+		} catch (err) {
+			this.rethrow(err, inputPath);
+		}
+	}
+	/** Remove a directory from the workspace namespace. */
+	async rmdir(inputPath, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.rmdir(inputPath, options);
+		this.assertWritable("rmdir");
+		const absolutePath = this.resolvePath(inputPath);
+		try {
+			if (!await this.exists(inputPath)) {
+				if (options?.force) return;
+				throw new DirectoryNotFoundError(inputPath);
+			}
+			if ((await this.stat(inputPath)).type !== "directory") throw new NotDirectoryError(inputPath);
+			await this.deleteAbsolutePath(absolutePath, options?.recursive ?? false);
+		} catch (err) {
+			if (err instanceof DirectoryNotFoundError || err instanceof NotDirectoryError || err instanceof DirectoryNotEmptyError) throw err;
+			this.rethrow(err, inputPath);
+		}
+	}
+	/**
+	* Recursively delete a Unity Catalog directory tree.
+	*
+	* DBFS and workspace trees use native recursive delete via
+	* {@link deleteAbsolutePath} instead.
+	*/
+	async deleteUcDirectoryRecursive(absolutePath) {
+		for (const child of await this.listAbsoluteDirectory(absolutePath)) {
+			const childAbsolute = posix.join(absolutePath, child.name);
+			if (child.type === "directory") await this.deleteUcDirectoryRecursive(childAbsolute);
+			else await this.deleteAbsoluteFile(childAbsolute);
+		}
+		await this.client.files.deleteDirectory({ directory_path: absolutePath });
+	}
+	/** List entries in a workspace directory. */
+	async readdir(inputPath, options) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.readdir(inputPath, options);
+		const absolutePath = this.resolvePath(inputPath);
+		try {
+			const entries = await this.listAbsoluteDirectory(absolutePath);
+			const filtered = this.filterEntries(entries, options);
+			if (!options?.recursive) return filtered;
+			return this.readDirectoryRecursive(absolutePath, options, 0);
+		} catch (err) {
+			this.rethrow(err, inputPath);
+		}
+	}
+	async readDirectoryRecursive(absolutePath, options, depth, relativePrefix = "") {
+		const maxDepth = options.maxDepth ?? Number.POSITIVE_INFINITY;
+		const entries = this.filterEntries(await this.listAbsoluteDirectory(absolutePath), options);
+		const collected = [];
+		for (const entry of entries) {
+			const relativeName = relativePrefix ? posix.join(relativePrefix, entry.name) : entry.name;
+			collected.push({
+				...entry,
+				name: relativeName
+			});
+			if (entry.type !== "directory" || depth >= maxDepth) continue;
+			collected.push(...await this.readDirectoryRecursive(posix.join(absolutePath, entry.name), options, depth + 1, relativeName));
+		}
+		return collected;
+	}
+	async listAbsoluteDirectory(absolutePath) {
+		return dispatchFilesBackend(absolutePath, {
+			dbfs: async () => {
+				const entries = [];
+				for await (const info of this.client.dbfs.list({ path: absolutePath })) entries.push({
+					name: posix.basename(info.path ?? ""),
+					type: info.is_dir ? "directory" : "file",
+					size: info.file_size
+				});
+				return entries;
+			},
+			workspace: async () => {
+				const entries = [];
+				for await (const info of this.client.workspace.list({ path: absolutePath })) entries.push({
+					name: posix.basename(info.path ?? ""),
+					type: info.object_type === "DIRECTORY" ? "directory" : "file"
+				});
+				return entries;
+			},
+			ucFiles: async () => {
+				const entries = [];
+				for await (const entry of this.client.files.listDirectoryContents({ directory_path: absolutePath })) entries.push({
+					name: entry.name ?? posix.basename(entry.path ?? ""),
+					type: entry.is_directory ? "directory" : "file",
+					size: entry.file_size
+				});
+				return entries;
+			}
+		});
+	}
+	/** Apply Mastra list filters (`extension`, etc.) to directory entries. */
+	filterEntries(entries, options) {
+		if (!options?.extension) return entries;
+		const normalized = (Array.isArray(options.extension) ? options.extension : [options.extension]).map((ext) => ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`);
+		return entries.filter((entry) => {
+			if (entry.type !== "file") return true;
+			const lower = entry.name.toLowerCase();
+			return normalized.some((ext) => lower.endsWith(ext));
+		});
+	}
+	/** Return whether `inputPath` exists in the workspace namespace. */
+	async exists(inputPath) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.exists(inputPath);
+		try {
+			await this.stat(inputPath);
+			return true;
+		} catch (err) {
+			if (err instanceof FileNotFoundError) return false;
+			throw err;
+		}
+	}
+	/** Return file or directory metadata for `inputPath`. */
+	async stat(inputPath) {
+		await this.ensureReady();
+		const empty = await this.emptyFallback();
+		if (empty) return empty.stat(inputPath);
+		const absolutePath = this.resolvePath(inputPath);
+		const workspacePath = this.workspacePath(absolutePath);
+		try {
+			return await dispatchFilesBackend(absolutePath, {
+				dbfs: async () => {
+					const info = await this.client.dbfs.getStatus({ path: absolutePath });
+					return {
+						name: posix.basename(info.path ?? absolutePath),
+						path: workspacePath,
+						type: info.is_dir ? "directory" : "file",
+						size: info.file_size ?? 0,
+						createdAt: new Date(info.modification_time ?? 0),
+						modifiedAt: new Date(info.modification_time ?? 0)
+					};
+				},
+				workspace: async () => {
+					const info = await this.client.workspace.getStatus({ path: absolutePath });
+					return {
+						name: posix.basename(info.path ?? absolutePath),
+						path: workspacePath,
+						type: info.object_type === "DIRECTORY" ? "directory" : "file",
+						size: 0,
+						createdAt: new Date(info.created_at ?? 0),
+						modifiedAt: new Date(info.modified_at ?? 0)
+					};
+				},
+				ucFiles: () => this.statUcAbsolute(absolutePath, workspacePath, inputPath)
+			});
+		} catch (err) {
+			this.rethrow(err, inputPath);
+		}
+	}
+	/**
+	* Stat a Unity Catalog path by probing file metadata first, then
+	* directory metadata.
+	*/
+	async statUcAbsolute(absolutePath, workspacePath, inputPath) {
+		try {
+			const metadata = await this.client.files.getMetadata({ file_path: absolutePath });
+			return {
+				name: posix.basename(absolutePath),
+				path: workspacePath,
+				type: "file",
+				size: Number(metadata["content-length"] ?? 0),
+				createdAt: parseHttpDate(metadata["last-modified"]),
+				modifiedAt: parseHttpDate(metadata["last-modified"]),
+				mimeType: metadata["content-type"]
+			};
+		} catch (fileErr) {
+			if (!apiUtils.isNotFoundError(fileErr)) this.rethrow(fileErr, inputPath);
+			await this.client.files.getDirectoryMetadata({ directory_path: absolutePath });
+			return {
+				name: posix.basename(absolutePath),
+				path: workspacePath,
+				type: "directory",
+				size: 0,
+				createdAt: /* @__PURE__ */ new Date(0),
+				modifiedAt: /* @__PURE__ */ new Date(0)
+			};
+		}
+	}
+};
+/** Normalize paths for the in-memory empty filesystem namespace. */
+function normalizeEmptyFilesystemPath(inputPath) {
+	const trimmed = inputPath.trim();
+	if (!trimmed || trimmed === ".") return "/";
+	const normalized = trimmed.startsWith("/") ? posix.normalize(trimmed) : posix.normalize(`/${trimmed}`);
+	return normalized === "." ? "/" : normalized;
+}
+/**
+* Read-only in-memory {@link WorkspaceFilesystem} with a single empty root.
+* Use {@link emptyFilesystem} rather than constructing directly.
+*/
+var EmptyFilesystem = class extends MastraFilesystem {
+	id = "empty-fs";
+	name = "EmptyFilesystem";
+	provider = "empty";
+	readOnly = true;
+	status = "pending";
+	constructor() {
+		super({ name: "EmptyFilesystem" });
+	}
+	async init() {}
+	async destroy() {}
+	getInfo() {
+		return {
+			id: this.id,
+			name: this.name,
+			provider: this.provider,
+			status: this.status,
+			readOnly: this.readOnly
+		};
+	}
+	getInstructions() {
+		return "This filesystem is empty and read-only.";
+	}
+	rootStat() {
+		return {
+			name: "/",
+			path: "/",
+			type: "directory",
+			size: 0,
+			createdAt: EMPTY_FILESYSTEM_EPOCH,
+			modifiedAt: EMPTY_FILESYSTEM_EPOCH
+		};
+	}
+	assertWritable(operation) {
+		throw new WorkspaceReadOnlyError(operation);
+	}
+	async readFile(inputPath, _options) {
+		await this.ensureReady();
+		const normalized = normalizeEmptyFilesystemPath(inputPath);
+		if (normalized === "/") throw new IsDirectoryError(normalized);
+		throw new FileNotFoundError(normalized);
+	}
+	async writeFile(_inputPath, _content, _options) {
+		await this.ensureReady();
+		this.assertWritable("writeFile");
+	}
+	async appendFile(_inputPath, _content) {
+		await this.ensureReady();
+		this.assertWritable("appendFile");
+	}
+	async deleteFile(inputPath, options) {
+		await this.ensureReady();
+		const normalized = normalizeEmptyFilesystemPath(inputPath);
+		if (normalized === "/") throw new IsDirectoryError(normalized);
+		if (options?.force) return;
+		throw new FileNotFoundError(normalized);
+	}
+	async copyFile(src, _dest, _options) {
+		await this.ensureReady();
+		const normalizedSrc = normalizeEmptyFilesystemPath(src);
+		if (normalizedSrc !== "/") throw new FileNotFoundError(normalizedSrc);
+		throw new IsDirectoryError(normalizedSrc);
+	}
+	async moveFile(src, dest, options) {
+		await this.copyFile(src, dest, options);
+	}
+	async mkdir(_inputPath, _options) {
+		await this.ensureReady();
+		this.assertWritable("mkdir");
+	}
+	async rmdir(inputPath, options) {
+		await this.ensureReady();
+		const normalized = normalizeEmptyFilesystemPath(inputPath);
+		if (normalized === "/") throw new DirectoryNotEmptyError(normalized);
+		if (options?.force) return;
+		throw new DirectoryNotFoundError(normalized);
+	}
+	async readdir(inputPath, _options) {
+		await this.ensureReady();
+		const normalized = normalizeEmptyFilesystemPath(inputPath);
+		if (normalized === "/") return [];
+		throw new DirectoryNotFoundError(normalized);
+	}
+	async exists(inputPath) {
+		await this.ensureReady();
+		return normalizeEmptyFilesystemPath(inputPath) === "/";
+	}
+	async stat(inputPath) {
+		await this.ensureReady();
+		const normalized = normalizeEmptyFilesystemPath(inputPath);
+		if (normalized === "/") return this.rootStat();
+		throw new FileNotFoundError(normalized);
+	}
+};
+/** Memoized singleton empty read-only filesystem for no-op mounts. */
+const emptyFilesystem = commonUtils.memoize(() => new EmptyFilesystem());
+
+//#endregion
+//#region packages/appkit-mastra/src/workspaces.ts
+/** 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", "all-apis"];
+/**
+* Create a Mastra {@link Workspace} with per-request Databricks mounts.
+*
+* @example Assistant skills only (default for agents in this plugin)
+* ```ts
+* createWorkspace()
+* ```
+*
+* @example Assistant skills plus a custom mount resolver
+* ```ts
+* createWorkspace({
+*   assistantSkills: true,
+*   mounts: [
+*     async ({ requestContext }) => ({
+*       mounts: { "/data": myFilesystem },
+*       skillPaths: [],
+*     }),
+*   ],
+* })
+* ```
+*/
+function createWorkspace(options = {}) {
+	const { id, name } = resolveWorkspaceIdentity(options);
+	const resolvers = buildMountResolvers(options);
+	const skills = options.skills ?? (resolvers.length > 0 ? buildWorkspaceSkillsResolver(resolvers) : void 0);
+	return new Workspace({
+		id,
+		name,
+		filesystem: (context) => resolveWorkspaceFilesystem(resolvers, context),
+		...skills ? {
+			skills,
+			checkSkillFileMtime: options.checkSkillFileMtime ?? options.assistantSkills !== false
+		} : {},
+		...options.bm25 !== false ? { bm25: true } : {}
+	});
+}
+/**
+* Map an OBO user email to their Assistant skills directory in the
+* workspace namespace.
+*/
+function userAssistantSkillsPath(userEmail) {
+	return `/Users/${userEmail.trim()}/.assistant/skills`;
+}
+/**
+* Return whether the request token carries a scope that allows workspace
+* file API access (`workspace` or `all-apis` on {@link MASTRA_SCOPES_KEY}).
+*/
+function hasWorkspaceFileScope(requestContext) {
+	return tokenUtils.includesAccessTokenScope(requestContext?.get(MASTRA_SCOPES_KEY), WORKSPACE_FILE_SCOPES);
+}
+/**
+* Built-in mount resolver for Assistant `SKILL.md` trees.
+*
+* 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.
+*/
+function resolveAssistantSkillsMounts(context) {
+	const mounts = {};
+	const requestContext = context.requestContext;
+	if (!shouldMountAssistantSkills(requestContext)) return {
+		mounts,
+		skillPaths: []
+	};
+	const client = requestContext.get(MASTRA_USER_KEY)?.executionContext.client;
+	if (!client) return {
+		mounts,
+		skillPaths: []
+	};
+	mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = readOnlyDatabricksFilesystem(client, ASSISTANT_SHARED_SKILLS_PATH);
+	const email = resolveScopedEmail(requestContext);
+	if (email) mounts[ASSISTANT_USER_SKILLS_MOUNT] = readOnlyDatabricksFilesystem(client, userAssistantSkillsPath(email));
+	return {
+		mounts,
+		skillPaths: Object.keys(mounts)
+	};
+}
+/**
+* Fill in `id` and `name` when either is omitted on {@link CreateWorkspaceOptions}.
+* Slugifies `name` into `id`; tokenizes `id` into a display `name`.
+*/
+function resolveWorkspaceIdentity(options) {
+	let id = options.id;
+	let name = options.name;
+	if (!id) id = name ? stringUtils.toSlug(name) : "workspace";
+	if (!name) name = Array.from(stringUtils.tokenize(id)).join(" ");
+	return {
+		id,
+		name
+	};
+}
+/** Collect built-in and caller-supplied mount resolvers for one workspace. */
+function buildMountResolvers(options) {
+	const resolvers = [];
+	const { assistantSkills = true, mounts } = options;
+	if (assistantSkills) resolvers.push(resolveAssistantSkillsMounts);
+	if (mounts?.length) resolvers.push(...mounts);
+	return resolvers;
+}
+/**
+* Gate Assistant skill mounts on request context.
+*
+* Always allows mounts in development; in other environments requires
+* {@link hasWorkspaceFileScope}.
+*/
+function shouldMountAssistantSkills(requestContext) {
+	if (!requestContext) return false;
+	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) {
+	return (requestContext?.get(MASTRA_USER_EMAIL_KEY))?.trim() || void 0;
+}
+/** Construct a read-only {@link DatabricksWorkspaceFilesystem} for `basePath`. */
+function readOnlyDatabricksFilesystem(client, basePath) {
+	return new DatabricksWorkspaceFilesystem({
+		client,
+		basePath,
+		readOnly: true
+	});
+}
+/**
+* Run every mount resolver for one request and merge mounts plus skill paths.
+* Later resolvers overwrite mount keys from earlier ones.
+*/
+async function resolveWorkspaceContribution(resolvers, context) {
+	const mounts = {};
+	const skillPaths = [];
+	for (const resolver of resolvers) {
+		const contribution = await resolver(context);
+		Object.assign(mounts, contribution.mounts);
+		if (contribution.skillPaths?.length) skillPaths.push(...contribution.skillPaths);
+	}
+	return {
+		mounts,
+		skillPaths
+	};
+}
+/**
+* Dynamic filesystem resolver passed to Mastra {@link Workspace}.
+*
+* Returns a {@link CompositeFilesystem} when any mount resolved; otherwise
+* {@link emptyFilesystem}.
+*/
+async function resolveWorkspaceFilesystem(resolvers, context) {
+	const { mounts } = await resolveWorkspaceContribution(resolvers, context);
+	if (Object.keys(mounts).length === 0) return emptyFilesystem();
+	return new CompositeFilesystem({ mounts });
+}
+/**
+* Build the dynamic {@link SkillsResolver} that collects `skillPaths` from
+* every mount resolver on each request.
+*/
+function buildWorkspaceSkillsResolver(resolvers) {
+	return async (context) => {
+		const { skillPaths } = await resolveWorkspaceContribution(resolvers, context);
+		return skillPaths ?? [];
+	};
+}
+
 //#endregion
 //#region packages/appkit-mastra/src/serving-sanitize.ts
 /**
@@ -2150,7 +3118,11 @@ function deriveToolId(description) {
 * type inference and to match the AppKit API surface.
 */
 function createAgent(def) {
-	return def;
+	const workspace = def.workspace ?? createWorkspace();
+	return {
+		...def,
+		workspace
+	};
 }
 /** Fallback agent id used when `config.agents` is omitted entirely. */
 const FALLBACK_AGENT_ID = "default";
@@ -3325,6 +4297,7 @@ async function buildObservability(options) {
 * that lets the plugin's custom API routes (e.g. `historyRoute`) work
 * behind an Express mount point.
 */
+logUtils.logger("mastra/server");
 /**
 * OpenTelemetry's sentinel for "no valid trace" - 32 zero hex chars.
 * `trace.getActiveSpan()` returns a non-recording span with this id
@@ -3352,12 +4325,13 @@ var MastraServer$1 = class extends MastraServer {
 	}
 	registerAuthMiddleware() {
 		super.registerAuthMiddleware();
-		this.app.use((req, res, next) => {
+		this.app.use(async (req, res, next) => {
 			const requestContext = res.locals.requestContext;
-			this.configureRequestContextUser(requestContext);
+			await this.configureRequestContextUser(requestContext);
 			this.configureRequestContextThreadId(req, res, requestContext);
 			this.configureRequestContextModelOverride(req, requestContext);
 			this.configureRequestContextRequestId(req, res, requestContext);
+			this.configureRequestContextScopes(req, requestContext);
 			this.configureMlflowTraceId(res);
 			this.log.debug("auth:middleware", {
 				method: req.method,
@@ -3372,7 +4346,7 @@ var MastraServer$1 = class extends MastraServer {
 			next();
 		});
 	}
-	configureRequestContextUser(requestContext) {
+	async configureRequestContextUser(requestContext) {
 		if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))) return;
 		const executionContext = getExecutionContext();
 		const user = {
@@ -3381,10 +4355,18 @@ var MastraServer$1 = class extends MastraServer {
 		};
 		requestContext.set(MASTRA_USER_KEY, user);
 		requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+		let userName;
+		let email;
 		if ("isUserContext" in executionContext) {
-			if (executionContext.userName) requestContext.set(MASTRA_USER_NAME_KEY, executionContext.userName);
-			if (executionContext.userEmail) requestContext.set(MASTRA_USER_EMAIL_KEY, executionContext.userEmail);
+			userName = executionContext.userName;
+			email = executionContext.userEmail;
+		} else if (process.env.NODE_ENV === "development") {
+			const currentUser = await executionContext.client.currentUser.me();
+			userName = currentUser?.userName;
+			email = currentUser?.emails?.filter((email) => email.primary).find((email) => email.value)?.value;
 		}
+		if (userName) requestContext.set(MASTRA_USER_NAME_KEY, userName);
+		if (email) requestContext.set(MASTRA_USER_EMAIL_KEY, email);
 	}
 	/**
 	* Stamp a per-request id and echo it on the response so an upstream
@@ -3405,6 +4387,16 @@ var MastraServer$1 = class extends MastraServer {
 		res.setHeader("X-Request-Id", requestId);
 	}
 	/**
+	* Stamp OAuth scopes from the forwarded access token on
+	* {@link MASTRA_SCOPES_KEY} for workspace mount gating.
+	*/
+	configureRequestContextScopes(req, requestContext) {
+		const scopes = /* @__PURE__ */ new Set();
+		for (const scope of tokenUtils.getAccessTokenScopes(req)) scopes.add(scope);
+		for (const scope of tokenUtils.getAccessTokenScopes(req, "authorization")) scopes.add(scope);
+		requestContext.set(MASTRA_SCOPES_KEY, [...scopes]);
+	}
+	/**
 	* Stamp the turn's MLflow trace id on the response so the chat client
 	* can attach thumbs / comment feedback to it later. MLflow derives
 	* its trace id from the OpenTelemetry trace id (`tr-<hex>`), and every
@@ -4289,4 +5281,4 @@ function parseStatementLimit(raw) {
 const mastra = toPlugin(MastraPlugin);
 
 //#endregion
-export { DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, GENIE_INSTRUCTIONS, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraPlugin, TRACE_REQUEST_CONTEXT_KEYS, approvalGatedToolIds, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };
+export { DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, DatabricksWorkspaceFilesystem, FALLBACK_AGENT_ID, GENIE_INSTRUCTIONS, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraPlugin, TRACE_REQUEST_CONTEXT_KEYS, approvalGatedToolIds, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, createWorkspace, emptyFilesystem, extractModelOverride, fetchChart, isDbfsPath, isWorkspaceFilesPath, mastra, normalizeDatabricksBasePath, normalizeGenieSpaces, prepareChart, resolveDatabricksAbsolutePath, resolveGenieSpaces, summarizeText, toDatabricksWorkspacePath, tool };