@dbx-tools/appkit-mastra 0.1.12 → 0.1.14

package/src/workspaces.ts

@@ -0,0 +1,346 @@
+/**
+ * Mastra workspace factory for Databricks Apps.
+ *
+ * Builds a per-request {@link Workspace} whose filesystem is a
+ * {@link CompositeFilesystem} over Databricks paths resolved from the
+ * OBO client on {@link MASTRA_USER_KEY}. Optional mount resolver
+ * contributions merge extra filesystems and skill scan roots; built-in
+ * Assistant skill trees are toggled with `assistantSkills` (on by default).
+ */
+
+import type { WorkspaceClient } from "@databricks/sdk-experimental";
+import type { RequestContext } from "@mastra/core/request-context";
+import {
+  CompositeFilesystem,
+  Workspace,
+  type SkillsContext,
+  type SkillsResolver,
+  type WorkspaceFilesystem,
+} from "@mastra/core/workspace";
+
+import { MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, type User } from "./config";
+import { DatabricksWorkspaceFilesystem, emptyFilesystem } from "./filesystems";
+import { log, string, token } from "@dbx-tools/shared-core";
+
+/* ------------------------------ constants ------------------------------ */
+
+/** 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", "workspace.workspace", "all-apis"] as const;
+
+const logger = log.logger("mastra/workspaces");
+
+/* -------------------------------- types -------------------------------- */
+
+/** 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}. */
+export 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: [],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace {
+  const { id, name } = resolveWorkspaceIdentity(options);
+  const resolvers = buildMountResolvers(options);
+  const skills =
+    options.skills ?? (resolvers.length > 0 ? buildWorkspaceSkillsResolver(resolvers) : undefined);
+  const checkSkillFileMtime = options.checkSkillFileMtime ?? options.assistantSkills !== false;
+  const bm25 = options.bm25 !== false;
+  logger.debug("workspace:create", {
+    id,
+    name,
+    resolverCount: resolvers.length,
+    assistantSkills: options.assistantSkills !== false,
+    customMountResolvers: options.mounts?.length ?? 0,
+    customSkillsResolver: Boolean(options.skills),
+    checkSkillFileMtime,
+    bm25,
+  });
+
+  return new Workspace({
+    id,
+    name,
+    filesystem: (context) => resolveWorkspaceFilesystem(resolvers, context),
+    ...(skills
+      ? {
+          skills,
+          checkSkillFileMtime,
+        }
+      : {}),
+    bm25,
+  });
+}
+
+/* ---------------------------- private helpers ---------------------------- */
+
+/**
+ * Map an OBO user email to their Assistant skills directory in the
+ * workspace namespace.
+ */
+function userAssistantSkillsPath(userEmail: string): string {
+  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: RequestContext | undefined): boolean {
+  return token.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: WorkspaceMountContext): WorkspaceMountContribution {
+  const mounts: Record<string, DatabricksWorkspaceFilesystem> = {};
+  const requestContext = context.requestContext;
+
+  if (!shouldMountAssistantSkills(requestContext)) {
+    logger.debug("assistant-skills:skipped", {
+      reason: !requestContext ? "no-request-context" : "missing-workspace-scope",
+      nodeEnv: process.env.NODE_ENV,
+      scopes: context.requestContext?.get(MASTRA_SCOPES_KEY),
+    });
+    return { mounts, skillPaths: [] };
+  }
+
+  const user = requestContext!.get(MASTRA_USER_KEY) as User | undefined;
+  const client = user?.executionContext.client;
+  if (!client) {
+    logger.debug("assistant-skills:skipped", {
+      reason: "missing-obo-client",
+      userId: user?.id,
+    });
+    return { mounts, skillPaths: [] };
+  }
+
+  mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = databricksFilesystem(
+    client,
+    ASSISTANT_SHARED_SKILLS_PATH,
+  );
+
+  const email = resolveScopedEmail(requestContext);
+  if (email) {
+    mounts[ASSISTANT_USER_SKILLS_MOUNT] = databricksFilesystem(
+      client,
+      userAssistantSkillsPath(email),
+      false,
+    );
+  }
+
+  logger.debug("assistant-skills:mounted", {
+    sharedPath: ASSISTANT_SHARED_SKILLS_PATH,
+    sharedMount: ASSISTANT_WORKSPACE_SKILLS_MOUNT,
+    userMount: email ? ASSISTANT_USER_SKILLS_MOUNT : undefined,
+    userPath: email ? userAssistantSkillsPath(email) : undefined,
+    mountKeys: Object.keys(mounts),
+  });
+
+  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: CreateWorkspaceOptions): {
+  id: string;
+  name: string;
+} {
+  let id = options.id;
+  let name = options.name;
+  if (!id) {
+    id = name ? string.toSlug(name) : "workspace";
+  }
+  if (!name) {
+    name = Array.from(string.tokenize(id)).join(" ");
+  }
+  return { id, name };
+}
+
+/** Collect built-in and caller-supplied mount resolvers for one workspace. */
+function buildMountResolvers(options: CreateWorkspaceOptions): WorkspaceMountResolver[] {
+  const resolvers: WorkspaceMountResolver[] = [];
+  const { assistantSkills = true, mounts } = options;
+  if (assistantSkills) {
+    resolvers.push(resolveAssistantSkillsMounts);
+  }
+  if (mounts?.length) {
+    resolvers.push(...mounts);
+  }
+  logger.debug("mounts:resolvers", {
+    assistantSkills,
+    builtInResolver: assistantSkills,
+    customResolverCount: mounts?.length ?? 0,
+    totalResolverCount: resolvers.length,
+  });
+  return resolvers;
+}
+
+/**
+ * Gate Assistant skill mounts on request context.
+ *
+ * Always allows mounts in development; in other environments requires
+ * {@link hasWorkspaceFileScope}.
+ */
+function shouldMountAssistantSkills(
+  requestContext: RequestContext | undefined,
+): requestContext is 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: RequestContext | undefined): string | undefined {
+  const email = requestContext?.get(MASTRA_USER_EMAIL_KEY) as string | undefined;
+  return email?.trim() || undefined;
+}
+
+/** Construct a read-only {@link DatabricksWorkspaceFilesystem} for `basePath`. */
+function databricksFilesystem(
+  client: WorkspaceClient,
+  basePath: string,
+  readOnly: boolean = true,
+): DatabricksWorkspaceFilesystem {
+  return new DatabricksWorkspaceFilesystem({
+    client,
+    basePath,
+    readOnly,
+  });
+}
+
+/**
+ * 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: WorkspaceMountResolver[],
+  context: WorkspaceMountContext,
+): Promise<WorkspaceMountContribution> {
+  const mounts: Record<string, WorkspaceFilesystem> = {};
+  const skillPaths: string[] = [];
+
+  for (const [index, resolver] of resolvers.entries()) {
+    const contribution = await resolver(context);
+    logger.debug("mounts:resolver", {
+      index,
+      mountKeys: Object.keys(contribution.mounts),
+      skillPaths: contribution.skillPaths ?? [],
+    });
+    Object.assign(mounts, contribution.mounts);
+    if (contribution.skillPaths?.length) {
+      skillPaths.push(...contribution.skillPaths);
+    }
+  }
+
+  logger.debug("mounts:merged", {
+    mountKeys: Object.keys(mounts),
+    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: WorkspaceMountResolver[],
+  context: WorkspaceMountContext,
+): Promise<WorkspaceFilesystem> {
+  const { mounts } = await resolveWorkspaceContribution(resolvers, context);
+  const mountKeys = Object.keys(mounts);
+  if (mountKeys.length === 0) {
+    logger.debug("filesystem:empty", {
+      hasRequestContext: Boolean(context.requestContext),
+    });
+    return emptyFilesystem();
+  }
+  logger.debug("filesystem:composite", { mountKeys });
+  return new CompositeFilesystem({ mounts });
+}
+
+/**
+ * Build the dynamic {@link SkillsResolver} that collects `skillPaths` from
+ * every mount resolver on each request.
+ */
+function buildWorkspaceSkillsResolver(resolvers: WorkspaceMountResolver[]): SkillsResolver {
+  return async (context: SkillsContext) => {
+    const { skillPaths } = await resolveWorkspaceContribution(resolvers, context);
+    logger.debug("skills:resolved", { skillPaths });
+    return skillPaths ?? [];
+  };
+}

