@dbx-tools/appkit-mastra 0.1.94 → 0.1.95

package/README.md

@@ -18,7 +18,9 @@ history / listing in [`history.ts`](src/history.ts) /
 [`threads.ts`](src/threads.ts), Model Serving resolution in
 [`model.ts`](src/model.ts) / [`serving.ts`](src/serving.ts), Genie
 tooling in [`genie.ts`](src/genie.ts), the chart pipeline in
-[`chart.ts`](src/chart.ts), and MLflow feedback logging in
+[`chart.ts`](src/chart.ts), Databricks workspace mounts in
+[`workspaces.ts`](src/workspaces.ts) / [`filesystems.ts`](src/filesystems.ts),
+and MLflow feedback logging in
 [`mlflow.ts`](src/mlflow.ts) (over the shared REST helper in
 [`rest.ts`](src/rest.ts)).
 
@@ -92,7 +94,57 @@ Override per plugin or per agent by passing `memory` / `storage` as
 index / schema). The fields are typed in [`config.ts`](src/config.ts);
 the wiring is in [`memory.ts`](src/memory.ts).
 
-### Conversations (threads)
+## Workspace and Assistant skills
+
+Every `createAgent` call applies a Mastra `Workspace` by default via
+`createWorkspace()` ([`workspaces.ts`](src/workspaces.ts)). The
+workspace is resolved per request and backed by the OBO user's
+`WorkspaceClient` through [`filesystems.ts`](src/filesystems.ts).
+
+Unless you opt out, `assistantSkills: true` mounts read-only Databricks
+trees where Mastra looks for `SKILL.md` files:
+
+| Databricks path | Workspace mount |
+| --- | --- |
+| `/Workspace/.assistant/skills` | `/workspace_skills` |
+| `/Users/<email>/.assistant/skills` | `/workspace_user_skills` |
+
+Production mounts require `workspace` or `all-apis` on the forwarded
+access token. [`server.ts`](src/server.ts) stamps parsed scopes on
+`MASTRA_SCOPES_KEY` using `tokenUtils` from `@dbx-tools/shared`.
+`NODE_ENV=development` skips the scope gate.
+
+```ts
+import { createAgent, createWorkspace } from "@dbx-tools/appkit-mastra";
+
+// Default: Assistant skills on.
+const support = createAgent({ instructions: "..." });
+
+// Extra per-request mounts (merged with built-in skill mounts).
+const analyst = createAgent({
+  instructions: "...",
+  workspace: createWorkspace({
+    mounts: [
+      async () => ({
+        mounts: { "/data": myFilesystem },
+        skillPaths: [],
+      }),
+    ],
+  }),
+});
+
+// Disable built-in skill mounts.
+const bare = createAgent({
+  instructions: "...",
+  workspace: createWorkspace({ assistantSkills: false }),
+});
+```
+
+Exported for direct use: `createWorkspace`, `DatabricksWorkspaceFilesystem`,
+`emptyFilesystem`, and path helpers (`normalizeDatabricksBasePath`,
+`isDbfsPath`, `resolveDatabricksAbsolutePath`, ...).
+
+## Conversations (threads)
 
 When storage is on, a user owns many conversation threads. The plugin
 resolves the thread a request targets from `RequestContext`, in order:

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 import { Chart } from "@dbx-tools/appkit-mastra-shared";
 import { ServingEndpointSummary } from "@dbx-tools/model";
+import { CopyOptions, FileContent, FileEntry, FileStat, FilesystemInfo, ListOptions, MastraFilesystem, MastraFilesystemOptions, ProviderStatus, ReadOptions, RemoveOptions, SkillsResolver, Workspace, WorkspaceFilesystem, WriteOptions } from "@mastra/core/workspace";
 import { appkitUtils, logUtils } from "@dbx-tools/shared";
+import { RequestContext } from "@mastra/core/request-context";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import * as _databricks_appkit0 from "@databricks/appkit";
+import { BasePluginConfig, IAppRouter, Plugin, ResourceRequirement } from "@databricks/appkit";
 import * as _mastra_core_agent0 from "@mastra/core/agent";
 import { Agent, AgentConfig, ToolsInput } from "@mastra/core/agent";
 import * as _mastra_core_tools0 from "@mastra/core/tools";
 import { Tool, createTool } from "@mastra/core/tools";
