@dbx-tools/appkit-mastra 0.9.179 → 0.9.182

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -36,23 +36,23 @@
36
36
  },
37
37
  "dependencies": {
38
38
  "@databricks/appkit": "0.81.0",
39
- "@dbx-tools/appkit": "^0.9.179",
40
- "@dbx-tools/appkit-model-gateway": "^0.9.179",
41
- "@dbx-tools/cache": "^0.9.179",
42
- "@dbx-tools/core": "^0.9.179",
43
- "@dbx-tools/databricks": "^0.9.179",
44
- "@dbx-tools/fs": "^0.9.179",
45
- "@dbx-tools/genie": "^0.9.179",
46
- "@dbx-tools/model": "^0.9.179",
47
- "@dbx-tools/model-protocol": "^0.9.179",
48
- "@dbx-tools/path": "^0.9.179",
49
- "@dbx-tools/postgres": "^0.9.179",
50
- "@dbx-tools/shared-core": "^0.9.179",
51
- "@dbx-tools/shared-fs": "^0.9.179",
52
- "@dbx-tools/shared-genie": "^0.9.179",
53
- "@dbx-tools/shared-mastra": "^0.9.179",
54
- "@dbx-tools/shared-model": "^0.9.179",
55
- "@dbx-tools/shared-model-gateway": "^0.9.179",
39
+ "@dbx-tools/appkit": "^0.9.182",
40
+ "@dbx-tools/appkit-model-gateway": "^0.9.182",
41
+ "@dbx-tools/cache": "^0.9.182",
42
+ "@dbx-tools/core": "^0.9.182",
43
+ "@dbx-tools/databricks": "^0.9.182",
44
+ "@dbx-tools/fs": "^0.9.182",
45
+ "@dbx-tools/genie": "^0.9.182",
46
+ "@dbx-tools/model": "^0.9.182",
47
+ "@dbx-tools/model-protocol": "^0.9.182",
48
+ "@dbx-tools/path": "^0.9.182",
49
+ "@dbx-tools/postgres": "^0.9.182",
50
+ "@dbx-tools/shared-core": "^0.9.182",
51
+ "@dbx-tools/shared-fs": "^0.9.182",
52
+ "@dbx-tools/shared-genie": "^0.9.182",
53
+ "@dbx-tools/shared-mastra": "^0.9.182",
54
+ "@dbx-tools/shared-model": "^0.9.182",
55
+ "@dbx-tools/shared-model-gateway": "^0.9.182",
56
56
  "@mastra/ai-sdk": "1.10.5",
57
57
  "@mastra/core": "1.71.0",
58
58
  "@mastra/express": "1.5.15",
@@ -90,7 +90,7 @@
90
90
  "./package.json": "./package.json"
91
91
  }
92
92
  },
93
- "version": "0.9.179",
93
+ "version": "0.9.182",
94
94
  "types": "./lib/index.d.ts",
