@dbx-tools/appkit-mastra 0.5.1 → 0.6.0

package/lib/src/identity.js

@@ -0,0 +1,95 @@
+/**
+ * Which Databricks identity a chat turn's workspace calls run as.
+ *
+ * Every Databricks call a turn makes - the `/serving-endpoints` catalogue the
+ * model picker reads, Genie suggestions, `ask_genie`, and the Statement
+ * Execution fetch behind a `[data:<id>]` embed - goes through the workspace
+ * 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.
+ *
+ * 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
+ * account-level group can therefore be opened by someone whose OBO token is
+ * perfectly valid but whose every workspace call fails with `Unauthorized
+ * access to Org: <workspace-id>`, and granting workspace membership is not
+ * always available - a workspace caps membership far below the size of a large
+ * account's user group. The app's own service principal already holds the Genie
+ * / 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}):
+ *
+ *   - `"user"` (default): always OBO. Calls are attributed per user and Genie /
+ *     Unity Catalog row filters apply per user. Correct whenever every caller is
+ *     a workspace member. This is the historical behavior, so the option is
+ *     purely additive - an app that never sets it is unchanged.
+ *   - `"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.
+ *
+ * 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
+ * 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
+ * Databricks credential is shared.
+ *
+ * @module
+ */
+import { ConfigurationError } from "@databricks/appkit";
+import { string } from "@dbx-tools/shared-core";
+/** Environment fallback for `config.genieIdentity`. */
+export const IDENTITY_ENV = "MASTRA_GENIE_IDENTITY";
+/** Every accepted {@link MastraIdentityMode}. */
+export const IDENTITY_MODES = ["user", "service-principal"];
+/**
+ * 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 = "user";
+/**
+ * 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.
+ */
+export function resolveIdentityMode(configured) {
+    const raw = string.trimToNull(configured) ?? string.trimToNull(process.env[IDENTITY_ENV]);
+    if (raw === null)
+        return DEFAULT_IDENTITY_MODE;
+    const mode = raw.toLowerCase();
+    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;
+}
+/** 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.
+ */
+export function requestUserId(req) {
+    return string.trimToNull(req.header(USER_ID_HEADER)) ?? undefined;
+}
+/** The forwarded user email on `req`, or `undefined`. */
+export function requestUserEmail(req) {
+    return string.trimToNull(req.header(USER_EMAIL_HEADER)) ?? undefined;
+}
+/**
+ * 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.
+ */
+export function useServicePrincipal(mode, _req) {
+    return mode === "service-principal";
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaWRlbnRpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaWRlbnRpdHkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVDRztBQUVILE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ3hELE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQU1oRCx1REFBdUQ7QUFDdkQsTUFBTSxDQUFDLE1BQU0sWUFBWSxHQUFHLHVCQUF1QixDQUFDO0FBRXBELGlEQUFpRDtBQUNqRCxNQUFNLENBQUMsTUFBTSxjQUFjLEdBQWtDLENBQUMsTUFBTSxFQUFFLG1CQUFtQixDQUFDLENBQUM7QUFFM0Y7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQXVCLE1BQU0sQ0FBQztBQUVoRTs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxVQUFVLG1CQUFtQixDQUFDLFVBQThCO0lBQ2hFLE1BQU0sR0FBRyxHQUFHLE1BQU0sQ0FBQyxVQUFVLENBQUMsVUFBVSxDQUFDLElBQUksTUFBTSxDQUFDLFVBQVUsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLFlBQVksQ0FBQyxDQUFDLENBQUM7SUFDMUYsSUFBSSxHQUFHLEtBQUssSUFBSTtRQUFFLE9BQU8scUJBQXFCLENBQUM7SUFDL0MsTUFBTSxJQUFJLEdBQUcsR0FBRyxDQUFDLFdBQVcsRUFBd0IsQ0FBQztJQUNyRCxJQUFJLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDO1FBQ25DLE1BQU0sSUFBSSxrQkFBa0IsQ0FDMUIsZ0NBQWdDLGNBQWMsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLFVBQVUsWUFBWSxHQUFHLEVBQ25GLEVBQUUsT0FBTyxFQUFFLEVBQUUsS0FBSyxFQUFFLGVBQWUsRUFBRSxNQUFNLEVBQUUsWUFBWSxFQUFFLFFBQVEsRUFBRSxHQUFHLEVBQUUsRUFBRSxDQUM3RSxDQUFDO0lBQ0osQ0FBQztJQUNELE9BQU8sSUFBSSxDQUFDO0FBQ2QsQ0FBQztBQUVELGlFQUFpRTtBQUNqRSxNQUFNLENBQUMsTUFBTSxjQUFjLEdBQUcsa0JBQWtCLENBQUM7QUFFakQsb0VBQW9FO0FBQ3BFLE1BQU0sQ0FBQyxNQUFNLGlCQUFpQixHQUFHLG1CQUFtQixDQUFDO0FBRXJEOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsYUFBYSxDQUFDLEdBQW9CO0lBQ2hELE9BQU8sTUFBTSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLGNBQWMsQ0FBQyxDQUFDLElBQUksU0FBUyxDQUFDO0FBQ3BFLENBQUM7QUFFRCx5REFBeUQ7QUFDekQsTUFBTSxVQUFVLGdCQUFnQixDQUFDLEdBQW9CO0lBQ25ELE9BQU8sTUFBTSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLGlCQUFpQixDQUFDLENBQUMsSUFBSSxTQUFTLENBQUM7QUFDdkUsQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxVQUFVLG1CQUFtQixDQUFDLElBQXdCLEVBQUUsSUFBc0I7SUFDbEYsT0FBTyxJQUFJLEtBQUssbUJBQW1CLENBQUM7QUFDdEMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogV2hpY2ggRGF0YWJyaWNrcyBpZGVudGl0eSBhIGNoYXQgdHVybidzIHdvcmtzcGFjZSBjYWxscyBydW4gYXMuXG4gKlxuICogRXZlcnkgRGF0YWJyaWNrcyBjYWxsIGEgdHVybiBtYWtlcyAtIHRoZSBgL3NlcnZpbmctZW5kcG9pbnRzYCBjYXRhbG9ndWUgdGhlXG4gKiBtb2RlbCBwaWNrZXIgcmVhZHMsIEdlbmllIHN1Z2dlc3Rpb25zLCBgYXNrX2dlbmllYCwgYW5kIHRoZSBTdGF0ZW1lbnRcbiAqIEV4ZWN1dGlvbiBmZXRjaCBiZWhpbmQgYSBgW2RhdGE6PGlkPl1gIGVtYmVkIC0gZ29lcyB0aHJvdWdoIHRoZSB3b3Jrc3BhY2VcbiAqIGNsaWVudCBvbiB0aGUgYW1iaWVudCBBcHBLaXQgZXhlY3V0aW9uIGNvbnRleHQuIFRoYXQgY29udGV4dCBpcyB1c2VyLXNjb3BlZFxuICogKE9CTykgd2hlbmV2ZXIgdGhlIHBsdWdpbiBlbnRlcnMgYGFzVXNlcihyZXEpYCBhbmQgdGhlIGFwcCdzIHNlcnZpY2UgcHJpbmNpcGFsXG4gKiBvdGhlcndpc2UsIHNvIE9ORSBkZWNpc2lvbiAtIGRvIHdlIGVudGVyIHRoYXQgc2NvcGUgZm9yIHRoaXMgcmVxdWVzdCAtIG1vdmVzXG4gKiBldmVyeSBjYWxsIHNpdGUgdG9nZXRoZXIuIFRoaXMgbW9kdWxlIG93bnMgdGhhdCBkZWNpc2lvbi5cbiAqXG4gKiBXaHkgdGhlIG9wdGlvbiBleGlzdHM6IE9CTyByZXF1aXJlcyB0aGUgY2FsbGVyIHRvIGJlIGEgbWVtYmVyIG9mIHRoZVxuICogV09SS1NQQUNFLCBub3QgbWVyZWx5IG9mIHRoZSBEYXRhYnJpY2tzIGFjY291bnQuIEFuIGFwcCBzaGFyZWQgd2l0aCBhblxuICogYWNjb3VudC1sZXZlbCBncm91cCBjYW4gdGhlcmVmb3JlIGJlIG9wZW5lZCBieSBzb21lb25lIHdob3NlIE9CTyB0b2tlbiBpc1xuICogcGVyZmVjdGx5IHZhbGlkIGJ1dCB3aG9zZSBldmVyeSB3b3Jrc3BhY2UgY2FsbCBmYWlscyB3aXRoIGBVbmF1dGhvcml6ZWRcbiAqIGFjY2VzcyB0byBPcmc6IDx3b3Jrc3BhY2UtaWQ+YCwgYW5kIGdyYW50aW5nIHdvcmtzcGFjZSBtZW1iZXJzaGlwIGlzIG5vdFxuICogYWx3YXlzIGF2YWlsYWJsZSAtIGEgd29ya3NwYWNlIGNhcHMgbWVtYmVyc2hpcCBmYXIgYmVsb3cgdGhlIHNpemUgb2YgYSBsYXJnZVxuICogYWNjb3VudCdzIHVzZXIgZ3JvdXAuIFRoZSBhcHAncyBvd24gc2VydmljZSBwcmluY2lwYWwgYWxyZWFkeSBob2xkcyB0aGUgR2VuaWVcbiAqIC8gd2FyZWhvdXNlIC8gc2VydmluZyAvIFVuaXR5IENhdGFsb2cgZ3JhbnRzIHRoZSBhcHAgd2FzIGRlcGxveWVkIHdpdGgsIGFuZFxuICogd29ya3MgZm9yIGV2ZXJ5IGNhbGxlci5cbiAqXG4gKiBUaGUgdHdvIG1vZGVzLCBmcm9tIGBjb25maWcuZ2VuaWVJZGVudGl0eWAgKGVudjoge0BsaW5rIElERU5USVRZX0VOVn0pOlxuICpcbiAqICAgLSBgXCJ1c2VyXCJgIChkZWZhdWx0KTogYWx3YXlzIE9CTy4gQ2FsbHMgYXJlIGF0dHJpYnV0ZWQgcGVyIHVzZXIgYW5kIEdlbmllIC9cbiAqICAgICBVbml0eSBDYXRhbG9nIHJvdyBmaWx0ZXJzIGFwcGx5IHBlciB1c2VyLiBDb3JyZWN0IHdoZW5ldmVyIGV2ZXJ5IGNhbGxlciBpc1xuICogICAgIGEgd29ya3NwYWNlIG1lbWJlci4gVGhpcyBpcyB0aGUgaGlzdG9yaWNhbCBiZWhhdmlvciwgc28gdGhlIG9wdGlvbiBpc1xuICogICAgIHB1cmVseSBhZGRpdGl2ZSAtIGFuIGFwcCB0aGF0IG5ldmVyIHNldHMgaXQgaXMgdW5jaGFuZ2VkLlxuICogICAtIGBcInNlcnZpY2UtcHJpbmNpcGFsXCJgOiBhbHdheXMgdGhlIGFwcCBzZXJ2aWNlIHByaW5jaXBhbC4gTmVlZHMgbm8gT0JPXG4gKiAgICAgc2NvcGVzIGFuZCB3b3JrcyBmb3IgYW55IGNhbGxlciB3aG8gY2FuIG9wZW4gdGhlIGFwcCwgYXQgdGhlIGNvc3Qgb2ZcbiAqICAgICBwZXItdXNlciBhdHRyaWJ1dGlvbiBpbiBHZW5pZSAvIFVuaXR5IENhdGFsb2cuXG4gKlxuICogV2hhdCBgXCJzZXJ2aWNlLXByaW5jaXBhbFwiYCBkb2VzIE5PVCBjaGFuZ2UgaXMgV0hPIHRoZSB0dXJuIGJlbG9uZ3MgdG8uIFRoZVxuICogbWVtb3J5IHRocmVhZCdzIGByZXNvdXJjZUlkYCwgdGhlIHBlci11c2VyIGNhY2hlIG5hbWVzcGFjZSwgYW5kIHRoZSB1c2VyXG4gKiBtZXRhZGF0YSBvbiB0cmFjZXMgc3RpbGwgY29tZSBmcm9tIHRoZSBmb3J3YXJkZWQgcmVxdWVzdCBoZWFkZXJzLCBzbyB0d29cbiAqIGFjY291bnQgdXNlcnMgc2hhcmluZyB0aGUgc2VydmljZSBwcmluY2lwYWwncyBkYXRhIGFjY2VzcyBzdGlsbCBnZXQgc2VwYXJhdGVcbiAqIGNvbnZlcnNhdGlvbnMgYW5kIGNhbm5vdCByZWFkIGVhY2ggb3RoZXIncyB0aHJlYWRzIG9yIGNhY2hlZCBjaGFydHMuIE9ubHkgdGhlXG4gKiBEYXRhYnJpY2tzIGNyZWRlbnRpYWwgaXMgc2hhcmVkLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBDb25maWd1cmF0aW9uRXJyb3IgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG5pbXBvcnQgeyBzdHJpbmcgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuaW1wb3J0IHR5cGUgZXhwcmVzcyBmcm9tIFwiZXhwcmVzc1wiO1xuXG4vKiogSWRlbnRpdHkgYSBjaGF0IHR1cm4ncyBEYXRhYnJpY2tzIGNhbGxzIHJ1biBhcy4gU2VlIHRoZSBtb2R1bGUgZG9jcy4gKi9cbmV4cG9ydCB0eXBlIE1hc3RyYUlkZW50aXR5TW9kZSA9IFwidXNlclwiIHwgXCJzZXJ2aWNlLXByaW5jaXBhbFwiO1xuXG4vKiogRW52aXJvbm1lbnQgZmFsbGJhY2sgZm9yIGBjb25maWcuZ2VuaWVJZGVudGl0eWAuICovXG5leHBvcnQgY29uc3QgSURFTlRJVFlfRU5WID0gXCJNQVNUUkFfR0VOSUVfSURFTlRJVFlcIjtcblxuLyoqIEV2ZXJ5IGFjY2VwdGVkIHtAbGluayBNYXN0cmFJZGVudGl0eU1vZGV9LiAqL1xuZXhwb3J0IGNvbnN0IElERU5USVRZX01PREVTOiByZWFkb25seSBNYXN0cmFJZGVudGl0eU1vZGVbXSA9IFtcInVzZXJcIiwgXCJzZXJ2aWNlLXByaW5jaXBhbFwiXTtcblxuLyoqXG4gKiBEZWZhdWx0IG1vZGUuIGBcInVzZXJcImAga2VlcHMgT0JPIHRoZSBvbmx5IGlkZW50aXR5IHVubGVzcyBhbiBhcHAgb3B0cyBpbiwgc29cbiAqIGFkb3B0aW5nIHRoaXMgb3B0aW9uIGNhbiBuZXZlciBzaWxlbnRseSB3aWRlbiBhbiBleGlzdGluZyBhcHAncyBkYXRhIGFjY2Vzcy5cbiAqL1xuZXhwb3J0IGNvbnN0IERFRkFVTFRfSURFTlRJVFlfTU9ERTogTWFzdHJhSWRlbnRpdHlNb2RlID0gXCJ1c2VyXCI7XG5cbi8qKlxuICogUmVzb2x2ZSB0aGUgY29uZmlndXJlZCBtb2RlOiBleHBsaWNpdCBwbHVnaW4gY29uZmlnLCB0aGVuIHtAbGluayBJREVOVElUWV9FTlZ9LFxuICogdGhlbiB7QGxpbmsgREVGQVVMVF9JREVOVElUWV9NT0RFfS5cbiAqXG4gKiBBbiB1bnJlY29nbml6ZWQgdmFsdWUgdGhyb3dzIHJhdGhlciB0aGFuIGZhbGxpbmcgYmFjaywgc2luY2UgZmFsbGluZyBiYWNrXG4gKiB3b3VsZCBzaWxlbnRseSBrZWVwIHNlcnZpbmcgT0JPIC0gYW5kIHRoZSA1MDBzIGl0IHByb2R1Y2VzIC0gdG8gZXhhY3RseSB0aGVcbiAqIGNhbGxlcnMgdGhlIG9wdGlvbiB3YXMgc2V0IHRvIGFjY29tbW9kYXRlLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVzb2x2ZUlkZW50aXR5TW9kZShjb25maWd1cmVkOiBzdHJpbmcgfCB1bmRlZmluZWQpOiBNYXN0cmFJZGVudGl0eU1vZGUge1xuICBjb25zdCByYXcgPSBzdHJpbmcudHJpbVRvTnVsbChjb25maWd1cmVkKSA/PyBzdHJpbmcudHJpbVRvTnVsbChwcm9jZXNzLmVudltJREVOVElUWV9FTlZdKTtcbiAgaWYgKHJhdyA9PT0gbnVsbCkgcmV0dXJuIERFRkFVTFRfSURFTlRJVFlfTU9ERTtcbiAgY29uc3QgbW9kZSA9IHJhdy50b0xvd2VyQ2FzZSgpIGFzIE1hc3RyYUlkZW50aXR5TW9kZTtcbiAgaWYgKCFJREVOVElUWV9NT0RFUy5pbmNsdWRlcyhtb2RlKSkge1xuICAgIHRocm93IG5ldyBDb25maWd1cmF0aW9uRXJyb3IoXG4gICAgICBgZ2VuaWVJZGVudGl0eSBtdXN0IGJlIG9uZSBvZiAke0lERU5USVRZX01PREVTLmpvaW4oXCIgfCBcIil9IChlbnY6ICR7SURFTlRJVFlfRU5WfSlgLFxuICAgICAgeyBjb250ZXh0OiB7IGZpZWxkOiBcImdlbmllSWRlbnRpdHlcIiwgZW52VmFyOiBJREVOVElUWV9FTlYsIHJlY2VpdmVkOiByYXcgfSB9LFxuICAgICk7XG4gIH1cbiAgcmV0dXJuIG1vZGU7XG59XG5cbi8qKiBIZWFkZXIgRGF0YWJyaWNrcyBBcHBzIGZvcndhcmQgdGhlIHNpZ25lZC1pbiB1c2VyJ3MgaWQgb24uICovXG5leHBvcnQgY29uc3QgVVNFUl9JRF9IRUFERVIgPSBcIngtZm9yd2FyZGVkLXVzZXJcIjtcblxuLyoqIEhlYWRlciBEYXRhYnJpY2tzIEFwcHMgZm9yd2FyZCB0aGUgc2lnbmVkLWluIHVzZXIncyBlbWFpbCBvbi4gKi9cbmV4cG9ydCBjb25zdCBVU0VSX0VNQUlMX0hFQURFUiA9IFwieC1mb3J3YXJkZWQtZW1haWxcIjtcblxuLyoqXG4gKiBUaGUgZm9yd2FyZGVkIHVzZXIgaWQgb24gYHJlcWAsIG9yIGB1bmRlZmluZWRgLiBVc2VkIHRvIGF0dHJpYnV0ZSBhIHR1cm4gdG9cbiAqIHRoZSByZWFsIGNhbGxlciBpbiBgc2VydmljZS1wcmluY2lwYWxgIG1vZGUsIHdoZXJlIHRoZSBEYXRhYnJpY2tzIGNsaWVudCBpc1xuICogdGhlIGFwcCBTUCBidXQgbWVtb3J5IC8gY2FjaGUgLyB0cmFjZXMgbXVzdCBzdGlsbCBrZXkgb2ZmIHRoZSB1c2VyLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVxdWVzdFVzZXJJZChyZXE6IGV4cHJlc3MuUmVxdWVzdCk6IHN0cmluZyB8IHVuZGVmaW5lZCB7XG4gIHJldHVybiBzdHJpbmcudHJpbVRvTnVsbChyZXEuaGVhZGVyKFVTRVJfSURfSEVBREVSKSkgPz8gdW5kZWZpbmVkO1xufVxuXG4vKiogVGhlIGZvcndhcmRlZCB1c2VyIGVtYWlsIG9uIGByZXFgLCBvciBgdW5kZWZpbmVkYC4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXF1ZXN0VXNlckVtYWlsKHJlcTogZXhwcmVzcy5SZXF1ZXN0KTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgcmV0dXJuIHN0cmluZy50cmltVG9OdWxsKHJlcS5oZWFkZXIoVVNFUl9FTUFJTF9IRUFERVIpKSA/PyB1bmRlZmluZWQ7XG59XG5cbi8qKlxuICogV2hldGhlciB0aGlzIHJlcXVlc3Qgc2hvdWxkIHJ1biBpdHMgRGF0YWJyaWNrcyBjYWxscyBhcyB0aGUgYXBwIHNlcnZpY2VcbiAqIHByaW5jaXBhbCByYXRoZXIgdGhhbiBPQk8uIGBcInNlcnZpY2UtcHJpbmNpcGFsXCJgIGFsd2F5cyBkb2VzOyBgXCJ1c2VyXCJgIG5ldmVyXG4gKiBkb2VzLiBUaGUgcmVxdWVzdCBpcyBhY2NlcHRlZCBmb3Igc3ltbWV0cnkgYW5kIHRvIGxlYXZlIHJvb20gZm9yXG4gKiByZXF1ZXN0LXNjb3BlZCBwb2xpY3kgbGF0ZXI7IGl0IGlzIHVudXNlZCB0b2RheS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHVzZVNlcnZpY2VQcmluY2lwYWwobW9kZTogTWFzdHJhSWRlbnRpdHlNb2RlLCBfcmVxPzogZXhwcmVzcy5SZXF1ZXN0KTogYm9vbGVhbiB7XG4gIHJldHVybiBtb2RlID09PSBcInNlcnZpY2UtcHJpbmNpcGFsXCI7XG59XG4iXX0=

package/lib/src/plugin.d.ts

@@ -103,6 +103,12 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
      * {@link buildAgentAndServer} and registered on the Mastra instance.
      */
     private mcp;
+    /**
+     * Resolved {@link MastraIdentityMode}: the identity the chat path's Databricks
+     * calls run as. Read once at setup so an invalid `genieIdentity` fails the app
+     * boot rather than the first request, and so every request agrees.
+     */
+    private identityMode;
     /**
      * Dedicated service-principal Lakebase pool backing Mastra memory /
      * storage. Built once in {@link buildAgentAndServer} (outside any
@@ -112,6 +118,22 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
      */
     private servicePrincipalPool;
     setup(): Promise<void>;
+    /**
+     * The plugin instance the chat path's Databricks calls should run through for
+     * `req`, honoring {@link identityMode}.
+     *
+     * In `"user"` mode (the default) this is `this.asUser(req)` - AppKit's own
+     * proxy that runs every call inside `runInUserContext`, so `getExecutionContext()`
+     * returns the caller's OBO client, exactly as before this option existed. In
+     * `"service-principal"` mode it is `this` unwrapped, so the same methods run in
+     * the ambient service context and `getExecutionContext()` returns the app
+     * service principal's client - the same "just don't enter `asUser`" pattern
+     * AppKit's own service-context calls use. One helper covers every workspace
+     * call the chat path makes (serving catalogue, Genie suggestions, `ask_genie`
+     * via the dispatched agent turn, statement fetch, feedback), so the identity
+     * decision lives in one place.
+     */
+    private scopedSelf;
     /**
      * When the `lakebase` plugin is registered, auto-enable `storage`
      * and `memory` unless the caller opted out explicitly (`false` or a