@dbx-tools/appkit-mastra 0.9.181 → 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.181",
40
- "@dbx-tools/appkit-model-gateway": "^0.9.181",
41
- "@dbx-tools/cache": "^0.9.181",
42
- "@dbx-tools/core": "^0.9.181",
43
- "@dbx-tools/databricks": "^0.9.181",
44
- "@dbx-tools/fs": "^0.9.181",
45
- "@dbx-tools/genie": "^0.9.181",
46
- "@dbx-tools/model": "^0.9.181",
47
- "@dbx-tools/model-protocol": "^0.9.181",
48
- "@dbx-tools/path": "^0.9.181",
49
- "@dbx-tools/postgres": "^0.9.181",
50
- "@dbx-tools/shared-core": "^0.9.181",
51
- "@dbx-tools/shared-fs": "^0.9.181",
52
- "@dbx-tools/shared-genie": "^0.9.181",
53
- "@dbx-tools/shared-mastra": "^0.9.181",
54
- "@dbx-tools/shared-model": "^0.9.181",
55
- "@dbx-tools/shared-model-gateway": "^0.9.181",
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.181",
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,16 +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,
634
- viewerUserName?: string,
679
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean } = {},
680
+ ): Promise<string | undefined> {
681
+ try {
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,
635
695
  ): Promise<string | undefined> {
636
696
  try {
637
- return await resolveMlflowExperimentManagerUrl(client, viewerUserName);
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();
638
704
  } catch {
639
705
  return undefined;
640
706
  }
@@ -642,13 +708,23 @@ export async function mlflowExperimentManagerUrl(
642
708
 
643
709
  async function resolveMlflowExperimentManagerUrl(
644
710
  client: WorkspaceClient,
645
- viewerUserName?: string,
711
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean },
646
712
  ): Promise<string | undefined> {
647
713
  const experimentId = await resolveExperimentId(client);
648
714
  if (!experimentId) return undefined;
649
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
+
650
726
  const [currentResponse, permissionsResponse] = await Promise.all([
651
- databricksFetch(client, "/api/2.0/preview/scim/v2/Me", { method: "GET" }),
727
+ databricksFetch(client, currentPrincipalPath, { method: "GET" }),
652
728
  databricksFetch(
653
729
  client,
654
730
  `/api/2.0/permissions/experiments/${encodeURIComponent(experimentId)}`,
@@ -657,30 +733,44 @@ async function resolveMlflowExperimentManagerUrl(
657
733
  ]);
658
734
  if (!permissionsResponse.ok) return undefined;
659
735
 
660
- const current = currentResponse.ok
661
- ? CurrentUserResponseSchema.safeParse(await readResponseJson(currentResponse))
662
- : undefined;
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
+ }
663
751
  const permissions = ExperimentPermissionsResponseSchema.safeParse(
664
752
  await readResponseJson(permissionsResponse),
665
753
  );
666
- if (!permissions.success || (!viewerUserName && !current?.success)) return undefined;
754
+ const hasForwardedViewer = Boolean(viewerUserName || viewerUserId);
755
+ if (!permissions.success || (!hasForwardedViewer && !currentUser)) return undefined;
667
756
 
668
757
  const userNames = new Set(
669
758
  [
670
759
  viewerUserName,
671
- ...(current?.success
672
- ? [current.data.userName, current.data.applicationId, current.data.displayName]
760
+ ...(currentUser
761
+ ? [currentUser.userName, currentUser.applicationId, currentUser.displayName]
673
762
  : []),
674
763
  ]
675
764
  .map((value) => value?.trim())
676
765
  .filter((value): value is string => Boolean(value)),
677
766
  );
678
767
  const groupNames = new Set(
679
- (current?.success ? (current.data.groups ?? []) : []).flatMap(({ value, display }) =>
768
+ (currentUser?.groups ?? []).flatMap(({ value, display }) =>
680
769
  [value, display].filter((entry): entry is string => Boolean(entry)),
681
770
  ),
682
771
  );
683
- 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) => {
684
774
  const matches =
685
775
  (entry.user_name !== undefined && userNames.has(entry.user_name)) ||
686
776
  (entry.service_principal_name !== undefined && userNames.has(entry.service_principal_name)) ||
@@ -688,11 +778,14 @@ async function resolveMlflowExperimentManagerUrl(
688
778
  return (
689
779
  matches &&
690
780
  (entry.all_permissions ?? []).some(
691
- (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",
692
785
  )
693
786
  );
694
787
  });
695
- if (!canManage) return undefined;
788
+ if (!canView) return undefined;
696
789
 
697
790
  const host = (await client.config.getHost()).toString();
698
791
  return new URL(`/ml/experiments/${encodeURIComponent(experimentId)}`, host).toString();
@@ -744,13 +837,27 @@ export async function logFeedback(
744
837
  const hasValue = params.value !== undefined;
745
838
  const name = params.name?.trim() || (hasValue ? DEFAULT_FEEDBACK_NAME : DEFAULT_COMMENT_NAME);
746
839
  const value = hasValue ? params.value : params.comment;
747
- const assessmentTraceId = mlflowAssessmentTraceId(
748
- params.traceId,
749
- await resolveUcTracePrefix(client),
750
- );
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;
751
846
  const assessment: Record<string, unknown> = {
752
- trace_id: assessmentTraceId,
847
+ trace_id: location ? rawTraceId : assessmentTraceId,
753
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
+ : {}),
754
861
  source: {
755
862
  source_type: "HUMAN",
756
863
  source_id: params.sourceId?.trim() || "user",
@@ -758,12 +865,22 @@ export async function logFeedback(
758
865
  feedback: { value },
759
866
  ...(hasValue && params.comment?.trim() ? { rationale: params.comment } : {}),
760
867
  };
761
- 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);
762
879
 
763
880
  for (let attempt = 0; attempt <= NOT_FOUND_RETRIES; attempt++) {
764
881
  let res: Response;
765
882
  try {
766
- res = await databricksFetch(client, assessmentsPath(assessmentTraceId), {
883
+ res = await databricksFetch(client, path, {
767
884
  method: "POST",
768
885
  body,
769
886
  });
package/src/plugin.ts CHANGED
@@ -64,6 +64,7 @@ import {
64
64
  configureNativeHttpTelemetry,
65
65
  excludeUnparentedOutgoingHttpTelemetry,
66
66
  deferredNativeTracerProvider,
67
+ requestAccessToken,
67
68
  requestUserEmail,
68
69
  requestUserId,
69
70
  useServicePrincipal,
@@ -142,6 +143,8 @@ import {
142
143
  logFeedback,
143
144
  mlflowEnabled,
144
145
  mlflowExperimentManagerUrl,
146
+ mlflowExperimentViewerUrl,
147
+ mlflowUcTracePrefix,
145
148
  } from "./mlflow.ts";
146
149
  import { resolveDefaultModelId, withSmartRouterEndpoint } from "./model.ts";
147
150
  import { buildObservability, configureOtelPropagation } from "./observability.ts";
@@ -1025,7 +1028,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1025
1028
  res.json({ ok: true });
1026
1029
  return;
1027
1030
  }
1028
- 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);
1029
1033
  if (!result.ok) {
1030
1034
  this.sendFailure(res, result, "feedback", "Feedback could not be recorded");
1031
1035
  return;
@@ -1047,11 +1051,33 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1047
1051
  path: MASTRA_ROUTES.mlflowExperiment,
1048
1052
  handler: async (req, res) => {
1049
1053
  if (!this.feedbackEnabled("mlflow")) {
1050
- res.json({ url: null });
1054
+ res.json({ url: null, tracePrefix: null });
1051
1055
  return;
1052
1056
  }
1053
- const result = await this.scopedSelf(req).fetchMlflowExperimentUrl(requestUserEmail(req));
1054
- 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
+ });
1055
1081
  },
1056
1082
  });
1057
1083
  }
@@ -1181,22 +1207,24 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1181
1207
 
1182
1208
  /**
1183
1209
  * Implementation backing the `/route/feedback` route. Runs inside the
1184
- * AppKit user-context proxy so `getExecutionContext()` returns the
1185
- * OBO-scoped client and the assessment is attributed to the signed-in
1186
- * 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
1187
1213
  * created assessment id on success, or `undefined` on a soft failure
1188
1214
  * (see {@link logFeedback} in `./mlflow.js`).
1189
1215
  */
1190
1216
  private async logFeedback(
1191
1217
  feedback: MlflowFeedbackRequest,
1218
+ attributedSourceId?: string,
1192
1219
  ): Promise<ExecutionResult<string | undefined>> {
1193
1220
  const ctx = getExecutionContext();
1194
1221
  const sourceId =
1195
- "userEmail" in ctx && ctx.userEmail
1222
+ attributedSourceId ??
1223
+ ("userEmail" in ctx && ctx.userEmail
1196
1224
  ? ctx.userEmail
1197
1225
  : "userId" in ctx
1198
1226
  ? ctx.userId
1199
- : ctx.serviceUserId;
1227
+ : ctx.serviceUserId);
1200
1228
  return this.execute(
1201
1229
  () =>
1202
1230
  logFeedback(ctx.client, {
@@ -1231,16 +1259,27 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1231
1259
 
1232
1260
  /**
1233
1261
  * Resolve an experiment link under the active request identity. The helper
1234
- * returns no URL unless the viewer has effective `CAN_MANAGE` permission.
1262
+ * returns no URL unless the viewer has effective read access.
1235
1263
  */
1236
1264
  private async fetchMlflowExperimentUrl(
1237
- viewerUserName?: string,
1265
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean } = {},
1238
1266
  ): Promise<ExecutionResult<string | undefined>> {
1239
1267
  const client = getExecutionContext().client;
1240
- return this.execute(
1241
- () => mlflowExperimentManagerUrl(client, viewerUserName),
1242
- feedbackWriteDefaults,
1243
- );
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>> {
1281
+ const client = getExecutionContext().client;
1282
+ return this.execute(() => mlflowUcTracePrefix(client), feedbackWriteDefaults);
1244
1283
  }
1245
1284
 
1246
1285
  /**