95
95
  "dbxToolsConfig": {
96
96
  "tags": [
package/src/mlflow.ts CHANGED
@@ -12,15 +12,15 @@
12
12
  * trace id on each turn's response and the client sends it back here.
13
13
  *
14
14
  * There is no MLflow JS SDK, so this posts to the assessments REST
15
- * endpoint directly using the OBO-scoped workspace client (the feedback
16
- * is thus attributed to the signed-in user). UC-backed Apps traces need
17
- * the experiment's table-prefix URI (`trace:/{catalog}.{schema}.{prefix}/{tr-hex}`)
18
- * rather than the experiment-store id the UI does not store. That prefix is
19
- * read from the experiment's `mlflow.experiment.databricksTraceDestinationPath`
20
- * tag (or the spans-table tag); `MLFLOW_UC_TRACE_PREFIX` remains an optional
21
- * override. Trace export is asynchronous, so the just-finished trace may not
22
- * exist in MLflow yet when the user reacts; the log call retries briefly on
23
- * "not found" before giving up softly.
15
+ * endpoint directly using a workspace client. The plugin uses the App service
16
+ * principal for the write and supplies the trusted forwarded user identity as
17
+ * the assessment source. UC-backed Apps traces use MLflow's location-scoped V4
18
+ * endpoint and assessment contract. The table prefix is read from the
19
+ * experiment's `mlflow.experiment.databricksTraceDestinationPath` tag (or the
20
+ * spans-table tag); `MLFLOW_UC_TRACE_PREFIX` remains an optional override.
21
+ * Trace export is asynchronous, so the just-finished trace may not exist in
22
+ * MLflow yet when the user reacts; the log call retries briefly on "not found"
23
+ * before giving up softly.
24
24
  *
25
25
  * @module
26
26
  */
@@ -200,12 +200,12 @@ export function resetUcTracePrefixCache(): void {
200
200
  *
201
201
  * Databricks Apps persist traces in Unity Catalog. The experiment UI lists
202
202
  * those rows, but `POST /api/3.0/mlflow/traces/{id}/assessments` looks up the
203
- * experiment store unless `{id}` is the UC URI `trace:/{catalog}.{schema}.{prefix}/{tr-hex}`.
203
+ * experiment store unless `{id}` is the UC URI `trace:/{catalog}.{schema}.{prefix}/{hex}`.
204
204
  * A bare `tr-<hex>` 404s and the assessment never appears.
205
205
  */
206
206
  export function mlflowAssessmentTraceId(traceId: string, prefix?: string): string {
207
207
  const resolved = normalizeUcPrefix(prefix);
208
- return resolved ? `trace:/${resolved}/${traceId}` : traceId;
208
+ return resolved ? `trace:/${resolved}/${traceId.replace(/^tr-/, "")}` : traceId;
209
209
  }
210
210
 
211
211
  async function resolveUcTracePrefix(client: WorkspaceClient): Promise<string | undefined> {
@@ -230,10 +230,45 @@ async function resolveUcTracePrefix(client: WorkspaceClient): Promise<string | u
230
230
  return prefix;
231
231
  }
232
232
 
233
- /** Assessments REST path for a trace. `3.0` is the current MLflow API version. */
233
+ /** Resolve the configured Unity Catalog trace prefix without failing chat startup. */
234
+ export async function mlflowUcTracePrefix(
235
+ client: WorkspaceClient,
236
+ ): Promise<string | undefined> {
237
+ try {
238
+ return await resolveUcTracePrefix(client);
239
+ } catch {
240
+ return undefined;
241
+ }
242
+ }
243
+
244
+ /** V3 assessments REST path for an experiment-store trace. */
234
245
  const assessmentsPath = (traceId: string): string =>
235
246
  `/api/3.0/mlflow/traces/${encodeURIComponent(traceId)}/assessments`;
236
247
 
248
+ interface UcTraceLocation {
249
+ catalog: string;
250
+ schema: string;
251
+ tablePrefix: string;
252
+ location: string;
253
+ }
254
+
255
+ function ucTraceLocation(prefix: string | undefined): UcTraceLocation | undefined {
256
+ const parts = normalizeUcPrefix(prefix)?.split(".");
257
+ if (!parts || parts.length < 3) return undefined;
258
+ const [catalog, schema, ...tablePrefixParts] = parts;
259
+ const tablePrefix = tablePrefixParts.join(".");
260
+ if (!catalog || !schema || !tablePrefix) return undefined;
261
+ return { catalog, schema, tablePrefix, location: parts.join(".") };
262
+ }
263
+
264
+ function ucAssessmentsPath(location: string, traceId: string): string {
265
+ const warehouseId =
266
+ process.env.MLFLOW_TRACING_SQL_WAREHOUSE_ID?.trim() ||
267
+ process.env.DATABRICKS_WAREHOUSE_ID?.trim();
268
+ const path = `/api/4.0/mlflow/traces/${encodeURIComponent(location)}/${encodeURIComponent(traceId)}/assessments`;
269
+ return warehouseId ? `${path}?sql_warehouse_id=${encodeURIComponent(warehouseId)}` : path;
270
+ }
271
+
237
272
  /** Number of times to retry a "trace not found" response before giving up. */
238
273
  const NOT_FOUND_RETRIES = 3;
239
274
  /** Base backoff between "trace not found" retries, in ms (grows linearly). */
@@ -289,6 +324,16 @@ const CurrentUserResponseSchema = z
289
324
  .passthrough()
290
325
  .describe("Databricks Current User API response.");
291
326
 
327
+ const ScimUsersResponseSchema = z
328
+ .object({
329
+ Resources: z
330
+ .array(CurrentUserResponseSchema)
331
+ .optional()
332
+ .describe("Workspace users matching the SCIM filter."),
333
+ })
334
+ .passthrough()
335
+ .describe("Databricks SCIM user search response.");
336
+
292
337
  const ExperimentPermissionsResponseSchema = z
293
338
  .object({
294
339
  access_control_list: z
@@ -625,15 +670,37 @@ export function mlflowEnabled(): boolean {
625
670
 
626
671
  /**
627
672
  * Return the configured experiment URL only when the active Databricks
628
- * principal has effective `CAN_MANAGE` permission. Permission lookup is
673
+ * viewer has effective read access. Permission lookup is
629
674
  * intentionally best-effort so Apps environments that do not expose the
630
675
  * required APIs simply omit the debug affordance.
631
676
  */
632
677
  export async function mlflowExperimentManagerUrl(
633
678
  client: WorkspaceClient,
679
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean } = {},
634
680
  ): Promise<string | undefined> {
635
681
  try {
636
- return await resolveMlflowExperimentManagerUrl(client);
682
+ return await resolveMlflowExperimentManagerUrl(client, viewer);
683
+ } catch {
684
+ return undefined;
685
+ }
686
+ }
687
+
688
+ /**
689
+ * Return the configured experiment URL only when this client can read the
690
+ * experiment itself. Use this with the active user's OBO client so the Debug
691
+ * affordance exactly matches whether that user can open the experiment.
692
+ */
693
+ export async function mlflowExperimentViewerUrl(
694
+ client: WorkspaceClient,
695
+ ): Promise<string | undefined> {
696
+ try {
697
+ const experiment = await fetchExperiment(client);
698
+ if (!experiment) return undefined;
699
+ const host = (await client.config.getHost()).toString();
700
+ return new URL(
701
+ `/ml/experiments/${encodeURIComponent(experiment.experiment_id)}`,
702
+ host,
703
+ ).toString();
637
704
  } catch {
638
705
  return undefined;
639
706
  }
@@ -641,37 +708,69 @@ export async function mlflowExperimentManagerUrl(
641
708
 
642
709
  async function resolveMlflowExperimentManagerUrl(
643
710
  client: WorkspaceClient,
711
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean },
644
712
  ): Promise<string | undefined> {
645
713
  const experimentId = await resolveExperimentId(client);
646
714
  if (!experimentId) return undefined;
647
715
 
716
+ const viewerUserName = viewer.userName?.trim();
717
+ const viewerUserId = viewer.userId?.trim();
718
+ const currentPrincipalPath = viewerUserName
719
+ ? `/api/2.0/preview/scim/v2/Users?filter=${encodeURIComponent(
720
+ `userName eq "${viewerUserName.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`,
721
+ )}`
722
+ : viewerUserId
723
+ ? `/api/2.0/preview/scim/v2/Users/${encodeURIComponent(viewerUserId)}`
724
+ : "/api/2.0/preview/scim/v2/Me";
725
+
648
726
  const [currentResponse, permissionsResponse] = await Promise.all([
649
- databricksFetch(client, "/api/2.0/preview/scim/v2/Me", { method: "GET" }),
727
+ databricksFetch(client, currentPrincipalPath, { method: "GET" }),
650
728
  databricksFetch(
651
729
  client,
652
730
  `/api/2.0/permissions/experiments/${encodeURIComponent(experimentId)}`,
653
731
  { method: "GET" },
654
732
  ),
655
733
  ]);
656
- if (!currentResponse.ok || !permissionsResponse.ok) return undefined;
657
-
658
- const current = CurrentUserResponseSchema.safeParse(await readResponseJson(currentResponse));
734
+ if (!permissionsResponse.ok) return undefined;
735
+
736
+ let currentUser: z.infer<typeof CurrentUserResponseSchema> | undefined;
737
+ if (currentResponse.ok) {
738
+ const currentRaw = await readResponseJson(currentResponse);
739
+ if (viewerUserName) {
740
+ const users = ScimUsersResponseSchema.safeParse(currentRaw);
741
+ currentUser = users.success
742
+ ? users.data.Resources?.find(
743
+ (candidate) => candidate.userName?.toLowerCase() === viewerUserName.toLowerCase(),
744
+ )
745
+ : undefined;
746
+ } else {
747
+ const current = CurrentUserResponseSchema.safeParse(currentRaw);
748
+ currentUser = current.success ? current.data : undefined;
749
+ }
750
+ }
659
751
  const permissions = ExperimentPermissionsResponseSchema.safeParse(
660
752
  await readResponseJson(permissionsResponse),
661
753
  );
662
- if (!current.success || !permissions.success) return undefined;
754
+ const hasForwardedViewer = Boolean(viewerUserName || viewerUserId);
755
+ if (!permissions.success || (!hasForwardedViewer && !currentUser)) return undefined;
663
756
 
664
757
  const userNames = new Set(
665
- [current.data.userName, current.data.applicationId, current.data.displayName].filter(
666
- (value): value is string => Boolean(value),
667
- ),
758
+ [
759
+ viewerUserName,
760
+ ...(currentUser
761
+ ? [currentUser.userName, currentUser.applicationId, currentUser.displayName]
762
+ : []),
763
+ ]
764
+ .map((value) => value?.trim())
765
+ .filter((value): value is string => Boolean(value)),
668
766
  );
669
767
  const groupNames = new Set(
670
- (current.data.groups ?? []).flatMap(({ value, display }) =>
768
+ (currentUser?.groups ?? []).flatMap(({ value, display }) =>
671
769
  [value, display].filter((entry): entry is string => Boolean(entry)),
672
770
  ),
673
771
  );
674
- const canManage = (permissions.data.access_control_list ?? []).some((entry) => {
772
+ if (viewer.workspaceUser) groupNames.add("users");
773
+ const canView = (permissions.data.access_control_list ?? []).some((entry) => {
675
774
  const matches =
676
775
  (entry.user_name !== undefined && userNames.has(entry.user_name)) ||
677
776
  (entry.service_principal_name !== undefined && userNames.has(entry.service_principal_name)) ||
@@ -679,11 +778,14 @@ async function resolveMlflowExperimentManagerUrl(
679
778
  return (
680
779
  matches &&
681
780
  (entry.all_permissions ?? []).some(
682
- (permission) => permission.permission_level === "CAN_MANAGE",
781
+ (permission) =>
782
+ permission.permission_level === "CAN_READ" ||
783
+ permission.permission_level === "CAN_EDIT" ||
784
+ permission.permission_level === "CAN_MANAGE",
683
785
  )
684
786
  );
685
787
  });
686
- if (!canManage) return undefined;
788
+ if (!canView) return undefined;
687
789
 
688
790
  const host = (await client.config.getHost()).toString();
689
791
  return new URL(`/ml/experiments/${encodeURIComponent(experimentId)}`, host).toString();
@@ -735,13 +837,27 @@ export async function logFeedback(
735
837
  const hasValue = params.value !== undefined;
736
838
  const name = params.name?.trim() || (hasValue ? DEFAULT_FEEDBACK_NAME : DEFAULT_COMMENT_NAME);
737
839
  const value = hasValue ? params.value : params.comment;
738
- const assessmentTraceId = mlflowAssessmentTraceId(
739
- params.traceId,
740
- await resolveUcTracePrefix(client),
741
- );
840
+ const prefix = await resolveUcTracePrefix(client);
841
+ const location = ucTraceLocation(prefix);
842
+ const rawTraceId = params.traceId.replace(/^tr-/, "");
843
+ const assessmentTraceId = location
844
+ ? mlflowAssessmentTraceId(rawTraceId, location.location)
845
+ : params.traceId;
742
846
  const assessment: Record<string, unknown> = {
743
- trace_id: assessmentTraceId,
847
+ trace_id: location ? rawTraceId : assessmentTraceId,
744
848
  assessment_name: name,
849
+ ...(location
850
+ ? {
851
+ trace_location: {
852
+ type: "UC_TABLE_PREFIX",
853
+ uc_table_prefix: {
854
+ catalog_name: location.catalog,
855
+ schema_name: location.schema,
856
+ table_prefix: location.tablePrefix,
857
+ },
858
+ },
859
+ }
860
+ : {}),
745
861
  source: {
746
862
  source_type: "HUMAN",
747
863
  source_id: params.sourceId?.trim() || "user",
@@ -749,12 +865,22 @@ export async function logFeedback(
749
865
  feedback: { value },
750
866
  ...(hasValue && params.comment?.trim() ? { rationale: params.comment } : {}),
751
867
  };
752
- const body = { assessment };
868
+ const body = location
869
+ ? {
870
+ ...assessment,
871
+ create_time: new Date().toISOString(),
872
+ last_update_time: new Date().toISOString(),
873
+ valid: true,
874
+ }
875
+ : { assessment };
876
+ const path = location
877
+ ? ucAssessmentsPath(location.location, rawTraceId)
878
+ : assessmentsPath(assessmentTraceId);
753
879
 
754
880
  for (let attempt = 0; attempt <= NOT_FOUND_RETRIES; attempt++) {
755
881
  let res: Response;
756
882
  try {
757
- res = await databricksFetch(client, assessmentsPath(assessmentTraceId), {
883
+ res = await databricksFetch(client, path, {
758
884
  method: "POST",
759
885
  body,
760
886
  });
package/src/plugin.ts CHANGED
@@ -64,6 +64,8 @@ import {
64
64
  configureNativeHttpTelemetry,
65
65
  excludeUnparentedOutgoingHttpTelemetry,
66
66
  deferredNativeTracerProvider,
67
+ requestAccessToken,
68
+ requestUserEmail,
67
69
  requestUserId,
68
70
  useServicePrincipal,
69
71
  } from "@dbx-tools/appkit";
@@ -141,6 +143,8 @@ import {
141
143
  logFeedback,
142
144
  mlflowEnabled,
143
145
  mlflowExperimentManagerUrl,
146
+ mlflowExperimentViewerUrl,
147
+ mlflowUcTracePrefix,
144
148
  } from "./mlflow.ts";
145
149
  import { resolveDefaultModelId, withSmartRouterEndpoint } from "./model.ts";
146
150
  import { buildObservability, configureOtelPropagation } from "./observability.ts";
@@ -1024,7 +1028,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1024
1028
  res.json({ ok: true });
1025
1029
  return;
1026
1030
  }
1027
- const result = await this.scopedSelf(req).logFeedback(parsed.data);
1031
+ const sourceId = requestUserEmail(req) ?? requestUserId(req);
1032
+ const result = await this.logFeedback(parsed.data, sourceId);
1028
1033
  if (!result.ok) {
1029
1034
  this.sendFailure(res, result, "feedback", "Feedback could not be recorded");
1030
1035
  return;
@@ -1046,11 +1051,33 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1046
1051
  path: MASTRA_ROUTES.mlflowExperiment,
1047
1052
  handler: async (req, res) => {
1048
1053
  if (!this.feedbackEnabled("mlflow")) {
1049
- res.json({ url: null });
1054
+ res.json({ url: null, tracePrefix: null });
1050
1055
  return;
1051
1056
  }
1052
- const result = await this.scopedSelf(req).fetchMlflowExperimentUrl();
1053
- res.json({ url: result.ok ? (result.data ?? null) : null });
1057
+ const hasOboToken = requestAccessToken(req) !== undefined;
1058
+ const userName = requestUserEmail(req);
1059
+ const userId = requestUserId(req);
1060
+ const viewer = {
1061
+ ...(userName ? { userName } : {}),
1062
+ ...(userId ? { userId } : {}),
1063
+ ...(hasOboToken ? { workspaceUser: true } : {}),
1064
+ };
1065
+ let result = hasOboToken
1066
+ ? await this.asUser(req).fetchMlflowExperimentViewerUrl()
1067
+ : undefined;
1068
+ if (!result?.ok || !result.data) {
1069
+ result = await this.fetchMlflowExperimentUrl(viewer);
1070
+ }
1071
+ const url = result.ok ? (result.data ?? null) : null;
1072
+ if (!url) {
1073
+ res.json({ url: null, tracePrefix: null });
1074
+ return;
1075
+ }
1076
+ const tracePrefix = await this.fetchMlflowTracePrefix();
1077
+ res.json({
1078
+ url,
1079
+ tracePrefix: tracePrefix.ok ? (tracePrefix.data ?? null) : null,
1080
+ });
1054
1081
  },
1055
1082
  });
1056
1083
  }
@@ -1180,22 +1207,24 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1180
1207
 
1181
1208
  /**
1182
1209
  * Implementation backing the `/route/feedback` route. Runs inside the
1183
- * AppKit user-context proxy so `getExecutionContext()` returns the
1184
- * OBO-scoped client and the assessment is attributed to the signed-in
1185
- * user (their email / id as the assessment source). Returns the
1210
+ * AppKit request context. The workspace client writes the assessment and
1211
+ * the trusted forwarded identity attributes it to the signed-in user.
1212
+ * Returns the
1186
1213
  * created assessment id on success, or `undefined` on a soft failure
1187
1214
  * (see {@link logFeedback} in `./mlflow.js`).
1188
1215
  */
1189
1216
  private async logFeedback(
1190
1217
  feedback: MlflowFeedbackRequest,
1218
+ attributedSourceId?: string,
1191
1219
  ): Promise<ExecutionResult<string | undefined>> {
1192
1220
  const ctx = getExecutionContext();
1193
1221
  const sourceId =
1194
- "userEmail" in ctx && ctx.userEmail
1222
+ attributedSourceId ??
1223
+ ("userEmail" in ctx && ctx.userEmail
1195
1224
  ? ctx.userEmail
1196
1225
  : "userId" in ctx
1197
1226
  ? ctx.userId
1198
- : ctx.serviceUserId;
1227
+ : ctx.serviceUserId);
1199
1228
  return this.execute(
1200
1229
  () =>
1201
1230
  logFeedback(ctx.client, {
@@ -1230,11 +1259,27 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1230
1259
 
1231
1260
  /**
1232
1261
  * Resolve an experiment link under the active request identity. The helper
1233
- * returns no URL unless the viewer has effective `CAN_MANAGE` permission.
1262
+ * returns no URL unless the viewer has effective read access.
1234
1263
  */
1235
- private async fetchMlflowExperimentUrl(): Promise<ExecutionResult<string | undefined>> {
1264
+ private async fetchMlflowExperimentUrl(
1265
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean } = {},
1266
+ ): Promise<ExecutionResult<string | undefined>> {
1267
+ const client = getExecutionContext().client;
1268
+ return this.execute(() => mlflowExperimentManagerUrl(client, viewer), feedbackWriteDefaults);
1269
+ }
1270
+
1271
+ /** Verify experiment visibility through the active user's OBO client. */
1272
+ private async fetchMlflowExperimentViewerUrl(): Promise<
1273
+ ExecutionResult<string | undefined>
1274
+ > {
1275
+ const client = getExecutionContext().client;
1276
+ return this.execute(() => mlflowExperimentViewerUrl(client), feedbackWriteDefaults);
1277
+ }
1278
+
1279
+ /** Resolve the configured UC trace prefix for an authorized Debug link. */
1280
+ private async fetchMlflowTracePrefix(): Promise<ExecutionResult<string | undefined>> {
1236
1281
  const client = getExecutionContext().client;
1237
- return this.execute(() => mlflowExperimentManagerUrl(client), feedbackWriteDefaults);
1282
+ return this.execute(() => mlflowUcTracePrefix(client), feedbackWriteDefaults);
1238
1283
  }
1239
1284
 
1240
1285
  /**