-import * as _databricks_appkit0 from "@databricks/appkit";
-import { BasePluginConfig, IAppRouter, Plugin, ResourceRequirement } from "@databricks/appkit";
 import { z } from "zod";
-import { RequestContext } from "@mastra/core/request-context";
-import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { MCPServer } from "@mastra/mcp";
 import { Mastra } from "@mastra/core/mastra";
 import express from "express";
@@ -17,7 +18,6 @@ import { Memory } from "@mastra/memory";
 import { PgVectorConfig, PostgresStore, PostgresStoreConfig } from "@mastra/pg";
 import { Pool } from "pg";
 import { MastraServer } from "@mastra/express";
-import { Workspace } from "@mastra/core/workspace";
 import * as _mastra_core_workflows0 from "@mastra/core/workflows";
 import * as _mastra_core_vector0 from "@mastra/core/vector";
 import * as _mastra_core_tts0 from "@mastra/core/tts";
@@ -30,6 +30,62 @@ import * as _mastra_core_channels0 from "@mastra/core/channels";
 export * from "@dbx-tools/appkit-mastra-shared";
 export * from "@dbx-tools/model";
 
+//#region packages/appkit-mastra/src/workspaces.d.ts
+/** Per-request context for mount resolvers. */
+interface WorkspaceMountContext {
+  requestContext?: RequestContext;
+}
+/** Mount map plus optional Mastra skill scan roots for one resolver. */
+interface WorkspaceMountContribution {
+  mounts: Record<string, WorkspaceFilesystem>;
+  /** Paths within the composite namespace where `SKILL.md` files are scanned. */
+  skillPaths?: string[];
+}
+/** Contributes filesystem mounts (and optional skill paths) for one request. */
+type WorkspaceMountResolver = (context: WorkspaceMountContext) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
+/** Options for {@link createWorkspace}. */
+interface CreateWorkspaceOptions {
+  /** Workspace id; derived from `name` or `"workspace"` when omitted. */
+  id?: string;
+  /** Display name; derived from `id` when omitted. */
+  name?: string;
+  /**
+   * Mount read-only Assistant skill trees from `/Workspace/.assistant/skills`
+   * and `/Users/<email>/.assistant/skills`. Defaults to `true`.
+   */
+  assistantSkills?: boolean;
+  /** Extra per-request mount resolvers (run after built-in options). */
+  mounts?: WorkspaceMountResolver[];
+  /** Replace the auto-built dynamic skills resolver. */
+  skills?: SkillsResolver;
+  /** Forwarded to Mastra when skill discovery is enabled. */
+  checkSkillFileMtime?: boolean;
+  /** Enable BM25 keyword search over indexed workspace content. */
+  bm25?: boolean;
+}
+/**
+ * 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: [],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function createWorkspace(options?: CreateWorkspaceOptions): Workspace;
+//#endregion
 //#region packages/appkit-mastra/src/genie.d.ts
 /** Default alias used when a single unnamed Genie space is wired up. */
 declare const DEFAULT_GENIE_ALIAS = "default";
@@ -179,6 +235,13 @@ declare const MASTRA_USER_EMAIL_KEY = "mastra__userEmail";
  * join key.
  */
 declare 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.
+ */
+declare 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,
@@ -829,13 +892,9 @@ interface MastraAgentDefinition {
    */
   storage?: boolean | MastraStorageConfigOverride;
   /**
-   * Mastra {@link Workspace} for this agent. When it exposes skills,
-   * Mastra injects `<available_skills>` metadata each turn and mounts
-   * `skill` / `skill_search` / `skill_read` at runtime.
-   *
-   * Use a zero-arg function so resolution happens at agent registration
-   * (for example `skillWorkspace` from `@dbx-tools/appkit-skills`
-   * after `aiDevKit()` has primed the cache).
+   * Mastra {@link Workspace} for this agent (filesystem, sandbox, or other
+   * providers). Assistant skills from Databricks workspace paths are wired
+   * via {@link createWorkspace}.
    */
   workspace?: Workspace | MastraAgentWorkspaceResolver;
 }