package/src/writer.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared helper for publishing events through Mastra's
+ * `ctx.writer`. Centralizes the "the downstream stream may already
+ * be closed, don't take the whole tool down" pattern that the
+ * Genie agent and chart tool both need.
+ *
+ * Failures are logged at `warn` (a persistently-closed writer is
+ * the most likely culprit when events go missing client-side) but
+ * swallowed so a cancelled request or a client that navigated
+ * away can't crash a tool mid-flight.
+ */
+
+import type { MastraWriter } from "@dbx-tools/shared-mastra";
+import { error, log } from "@dbx-tools/shared-core";
+
+/**
+ * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * caught errors are logged via `log.warn("writer:error", ...)`
+ * along with any caller-supplied `context` fields (e.g. a
+ * `chartId` or `messageId`) so the warning is greppable per
+ * resource.
+ *
+ * Returns when the write resolves or rejects; never throws.
+ */
+export async function safeWrite(
+  log: log.Logger,
+  writer: MastraWriter | undefined,
+  chunk: unknown,
+  context: Record<string, unknown> = {},
+): Promise<void> {
+  if (!writer) {
+    log.debug("writer:no-writer", context);
+    return;
+  }
+  try {
+    await writer.write(chunk);
+    log.debug("writer:ok", context);
+  } catch (err) {
+    log.warn("writer:error", {
+      ...context,
+      error: error.errorMessage(err),
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/dist/index.d.ts

@@ -1,20 +0,0 @@
-/**
- * AppKit Mastra integration: {@link MastraPlugin} / {@link mastra},
- * plugin config types, agent registration helpers, Genie tool
- * builders, and dynamic Model Serving endpoint resolution.
- *
- * Client-side consumers should import URL helpers and the
- * {@link MastraClientConfig} type from `@dbx-tools/appkit-mastra-shared`
- * instead - that package is pure (no pg / fastembed / Mastra deps) and
- * is the right surface for browser bundles and `usePluginClientConfig`
- * consumers.
- */
-export * from "./src/plugin.js";
-export * from "@dbx-tools/appkit-mastra-shared";
-export * from "./src/config.js";
-export * from "./src/agents.js";
-export * from "./src/chart.js";
-export * from "./src/genie.js";
-export * from "./src/tools/email.js";
-export { clearServingEndpointsCache, extractModelOverride, listServingEndpoints, MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, resolveModelId, type ResolvedModel, type ResolveModelOptions, type ServingEndpointSummary, } from "./src/serving.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, modelForTier, modelsForTier, ModelTier, } from "./src/model.js";

package/dist/index.js

@@ -1,20 +0,0 @@
-/**
- * AppKit Mastra integration: {@link MastraPlugin} / {@link mastra},
- * plugin config types, agent registration helpers, Genie tool
- * builders, and dynamic Model Serving endpoint resolution.
- *
- * Client-side consumers should import URL helpers and the
- * {@link MastraClientConfig} type from `@dbx-tools/appkit-mastra-shared`
- * instead - that package is pure (no pg / fastembed / Mastra deps) and
- * is the right surface for browser bundles and `usePluginClientConfig`
- * consumers.
- */
-export * from "./src/plugin.js";
-export * from "@dbx-tools/appkit-mastra-shared";
-export * from "./src/config.js";
-export * from "./src/agents.js";
-export * from "./src/chart.js";
-export * from "./src/genie.js";
-export * from "./src/tools/email.js";
-export { clearServingEndpointsCache, extractModelOverride, listServingEndpoints, MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, resolveModelId, } from "./src/serving.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, modelForTier, modelsForTier, ModelTier, } from "./src/model.js";