@dbx-tools/appkit-mastra 0.1.100 → 0.1.102

package/dist/index.d.ts

@@ -1106,6 +1106,8 @@ declare function buildRenderDataTool(config: MastraPluginConfig): _mastra_core_t
 }, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;
 //#endregion
 //#region packages/appkit-mastra/src/filesystems.d.ts
+/** How {@link DatabricksWorkspaceFilesystem.init} handles a missing {@link basePath}. */
+type DatabricksMkdirsMode = boolean | "try";
 /** Options for {@link DatabricksWorkspaceFilesystem}. */
 interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOptions {
   /** Unique identifier for this filesystem instance. */
@@ -1118,12 +1120,16 @@ interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOptions {
    */
   basePath: string;
   /**
-   * When `true`, {@link init} and file operations fail if {@link basePath}
-   * is missing. When `false` (default), a missing base path yields an empty
-   * read-only namespace (only `/` exists).
+   * When the {@link basePath} is missing at {@link init}, create it with the
+   * matching Databricks `mkdirs` API. `"try"` (default) logs at debug and
+   * falls back to an empty read-only namespace on failure; `true` fails init;
+   * `false` skips creation and uses the empty namespace.
+   *
+   * A successful mkdir also satisfies the write-access probe when
+   * {@link readOnly} is omitted.
    */
-  requireBasePath?: boolean;
-  /** Block writes while still allowing reads. When omitted, {@link DatabricksWorkspaceFilesystem.init} probes write access. */
+  mkdirs?: DatabricksMkdirsMode;
+  /** Block writes while still allowing reads. When omitted, {@link init} probes write access. */
   readOnly?: boolean;
 }
 /** Normalize a Databricks base path (POSIX, no trailing slash). */
@@ -1154,15 +1160,14 @@ declare class DatabricksWorkspaceFilesystem extends MastraFilesystem {
   readonly basePath: string;
   status: ProviderStatus;
   private readonly client;
-  private readonly requireBasePath;
+  private readonly mkdirs;
   private _readOnly;
   private _basePathMissing;
   get readOnly(): boolean | undefined;
   /**
    * @param options.client - Defaults to the AppKit execution-context client.
+   * @param options.mkdirs - Default `"try"`; see {@link DatabricksMkdirsMode}.
    * @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: DatabricksWorkspaceFilesystemOptions);
   /** Resolve and sandbox a workspace-relative path under {@link basePath}. */
@@ -1174,20 +1179,13 @@ declare class DatabricksWorkspaceFilesystem extends MastraFilesystem {
   /** Map SDK / HTTP errors to Mastra workspace filesystem errors. */
   private rethrow;
   /**
-   * When {@link requireBasePath} is `false`, probe whether {@link basePath}
-   * exists and cache the result on {@link _basePathMissing}.
+   * Probe whether {@link basePath} exists and cache the result on
+   * {@link _basePathMissing}.
    */
   private resolveBasePathStatus;
-  /** Delegate to {@link emptyFilesystem} when the optional base path is missing. */
+  /** Delegate to {@link emptyFilesystem} when the base path is missing. */
   private emptyFallback;
   init(): Promise<void>;
-  /**
-   * 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.
-   */
-  private ensureBaseExists;
   /**
    * Write and delete a ephemeral probe file to detect read-only access when
    * {@link DatabricksWorkspaceFilesystemOptions.readOnly} was not set.
@@ -1675,4 +1673,4 @@ declare function buildSummarizeTool(config: MastraPluginConfig): _mastra_core_to
   maxWords?: number | undefined;
 }, unknown, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "summarize", unknown>;
 //#endregion
-export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, DatabricksWorkspaceFilesystem, type DatabricksWorkspaceFilesystemOptions, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraAgentDefinition, MastraAgentWorkspaceResolver, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, type SummarizeOptions, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, 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 };
+export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, type DatabricksMkdirsMode, DatabricksWorkspaceFilesystem, type DatabricksWorkspaceFilesystemOptions, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraAgentDefinition, MastraAgentWorkspaceResolver, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, type SummarizeOptions, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, 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 };

package/dist/index.js

@@ -3,7 +3,7 @@ import { DEFAULT_FUZZY_THRESHOLD, DEFAULT_MODEL_CACHE_TTL_MS, FALLBACK_MODEL_IDS
 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 { 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";
@@ -87,21 +87,20 @@ const TRACE_REQUEST_CONTEXT_KEYS = [
 
 //#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);
+/** Mastra error constructor for a known SDK filesystem failure, if any. */
+function filesystemSdkErrorType(err) {
+	if (err) {
+		const ctx = apiUtils.errorContext(err);
+		if (ctx.notAccessible) return FileNotFoundError;
+		else if (ctx.hasMessage("already", "exists")) return FileExistsError;
+		else if (ctx.hasMessage("not", "directory")) return NotDirectoryError;
+		else if (ctx.hasMessage("not", "file")) return IsDirectoryError;
+	}
+}
+const log$9 = logUtils.logger("mastra/filesystems");
 /** Normalize a Databricks base path (POSIX, no trailing slash). */
 function normalizeDatabricksBasePath(basePath) {
 	const trimmed = basePath.trim();
@@ -203,7 +202,7 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 	basePath;
 	status = "pending";
 	client;
-	requireBasePath;
+	mkdirs;
 	_readOnly;
 	_basePathMissing;
 	get readOnly() {
@@ -211,9 +210,8 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 	}
 	/**
 	* @param options.client - Defaults to the AppKit execution-context client.
+	* @param options.mkdirs - Default `"try"`; see {@link DatabricksMkdirsMode}.
 	* @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({
@@ -223,7 +221,7 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 		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.mkdirs = options.mkdirs ?? "try";
 		this._readOnly = options.readOnly;
 	}
 	/** Resolve and sandbox a workspace-relative path under {@link basePath}. */
@@ -243,16 +241,14 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 	/** 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 ErrorType = filesystemSdkErrorType(err);
+		if (ErrorType) throw new ErrorType(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}.
+	* Probe whether {@link basePath} exists and cache the result on
+	* {@link _basePathMissing}.
 	*/
 	async resolveBasePathStatus() {
 		if (this._basePathMissing !== void 0) return;
@@ -260,38 +256,36 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 			await this.assertAbsoluteReadable(this.basePath);
 			this._basePathMissing = false;
 		} catch (err) {
-			if (!this.requireBasePath && apiUtils.isNotFoundError(err)) {
+			if (apiUtils.errorContext(err).notAccessible) {
 				this._basePathMissing = true;
 				return;
 			}
 			this.rethrow(err, "/");
 		}
 	}
-	/** Delegate to {@link emptyFilesystem} when the optional base path is missing. */
+	/** Delegate to {@link emptyFilesystem} when the 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);
+		if (this._basePathMissing) {
+			if (this.mkdirs === false) return;
+			try {
+				await this.mkdirAbsolute(this.basePath);
+				this._basePathMissing = false;
+				if (this._readOnly === void 0) this._readOnly = false;
+			} catch (err) {
+				if (this.mkdirs === true) this.rethrow(err, "/");
+				log$9.debug("mkdirs:try-failed", {
+					basePath: this.basePath,
+					error: commonUtils.errorMessage(err)
+				});
+			}
+			return;
 		}
+		if (this._readOnly === void 0) await this.probeReadOnly();
 	}
 	/**
 	* Write and delete a ephemeral probe file to detect read-only access when
@@ -751,7 +745,7 @@ var DatabricksWorkspaceFilesystem = class extends MastraFilesystem {
 				mimeType: metadata["content-type"]
 			};
 		} catch (fileErr) {
-			if (!apiUtils.isNotFoundError(fileErr)) this.rethrow(fileErr, inputPath);
+			if (!apiUtils.errorContext(fileErr).notAccessible) this.rethrow(fileErr, inputPath);
 			await this.client.files.getDirectoryMetadata({ directory_path: absolutePath });
 			return {
 				name: posix.basename(absolutePath),
@@ -983,9 +977,9 @@ function resolveAssistantSkillsMounts(context) {
 			skillPaths: []
 		};
 	}
-	mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = readOnlyDatabricksFilesystem(client, ASSISTANT_SHARED_SKILLS_PATH);
+	mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = databricksFilesystem(client, ASSISTANT_SHARED_SKILLS_PATH);
 	const email = resolveScopedEmail(requestContext);
-	if (email) mounts[ASSISTANT_USER_SKILLS_MOUNT] = readOnlyDatabricksFilesystem(client, userAssistantSkillsPath(email));
+	if (email) mounts[ASSISTANT_USER_SKILLS_MOUNT] = databricksFilesystem(client, userAssistantSkillsPath(email), false);
 	log$8.debug("assistant-skills:mounted", {
 		sharedPath: ASSISTANT_SHARED_SKILLS_PATH,
 		sharedMount: ASSISTANT_WORKSPACE_SKILLS_MOUNT,
@@ -1042,11 +1036,11 @@ 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) {
+function databricksFilesystem(client, basePath, readOnly = true) {
 	return new DatabricksWorkspaceFilesystem({
 		client,
 		basePath,
-		readOnly: true
+		readOnly
 	});
 }
 /**
@@ -2344,7 +2338,7 @@ function buildAskGenieTool(opts) {
 				finalMessage = await runTurn();
 			} catch (err) {
 				const seeded = readContextConversationId(requestContext, spaceId);
-				if (seeded && apiUtils.isNotFoundError(err)) {
+				if (seeded && apiUtils.errorContext(err).notAccessible) {
 					log$6.warn("conversation-cache:stale, resetting", {
 						spaceId,
 						conversationId: seeded,
@@ -5215,7 +5209,7 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 				truncated: data.rows.length < data.rowCount
 			};
 		} catch (err) {
-			if (apiUtils.isNotFoundError(err)) return void 0;
+			if (apiUtils.errorContext(err).notAccessible) return void 0;
 			throw err;
 		}
 	}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/appkit-mastra-shared": "0.1.100",
-    "@dbx-tools/genie": "0.1.100",
-    "@dbx-tools/genie-shared": "0.1.100",
-    "@dbx-tools/model": "0.1.100",
-    "@dbx-tools/shared": "0.1.100",
+    "@dbx-tools/appkit-mastra-shared": "0.1.102",
+    "@dbx-tools/genie": "0.1.102",
+    "@dbx-tools/genie-shared": "0.1.102",
+    "@dbx-tools/model": "0.1.102",
+    "@dbx-tools/shared": "0.1.102",
     "@mastra/ai-sdk": "^1.6.0",
     "@mastra/core": "^1.47.0",
     "@mastra/express": "^1.4.2",