@dbx-tools/appkit-mastra 0.6.8 → 0.6.10

package/package.json

@@ -32,22 +32,25 @@
     "express": "^5.1.0",
     "pg": "^8.22.0",
     "zod": "4.3.6",
-    "@dbx-tools/model": "0.6.8",
-    "@dbx-tools/appkit": "0.6.8",
-    "@dbx-tools/genie": "0.6.8",
-    "@dbx-tools/core": "0.6.8",
-    "@dbx-tools/path": "0.6.8",
-    "@dbx-tools/shared-core": "0.6.8",
-    "@dbx-tools/shared-genie": "0.6.8",
-    "@dbx-tools/shared-mastra": "0.6.8",
-    "@dbx-tools/shared-model": "0.6.8"
+    "@dbx-tools/appkit": "0.6.10",
+    "@dbx-tools/databricks": "0.6.10",
+    "@dbx-tools/genie": "0.6.10",
+    "@dbx-tools/fs": "0.6.10",
+    "@dbx-tools/model": "0.6.10",
+    "@dbx-tools/core": "0.6.10",
+    "@dbx-tools/path": "0.6.10",
+    "@dbx-tools/shared-core": "0.6.10",
+    "@dbx-tools/shared-fs": "0.6.10",
+    "@dbx-tools/shared-model": "0.6.10",
+    "@dbx-tools/shared-genie": "0.6.10",
+    "@dbx-tools/shared-mastra": "0.6.10"
   },
   "main": "./lib/index.js",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.8",
