@dbx-tools/appkit-mastra 0.6.48 → 0.6.50

package/package.json

@@ -31,18 +31,18 @@
   "dependencies": {
     "@databricks/appkit": "^0.43.0",
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/appkit": "0.6.48",
-    "@dbx-tools/core": "0.6.48",
-    "@dbx-tools/databricks": "0.6.48",
-    "@dbx-tools/fs": "0.6.48",
-    "@dbx-tools/genie": "0.6.48",
-    "@dbx-tools/model": "0.6.48",
-    "@dbx-tools/path": "0.6.48",
-    "@dbx-tools/shared-core": "0.6.48",
-    "@dbx-tools/shared-fs": "0.6.48",
-    "@dbx-tools/shared-genie": "0.6.48",
-    "@dbx-tools/shared-mastra": "0.6.48",
-    "@dbx-tools/shared-model": "0.6.48",
+    "@dbx-tools/appkit": "0.6.50",
+    "@dbx-tools/core": "0.6.50",
+    "@dbx-tools/databricks": "0.6.50",
+    "@dbx-tools/fs": "0.6.50",
+    "@dbx-tools/genie": "0.6.50",
+    "@dbx-tools/model": "0.6.50",
+    "@dbx-tools/path": "0.6.50",
+    "@dbx-tools/shared-core": "0.6.50",
+    "@dbx-tools/shared-fs": "0.6.50",
+    "@dbx-tools/shared-genie": "0.6.50",
+    "@dbx-tools/shared-mastra": "0.6.50",
+    "@dbx-tools/shared-model": "0.6.50",
     "@mastra/ai-sdk": "^1.6.0",
     "@mastra/core": "^1.47.0",
     "@mastra/express": "^1.4.2",
@@ -71,7 +71,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.6.48",
+  "version": "0.6.50",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {

package/src/config.ts

@@ -24,7 +24,7 @@ import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
 import type { MastraAgentDefinition, MastraTools } from "./agents.ts";
 import type { GenieSpacesConfig } from "./genie.ts";
-import type { MastraIdentityMode } from "./identity.ts";
+import { IDENTITY_MODES, type MastraIdentityMode } from "./identity.ts";
 import type { RemoteSkillsOption } from "./remote-skills.ts";
 
 /**
@@ -526,8 +526,13 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * - `"service-principal"`: always the app service principal. Needs no OBO
    *   scopes and works for any caller who can open the app, at the cost of
    *   per-user attribution in Genie / Unity Catalog.
+   * - `"auto"`: OBO when the request carries an OBO token, the service principal
+   *   when it does not. For an app serving BOTH the platform front door and a
+   *   door that has no token to forward - a `@dbx-tools/cli-tunnel` gate, a
+   *   Teams channel - where AppKit's `asUser` would otherwise throw
+   *   `AuthenticationError` outside `NODE_ENV=development`.
    *
-   * `"service-principal"` changes only the Databricks CREDENTIAL. Memory
+   * The service-principal path changes only the Databricks CREDENTIAL. Memory
    * threads, the per-user cache namespace, and trace metadata still key off the
    * forwarded user, so callers sharing the service principal's data access keep
    * separate conversations and cannot read each other's threads or charts.
@@ -536,6 +541,11 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * ```ts
    * mastra({ genieIdentity: "service-principal", genieSpaces: { default: spaceId } });
    * ```
+   *
+   * @example One app behind both the front door and a public tunnel
+   * ```ts
+   * mastra({ genieIdentity: "auto", genieSpaces: { default: spaceId } });
+   * ```
    */
   genieIdentity?: MastraIdentityMode;
   /**
@@ -691,9 +701,11 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     },
     genieIdentity: {
       type: "string",
-      enum: ["user", "service-principal"],
+      // Derived from the resolver's own list, so a mode can never be accepted at
+      // runtime while the published schema (and the UI built from it) omits it.
+      enum: [...IDENTITY_MODES],
       description:
-        'Which Databricks identity the agents\' workspace calls (serving catalogue, Genie, statement execution) run as. "user" (default) is always OBO, so callers must be workspace members; "service-principal" always uses the app service principal, so any caller who can open the app works, at the cost of per-user attribution. Falls back to MASTRA_GENIE_IDENTITY.',
+        'Which Databricks identity the agents\' workspace calls (serving catalogue, Genie, statement execution) run as. "user" (default) is always OBO, so callers must be workspace members; "service-principal" always uses the app service principal, so any caller who can open the app works, at the cost of per-user attribution; "auto" uses OBO when the request carries an OBO token and the service principal when it does not, for an app that also serves a tunnel or webhook door. Falls back to MASTRA_GENIE_IDENTITY.',
     },
     apiAccess: {
       type: "string",

package/src/identity.ts

@@ -7,7 +7,14 @@
  * client on the ambient AppKit execution context. That context is user-scoped
  * (OBO) whenever the plugin enters `asUser(req)` and the app's service principal
  * otherwise, so ONE decision - do we enter that scope for this request - moves
- * every call site together. This module owns that decision.
+ * every call site together.
+ *
+ * The decision itself is NOT Mastra-specific (the Teams messaging endpoint and
+ * the tunnel gate face it too), so it lives in `@dbx-tools/appkit`'s `identity`
+ * module - which also documents the measured AppKit behavior that makes `"auto"`
+ * necessary. This module is the Mastra-facing binding: the plugin's own config
+ * field and env var, re-exporting the shared vocabulary so a consumer importing
+ * `@dbx-tools/appkit-mastra` needs no second import.
  *
  * Why the option exists: OBO requires the caller to be a member of the
  * WORKSPACE, not merely of the Databricks account. An app shared with an
@@ -19,7 +26,7 @@
  * / warehouse / serving / Unity Catalog grants the app was deployed with, and
  * works for every caller.
  *
- * The two modes, from `config.genieIdentity` (env: {@link IDENTITY_ENV}):
+ * The modes, from `config.genieIdentity` (env: {@link IDENTITY_ENV}):
  *
  *   - `"user"` (default): always OBO. Calls are attributed per user and Genie /
  *     Unity Catalog row filters apply per user. Correct whenever every caller is
@@ -28,9 +35,13 @@
  *   - `"service-principal"`: always the app service principal. Needs no OBO
  *     scopes and works for any caller who can open the app, at the cost of
  *     per-user attribution in Genie / Unity Catalog.
+ *   - `"auto"`: OBO when the request carries an OBO token, the service principal
+ *     when it does not. The mode for an app that serves BOTH the platform front
+ *     door and a door with no OBO token to forward (a `@dbx-tools/cli-tunnel`
+ *     gate, a Teams channel), since a single container serves both at once.
  *
- * What `"service-principal"` does NOT change is WHO the turn belongs to. The
- * memory thread's `resourceId`, the per-user cache namespace, and the user
+ * What the service-principal path does NOT change is WHO the turn belongs to.
+ * The memory thread's `resourceId`, the per-user cache namespace, and the user
  * metadata on traces still come from the forwarded request headers, so two
  * account users sharing the service principal's data access still get separate
  * conversations and cannot read each other's threads or cached charts. Only the
@@ -39,72 +50,50 @@
  * @module
  */
 
-import { ConfigurationError } from "@databricks/appkit";
-import { string } from "@dbx-tools/shared-core";
-import type express from "express";
+import { identity } from "@dbx-tools/appkit";
 
 /** Identity a chat turn's Databricks calls run as. See the module docs. */
-export type MastraIdentityMode = "user" | "service-principal";
+export type MastraIdentityMode = identity.IdentityMode;
 
 /** Environment fallback for `config.genieIdentity`. */
 export const IDENTITY_ENV = "MASTRA_GENIE_IDENTITY";
 
 /** Every accepted {@link MastraIdentityMode}. */
-export const IDENTITY_MODES: readonly MastraIdentityMode[] = ["user", "service-principal"];
+export const IDENTITY_MODES = identity.IDENTITY_MODES;
 
 /**
  * Default mode. `"user"` keeps OBO the only identity unless an app opts in, so
  * adopting this option can never silently widen an existing app's data access.
  */
-export const DEFAULT_IDENTITY_MODE: MastraIdentityMode = "user";
+export const DEFAULT_IDENTITY_MODE = identity.DEFAULT_IDENTITY_MODE;
+
+/** Header Databricks Apps forward the signed-in user's id on. */
+export const USER_ID_HEADER = identity.USER_ID_HEADER;
+
+/** Header Databricks Apps forward the signed-in user's email on. */
+export const USER_EMAIL_HEADER = identity.USER_EMAIL_HEADER;
 
 /**
  * Resolve the configured mode: explicit plugin config, then {@link IDENTITY_ENV},
- * then {@link DEFAULT_IDENTITY_MODE}.
- *
- * An unrecognized value throws rather than falling back, since falling back
- * would silently keep serving OBO - and the 500s it produces - to exactly the
- * callers the option was set to accommodate.
+ * then {@link DEFAULT_IDENTITY_MODE}. An unrecognized value throws.
  */
 export function resolveIdentityMode(configured: string | undefined): MastraIdentityMode {
-  const raw = string.trimToNull(configured) ?? string.trimToNull(process.env[IDENTITY_ENV]);
-  if (raw === null) return DEFAULT_IDENTITY_MODE;
-  const mode = raw.toLowerCase() as MastraIdentityMode;
-  if (!IDENTITY_MODES.includes(mode)) {
-    throw new ConfigurationError(
-      `genieIdentity must be one of ${IDENTITY_MODES.join(" | ")} (env: ${IDENTITY_ENV})`,
-      { context: { field: "genieIdentity", envVar: IDENTITY_ENV, received: raw } },
-    );
-  }
-  return mode;
+  return identity.resolveIdentityMode(configured, IDENTITY_ENV, "genieIdentity");
 }
 
-/** Header Databricks Apps forward the signed-in user's id on. */
-export const USER_ID_HEADER = "x-forwarded-user";
-
-/** Header Databricks Apps forward the signed-in user's email on. */
-export const USER_EMAIL_HEADER = "x-forwarded-email";
-
 /**
  * The forwarded user id on `req`, or `undefined`. Used to attribute a turn to
- * the real caller in `service-principal` mode, where the Databricks client is
- * the app SP but memory / cache / traces must still key off the user.
+ * the real caller when the Databricks client is the app SP but memory / cache /
+ * traces must still key off the user.
  */
-export function requestUserId(req: express.Request): string | undefined {
-  return string.trimToNull(req.header(USER_ID_HEADER)) ?? undefined;
-}
+export const requestUserId = identity.requestUserId;
 
 /** The forwarded user email on `req`, or `undefined`. */
-export function requestUserEmail(req: express.Request): string | undefined {
-  return string.trimToNull(req.header(USER_EMAIL_HEADER)) ?? undefined;
-}
+export const requestUserEmail = identity.requestUserEmail;
 
 /**
  * Whether this request should run its Databricks calls as the app service
- * principal rather than OBO. `"service-principal"` always does; `"user"` never
- * does. The request is accepted for symmetry and to leave room for
- * request-scoped policy later; it is unused today.
+ * principal rather than OBO - `"service-principal"` always, `"user"` never, and
+ * `"auto"` only when the request carries no OBO token for AppKit to use.
  */
-export function useServicePrincipal(mode: MastraIdentityMode, _req?: express.Request): boolean {
-  return mode === "service-principal";
-}
+export const useServicePrincipal = identity.useServicePrincipal;

package/src/remote-skills.ts

@@ -40,9 +40,12 @@
  * action writes to), so provisioned skills persist across restarts and are
  * discovered by the built-in Assistant-skills mount. Pass `userEmail` (or an
  * explicit `databricksBasePath`) to target `/Users/<email>/.assistant/skills`
- * instead. When no Databricks client is resolvable at startup, the tree is
- * written under {@link localFS.tmpFS} and returned as an extra local skill path
- * for the current process.
+ * instead. When no Databricks client is resolvable at startup - or the resolved
+ * identity cannot WRITE the destination, which is the normal case for a
+ * Databricks App service principal against the admin-owned shared tree (see
+ * {@link openWritableWorkspace}) - the tree is written under
+ * {@link localFS.tmpFS} and returned as an extra local skill path for the
+ * current process. Storage location degrades; the skills themselves do not.
  *
  * @module
  */
@@ -413,25 +416,20 @@ export async function provisionRemoteSkills(
 
   const failDefault = options.failOnError !== false;
   const client = options.client ?? appkit.tryGetExecutionContext()?.client;
-  const databricksBasePath = resolveDatabricksBasePath(options, client);
-  const destination = databricksBasePath
-    ? new DatabricksFileSystem({
-        client: client as WorkspaceClient,
-        root: databricksBasePath,
-        readOnly: false,
-        createRoot: true,
-      })
+  // Probed rather than assumed: an identity that cannot write the workspace
+  // tree falls back to the local one instead of failing startup. The probe also
+  // creates the root, which the first cache READ needs - `copySkillDirs` would
+  // otherwise be the first thing to create it, which is too late.
+  const requestedBasePath = resolveDatabricksBasePath(options, client);
+  const destination = requestedBasePath
+    ? await openWritableWorkspace(requestedBasePath, client as WorkspaceClient)
     : undefined;
+  const databricksBasePath = destination ? requestedBasePath : undefined;
 
   const localSkillPaths: string[] = [];
   const skillNames: string[] = [];
   let staging: LocalFileSystem | undefined;
 
-  // The destination roots the shared metadata document, so it has to exist
-  // before the first cache READ - `copySkillDirs` would otherwise be the first
-  // thing to create it, which is too late.
-  if (destination) await destination.init();
-
   try {
     const sources = Array.isArray(options.sources) ? options.sources : [options.sources];
     for (const entry of sources) {
@@ -508,6 +506,49 @@ export async function provisionRemoteSkills(
   return { localSkillPaths, databricksBasePath, skillNames };
 }
 
+/** Probe file {@link openWritableWorkspace} writes and removes. */
+const WRITE_PROBE_FILE = ".dbx-tools-write-probe";
+
+/**
+ * Open the Databricks skills destination, or `undefined` when this identity
+ * cannot write there.
+ *
+ * The default destination (`/Workspace/.assistant/skills`) is commonly
+ * admins-only, and an app service principal is not an admin - so a Databricks
+ * App writing there fails with `RESOURCE_DOES_NOT_EXIST`, which is how the
+ * workspace API reports a path the caller is not allowed to see. That is a fact
+ * about WHERE the tree is stored, not about whether the skills are usable, so it
+ * degrades to the local tree (handed to Mastra as an extra scan path) rather
+ * than taking app startup down over bookkeeping location.
+ *
+ * The probe is a real write: `mkdirs` succeeds on an existing directory even for
+ * an identity that cannot write into it, so init alone proves nothing. Removing
+ * the probe file is best-effort - a failed cleanup must not decide writability.
+ */
+async function openWritableWorkspace(
+  basePath: string,
+  client: WorkspaceClient,
+): Promise<DatabricksFileSystem | undefined> {
+  const fs = new DatabricksFileSystem({
+    client,
+    root: basePath,
+    readOnly: false,
+    createRoot: true,
+  });
+  try {
+    await fs.init();
+    await fs.writeFile(WRITE_PROBE_FILE, new Date().toISOString(), { overwrite: true });
+  } catch (err) {
+    logger.warn("destination:unwritable", {
+      destination: basePath,
+      error: error.errorMessage(err),
+    });
+    return undefined;
+  }
+  await fs.deleteFile(WRITE_PROBE_FILE, { force: true }).catch(() => undefined);
+  return fs;
+}
+
 /** Resolve the Databricks Assistant skills destination, or `undefined` for local temp. */
 function resolveDatabricksBasePath(
   options: ProvisionRemoteSkillsOptions,