@@ -1046,6 +1105,200 @@ declare function buildRenderDataTool(config: MastraPluginConfig): _mastra_core_t
   chartId: string;
 }, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;
 //#endregion
+//#region packages/appkit-mastra/src/filesystems.d.ts
+/** Options for {@link DatabricksWorkspaceFilesystem}. */
+interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOptions {
+  /** Unique identifier for this filesystem instance. */
+  id?: string;
+  /** Auth-scoped Databricks workspace client. */
+  client?: WorkspaceClient;
+  /**
+   * Absolute Databricks path that roots the workspace namespace, e.g.
+   * `/Volumes/catalog/schema/volume` or `/dbfs/FileStore/shared`.
+   */
+  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).
+   */
+  requireBasePath?: boolean;
+  /** Block writes while still allowing reads. When omitted, {@link DatabricksWorkspaceFilesystem.init} probes write access. */
+  readOnly?: boolean;
+}
+/** Normalize a Databricks base path (POSIX, no trailing slash). */
+declare function normalizeDatabricksBasePath(basePath: string): string;
+/** True when `absolutePath` is served by DBFS rather than the UC Files API. */
+declare function isDbfsPath(absolutePath: string): boolean;
+/** True when `absolutePath` is a Databricks workspace object path. */
+declare function isWorkspaceFilesPath(absolutePath: string): boolean;
+/**
+ * Resolve a workspace-relative path to an absolute Databricks path under
+ * `basePath`.
+ */
+declare function resolveDatabricksAbsolutePath(basePath: string, inputPath: string): string;
+/** Map an absolute Databricks path back to the workspace namespace. */
+declare function toDatabricksWorkspacePath(basePath: string, absolutePath: string): string;
+/**
+ * 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.
+ */
+declare class DatabricksWorkspaceFilesystem extends MastraFilesystem {
+  readonly id: string;
+  readonly name = "DatabricksWorkspaceFilesystem";
+  readonly provider = "databricks";
+  readonly basePath: string;
+  status: ProviderStatus;
+  private readonly client;
+  private readonly requireBasePath;
+  private _readOnly;
+  private _basePathMissing;
+  get readOnly(): boolean | undefined;
+  /**
+   * @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: DatabricksWorkspaceFilesystemOptions);
+  /** Resolve and sandbox a workspace-relative path under {@link basePath}. */
+  private resolvePath;
+  /** Map a Databricks absolute path back to the workspace namespace. */
+  private workspacePath;
+  /** Throw when the filesystem is read-only. */
+  private assertWritable;
+  /** 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}.
+   */
+  private resolveBasePathStatus;
+  /** Delegate to {@link emptyFilesystem} when the optional 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.
+   *
+   * @returns `true` when the probe write (and cleanup) succeeded.
+   */
+  private probeReadOnly;
+  destroy(): Promise<void>;
+  /** Probe that `absolutePath` exists (file or directory metadata). */
+  private assertAbsoluteReadable;
+  /** Read the full contents of `absolutePath` from the matching backend. */
+  private readAbsolute;
+  /** Write `buffer` to `absolutePath` on the matching backend. */
+  private writeAbsolute;
+  /** Upload a buffer to a Unity Catalog Files API path. */
+  private uploadUcFile;
+  /** Delete a single file at `absolutePath` (non-recursive). */
+  private deleteAbsoluteFile;
+  /**
+   * Delete a file or directory at `absolutePath`.
+   *
+   * DBFS and workspace APIs accept `recursive`; UC volumes recurse manually.
+   */
+  private deleteAbsolutePath;
+  /** Create `absolutePath` and any missing parents on the matching backend. */
+  private mkdirAbsolute;
+  private readDbfsFile;
+  private readWorkspaceFile;
+  private writeDbfsFile;
+  private writeWorkspaceFile;
+  getInfo(): FilesystemInfo<{
+    basePath: string;
+  }>;
+  getInstructions(): string;
+  /** Map a workspace-relative path to the backing Databricks absolute path. */
+  resolveAbsolutePath(inputPath: string): string | undefined;
+  /** Read file contents from the workspace namespace. */
+  readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer>;
+  /** Write file contents into the workspace namespace. */
+  writeFile(inputPath: string, content: FileContent, options?: WriteOptions): Promise<void>;
+  /** Append to an existing file, creating it when missing. */
+  appendFile(inputPath: string, content: FileContent): Promise<void>;
+  /** Delete a file in the workspace namespace. */
+  deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
+  /** Copy a file within the workspace namespace. */
+  copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+  /** Move or rename a file within the workspace namespace. */
+  moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+  /** Create a directory in the workspace namespace. */
+  mkdir(inputPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  /** Remove a directory from the workspace namespace. */
+  rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
+  /**
+   * Recursively delete a Unity Catalog directory tree.
+   *
+   * DBFS and workspace trees use native recursive delete via
+   * {@link deleteAbsolutePath} instead.
+   */
+  private deleteUcDirectoryRecursive;
+  /** List entries in a workspace directory. */
+  readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]>;
+  private readDirectoryRecursive;
+  private listAbsoluteDirectory;
+  /** Apply Mastra list filters (`extension`, etc.) to directory entries. */
+  private filterEntries;
+  /** Return whether `inputPath` exists in the workspace namespace. */
+  exists(inputPath: string): Promise<boolean>;
+  /** Return file or directory metadata for `inputPath`. */
+  stat(inputPath: string): Promise<FileStat>;
+  /**
+   * Stat a Unity Catalog path by probing file metadata first, then
+   * directory metadata.
+   */
+  private statUcAbsolute;
+}
+/**
+ * Read-only in-memory {@link WorkspaceFilesystem} with a single empty root.
+ * Use {@link emptyFilesystem} rather than constructing directly.
+ */
+declare class EmptyFilesystem extends MastraFilesystem {
+  readonly id = "empty-fs";
+  readonly name = "EmptyFilesystem";
+  readonly provider = "empty";
+  readonly readOnly = true;
+  status: ProviderStatus;
+  constructor();
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  getInfo(): FilesystemInfo;
+  getInstructions(): string;
+  private rootStat;
+  private assertWritable;
+  readFile(inputPath: string, _options?: ReadOptions): Promise<string | Buffer>;
+  writeFile(_inputPath: string, _content: FileContent, _options?: WriteOptions): Promise<void>;
+  appendFile(_inputPath: string, _content: FileContent): Promise<void>;
+  deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
+  copyFile(src: string, _dest: string, _options?: CopyOptions): Promise<void>;
+  moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+  mkdir(_inputPath: string, _options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
+  readdir(inputPath: string, _options?: ListOptions): Promise<FileEntry[]>;
+  exists(inputPath: string): Promise<boolean>;
+  stat(inputPath: string): Promise<FileStat>;
+}
+/** Memoized singleton empty read-only filesystem for no-op mounts. */
+declare const emptyFilesystem: () => EmptyFilesystem;
+//#endregion
 //#region packages/appkit-mastra/src/mcp.d.ts
 /**
  * A built MCP server plus the request paths it answers on, relative to
@@ -1113,7 +1366,7 @@ declare class MastraServer$1 extends MastraServer {
   private feedbackEnabled;
   constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServer>);
   registerAuthMiddleware(): void;
-  configureRequestContextUser(requestContext: RequestContext): void;
+  configureRequestContextUser(requestContext: RequestContext): Promise<void>;
   /**
    * Stamp a per-request id and echo it on the response so an upstream
    * proxy / curl client / browser-side log line can pair its view of
@@ -1126,6 +1379,11 @@ declare class MastraServer$1 extends MastraServer {
    * response header so dev tools can copy it from either side.
    */
   configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  /**
+   * Stamp OAuth scopes from the forwarded access token on
+   * {@link MASTRA_SCOPES_KEY} for workspace mount gating.
+   */
+  configureRequestContextScopes(req: express.Request, requestContext: RequestContext): void;
   /**
    * Stamp the turn's MLflow trace id on the response so the chat client
    * can attach thumbs / comment feedback to it later. MLflow derives
@@ -1417,4 +1675,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, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_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, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };
+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 };