+  "version": "0.6.10",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {

package/src/config.ts

@@ -23,6 +23,7 @@ import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/reque
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
 import type { MastraAgentDefinition, MastraTools } from "./agents.ts";
+import type { DatabricksAIToolsOption } from "./databricks-aitools.ts";
 import type { GenieSpacesConfig } from "./genie.ts";
 import type { MastraIdentityMode } from "./identity.ts";
 import type { RemoteSkillsOption } from "./remote-skills.ts";
@@ -580,6 +581,27 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * ```
    */
   remoteSkills?: RemoteSkillsOption;
+
+  /**
+   * Fold Databricks AI Tools skills (`databricks aitools`) into every
+   * default-workspace agent as extra local skill scan paths.
+   *
+   * `false` (default) off; `"auto"` runs the `databricks` CLI when it's
+   * installed and logs-and-continues when it isn't (never fails startup);
+   * `true` requires the CLI and fails startup otherwise. Pass an options bag to
+   * select `skills`, include `experimental` skills, or set an explicit `path`.
+   *
+   * Runs `databricks aitools install --path <dir>` to materialize a resolved,
+   * agent-agnostic set (`<name>/SKILL.md` trees) into a temp dir the agents
+   * then scan. The CLI is the source of truth.
+   *
+   * @example
+   * ```ts
+   * mastra({ databricksAITools: "auto" });
+   * mastra({ databricksAITools: { skills: ["databricks-core", "databricks-jobs"] } });
+   * ```
+   */
+  databricksAITools?: DatabricksAIToolsOption;
 }
 
 /**
@@ -603,6 +625,11 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
       description:
         "Remote Agent-Skill sources provisioned at startup (GitHub owner/repo, git/GitLab URL, or a direct SKILL.md/archive URL). Prefers the optional `skills` npm CLI, else a direct fetch; fails startup on error unless failOnError:false. Written to the Databricks user Assistant skills folder, or a local temp dir when no workspace is writable.",
     },
+    databricksAITools: {
+      type: ["boolean", "string", "object"],
+      description:
+        'Fold Databricks AI Tools skills (databricks aitools) into agents as extra local skill paths. false (default) off; "auto" runs the databricks CLI when installed and logs-and-continues otherwise; true requires the CLI and fails startup otherwise. An object selects skills, experimental, or path.',
+    },
     storage: {
       type: ["boolean", "object"],
       description:

package/src/databricks-aitools.ts

@@ -0,0 +1,216 @@
+/**
+ * Startup provisioning of Databricks AI Tools skills for a Mastra workspace.
+ *
+ * Databricks AI Tools (`databricks aitools`) are Databricks-owned Agent-Skill
+ * (`SKILL.md`) trees installed and kept up to date through the Databricks CLI.
+ * {@link provisionDatabricksAITools} shells out to the CLI
+ * (`databricks aitools install --path <dir>`) to materialize a resolved,
+ * agent-agnostic skill set into a directory, then hands it to Mastra as an
+ * extra LOCAL skill scan path - so an agent gets first-class Databricks skills
+ * without anyone hand-copying `SKILL.md` files. It never reimplements the CLI's
+ * sourcing; the CLI is the source of truth.
+ *
+ * The option is `false | true | "auto" | DatabricksAIToolsOptions`:
+ *
+ * - `false` (default) - off.
+ * - `"auto"` - run the CLI when it's installed; if the `databricks` CLI isn't
+ *   available, log and move on (never fails startup). The "on if the CLI is
+ *   around" default.
+ * - `true` (`"require"`) - require the CLI: fail startup (subject to
+ *   `failOnError`) when it isn't available or produces nothing.
+ * - an options bag for a specific `skills` subset, `experimental` skills, an
+ *   explicit output `path`, or a custom `cli` path.
+ *
+ * @module
+ */
+
+import { existsSync } from "node:fs";
+import { exec } from "@dbx-tools/core";
+import { localFS } from "@dbx-tools/fs";
+import { error, log, string } from "@dbx-tools/shared-core";
+
+const logger = log.logger("mastra/databricks-aitools");
+
+/** The Databricks CLI binary name; resolved on `PATH`. */
+const DATABRICKS_CLI = "databricks";
+
+/** Stable temp directory the CLI's skill tree is rebuilt into each boot. */
+const SKILLS_CACHE_DIR = "databricks-aitools";
+
+/* -------------------------------- types -------------------------------- */
+
+/** How aggressively to enable Databricks AI Tools skills. */
+export type DatabricksAIToolsMode = "auto" | "require";
+
+/** Options for {@link provisionDatabricksAITools}. */
+export interface DatabricksAIToolsOptions {
+  /**
+   * `"auto"` (default) runs the CLI when installed and logs-and-continues when
+   * it isn't; `"require"` fails startup when the CLI can't supply skills.
+   */
+  mode?: DatabricksAIToolsMode;
+  /** Install only these skill names (comma/space list or array). */
+  skills?: string | string[];
+  /** Include experimental skills when the CLI has to fetch. */
+  experimental?: boolean;
+  /**
+   * Explicit directory to materialize skills into with the CLI. Defaults to a
+   * fresh {@link localFS.tmpFS} root.
+   */
+  path?: string;
+  /** Absolute path to the `databricks` CLI. Defaults to `databricks` on PATH. */
+  cli?: string;
+  /**
+   * Fail app startup when required skills can't be provisioned. Defaults to
+   * `true` for `mode: "require"` and `false` for `"auto"`.
+   */
+  failOnError?: boolean;
+}
+
+/** The `databricksAITools` config option: a toggle, `"auto"`, or an options bag. */
+export type DatabricksAIToolsOption = boolean | "auto" | DatabricksAIToolsOptions;
+
+/** What {@link provisionDatabricksAITools} resolved. */
+export interface ProvisionedDatabricksAITools {
+  /** Extra LOCAL skill scan paths to hand Mastra. Empty when disabled/unresolved. */
+  localSkillPaths: string[];
+  /** How the skills were sourced, for logging. */
+  source?: "cli";
+}
+
+/* ------------------------------- helpers ------------------------------- */
+
+/** Normalize the `databricksAITools` option into a flat options bag, or `undefined` when off. */
+export function normalizeDatabricksAIToolsOption(
+  option: DatabricksAIToolsOption | undefined,
+): DatabricksAIToolsOptions | undefined {
+  if (option === undefined || option === false) return undefined;
+  if (option === true) return { mode: "require" };
+  if (option === "auto") return { mode: "auto" };
+  return { mode: option.mode ?? "auto", ...option };
+}
+
+/**
+ * Materialize Databricks AI Tools skills at app startup and return them as
+ * extra local skill scan paths.
+ *
+ * Resolution: reuse the installed global tree when present (no CLI call) unless
+ * `refresh`/`skills`/`path` ask for a fresh CLI materialization; otherwise run
+ * `databricks aitools install --path <dir> --skills-only` when the CLI resolves.
+ * A `"require"` provision that yields nothing fails startup unless
+ * `failOnError: false`.
+ */
+export async function provisionDatabricksAITools(
+  option: DatabricksAIToolsOption | undefined,
+): Promise<ProvisionedDatabricksAITools> {
+  const options = normalizeDatabricksAIToolsOption(option);
+  const empty: ProvisionedDatabricksAITools = { localSkillPaths: [] };
+  if (!options) return empty;
+
+  const mode = options.mode ?? "auto";
+  const failOnError = options.failOnError ?? mode === "require";
+
+  try {
+    // The `databricks` CLI is the source of truth. When it's resolvable, run
+    // `databricks aitools install --path <dir>` to materialize a fresh,
+    // agent-agnostic skill set into a dir Mastra can scan.
+    const cliPath = await resolveCli(options.cli);
+    if (cliPath) {
+      const dir = await materializeViaCli(cliPath, options);
+      if (dir) return { localSkillPaths: [dir], source: "cli" };
+    }
+
+    // CLI not installed (or produced nothing). "auto" logs and moves on;
+    // "require" fails startup unless `failOnError: false`.
+    if (failOnError) {
+      throw new Error(
+        `Databricks AI Tools required but the "${DATABRICKS_CLI}" CLI is not available. Install the Databricks CLI (\`databricks aitools install\`), or set databricksAITools: "auto".`,
+      );
+    }
+    logger.info("databricks CLI not available; skipping AI Tools skills");
+    return empty;
+  } catch (err) {
+    if (failOnError) {
+      throw new Error(
+        `failed to provision Databricks AI Tools skills: ${error.errorMessage(err)}`,
+        { cause: error.toError(err) },
+      );
+    }
+    logger.warn("skipped", { error: error.errorMessage(err) });
+    return empty;
+  }
+}
+
+/** Resolve the `databricks` CLI, returning its invocation path or `undefined`. */
+async function resolveCli(cli: string | undefined): Promise<string | undefined> {
+  const command = string.trimToNull(cli) ?? DATABRICKS_CLI;
+  try {
+    const result = await exec.spawn(command, ["aitools", "version"], {
+      stdout: "capture",
+      stderr: "capture",
+      check: false,
+    });
+    if (result.exitCode === 0) return command;
+  } catch {
+    // CLI absent or `aitools` unsupported - caller falls back / fails.
+  }
+  return undefined;
+}
+
+/**
+ * Run `databricks aitools install --path <dir>` to materialize a resolved,
+ * agent-agnostic skill set into a directory (writes `<name>/SKILL.md` trees,
+ * no agents, no state) Mastra can then scan.
+ */
+async function materializeViaCli(
+  cli: string,
+  options: DatabricksAIToolsOptions,
+): Promise<string | undefined> {
+  const explicit = string.trimToNull(options.path);
+  let dir: string;
+
+  if (explicit) {
+    // An explicit path is the caller's to own - install straight into it.
+    await installSkills(cli, options, explicit);
+    dir = explicit;
+  } else {
+    // The resolved skill set is the same on almost every boot, so rebuild ONE
+    // stable temp tree rather than leaving a fresh scratch dir behind each
+    // time. The CLI writes into a throwaway root that only replaces the stable
+    // one on success, so a failed install keeps the previous skills usable.
+    const stable = await localFS.rebuildFS(SKILLS_CACHE_DIR, (scratch) =>
+      installSkills(cli, options, scratch.root),
+    );
+    dir = stable.root;
+  }
+
+  if (!existsSync(dir)) return undefined;
+  logger.debug("materialized aitools skills via CLI", {
+    path: dir,
+    skills: string.parseList(options.skills),
+  });
+  return dir;
+}
+
+/** Run `databricks aitools install --path <dir>`, failing loudly on a non-zero exit. */
+async function installSkills(
+  cli: string,
+  options: DatabricksAIToolsOptions,
+  dir: string,
+): Promise<void> {
+  const args = ["aitools", "install", "--path", dir];
+  const skills = string.parseList(options.skills);
+  if (skills.length > 0) args.push("--skills", skills.join(","));
+  if (options.experimental) args.push("--experimental");
+
+  const result = await exec.spawn(cli, args, {
+    stdout: "capture",
+    stderr: "capture",
+    check: false,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `databricks aitools install failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+    );
+  }
+}