@dbx-tools/appkit-mastra 0.9.181 → 0.9.184

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/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,43 @@ 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(client: WorkspaceClient): Promise<string | undefined> {
235
+ try {
236
+ return await resolveUcTracePrefix(client);
237
+ } catch {
238
+ return undefined;
239
+ }
240
+ }
241
+
242
+ /** V3 assessments REST path for an experiment-store trace. */
234
243
  const assessmentsPath = (traceId: string): string =>
235
244
  `/api/3.0/mlflow/traces/${encodeURIComponent(traceId)}/assessments`;
236
245
 
246
+ interface UcTraceLocation {
247
+ catalog: string;
248
+ schema: string;
249
+ tablePrefix: string;
250
+ location: string;
251
+ }
252
+
253
+ function ucTraceLocation(prefix: string | undefined): UcTraceLocation | undefined {
254
+ const parts = normalizeUcPrefix(prefix)?.split(".");
255
+ if (!parts || parts.length < 3) return undefined;
256
+ const [catalog, schema, ...tablePrefixParts] = parts;
257
+ const tablePrefix = tablePrefixParts.join(".");
258
+ if (!catalog || !schema || !tablePrefix) return undefined;
259
+ return { catalog, schema, tablePrefix, location: parts.join(".") };
260
+ }
261
+
262
+ function ucAssessmentsPath(location: string, traceId: string): string {
263
+ const warehouseId =
264
+ process.env.MLFLOW_TRACING_SQL_WAREHOUSE_ID?.trim() ||
265
+ process.env.DATABRICKS_WAREHOUSE_ID?.trim();
266
+ const path = `/api/4.0/mlflow/traces/${encodeURIComponent(location)}/${encodeURIComponent(traceId)}/assessments`;
267
+ return warehouseId ? `${path}?sql_warehouse_id=${encodeURIComponent(warehouseId)}` : path;
268
+ }
269
+
237
270
  /** Number of times to retry a "trace not found" response before giving up. */
238
271
  const NOT_FOUND_RETRIES = 3;
239
272
  /** Base backoff between "trace not found" retries, in ms (grows linearly). */
@@ -289,6 +322,16 @@ const CurrentUserResponseSchema = z
289
322
  .passthrough()
290
323
  .describe("Databricks Current User API response.");
291
324
 
325
+ const ScimUsersResponseSchema = z
326
+ .object({
327
+ Resources: z
328
+ .array(CurrentUserResponseSchema)
329
+ .optional()
330
+ .describe("Workspace users matching the SCIM filter."),
331
+ })
332
+ .passthrough()
333
+ .describe("Databricks SCIM user search response.");
334
+
292
335
  const ExperimentPermissionsResponseSchema = z
293
336
  .object({
294
337
  access_control_list: z
@@ -625,16 +668,37 @@ export function mlflowEnabled(): boolean {
625
668
 
626
669
  /**
627
670
  * Return the configured experiment URL only when the active Databricks
628
- * principal has effective `CAN_MANAGE` permission. Permission lookup is
671
+ * viewer has effective read access. Permission lookup is
629
672
  * intentionally best-effort so Apps environments that do not expose the
630
673
  * required APIs simply omit the debug affordance.
631
674
  */
632
675
  export async function mlflowExperimentManagerUrl(
633
676
  client: WorkspaceClient,
634
- viewerUserName?: string,
677
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean } = {},
635
678
  ): Promise<string | undefined> {
636
679
  try {
637
- return await resolveMlflowExperimentManagerUrl(client, viewerUserName);
680
+ return await resolveMlflowExperimentManagerUrl(client, viewer);
681
+ } catch {
682
+ return undefined;
683
+ }
684
+ }
685
+
686
+ /**
687
+ * Return the configured experiment URL only when this client can read the
688
+ * experiment itself. Use this with the active user's OBO client so the Debug
689
+ * affordance exactly matches whether that user can open the experiment.
690
+ */
691
+ export async function mlflowExperimentViewerUrl(
692
+ client: WorkspaceClient,
693
+ ): Promise<string | undefined> {
694
+ try {
695
+ const experiment = await fetchExperiment(client);
696
+ if (!experiment) return undefined;
697
+ const host = (await client.config.getHost()).toString();
698
+ return new URL(
699
+ `/ml/experiments/${encodeURIComponent(experiment.experiment_id)}`,
700
+ host,
701
+ ).toString();
638
702
  } catch {
639
703
  return undefined;
640
704
  }
@@ -642,13 +706,23 @@ export async function mlflowExperimentManagerUrl(
642
706
 
643
707
  async function resolveMlflowExperimentManagerUrl(
644
708
  client: WorkspaceClient,
645
- viewerUserName?: string,
709
+ viewer: { userName?: string; userId?: string; workspaceUser?: boolean },
646
710
  ): Promise<string | undefined> {
647
711
  const experimentId = await resolveExperimentId(client);
648
712
  if (!experimentId) return undefined;
649
713
 
714
+ const viewerUserName = viewer.userName?.trim();
715
+ const viewerUserId = viewer.userId?.trim();
716
+ const currentPrincipalPath = viewerUserName
717
+ ? `/api/2.0/preview/scim/v2/Users?filter=${encodeURIComponent(
718
+ `userName eq "${viewerUserName.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`,
719
+ )}`
720
+ : viewerUserId
721
+ ? `/api/2.0/preview/scim/v2/Users/${encodeURIComponent(viewerUserId)}`
722
+ : "/api/2.0/preview/scim/v2/Me";
723
+
650
724
  const [currentResponse, permissionsResponse] = await Promise.all([
651
- databricksFetch(client, "/api/2.0/preview/scim/v2/Me", { method: "GET" }),
725
+ databricksFetch(client, currentPrincipalPath, { method: "GET" }),
652
726
  databricksFetch(
653
727
  client,
654
728
  `/api/2.0/permissions/experiments/${encodeURIComponent(experimentId)}`,
@@ -657,30 +731,44 @@ async function resolveMlflowExperimentManagerUrl(
657
731
  ]);
658
732
  if (!permissionsResponse.ok) return undefined;
659
733
 
660
- const current = currentResponse.ok
661
- ? CurrentUserResponseSchema.safeParse(await readResponseJson(currentResponse))
662
- : undefined;
734
+ let currentUser: z.infer<typeof CurrentUserResponseSchema> | undefined;
735
+ if (currentResponse.ok) {
736
+ const currentRaw = await readResponseJson(currentResponse);
737
+ if (viewerUserName) {
738
+ const users = ScimUsersResponseSchema.safeParse(currentRaw);
739
+ currentUser = users.success
740
+ ? users.data.Resources?.find(
741
+ (candidate) => candidate.userName?.toLowerCase() === viewerUserName.toLowerCase(),
742
+ )
743
+ : undefined;
744
+ } else {
745
+ const current = CurrentUserResponseSchema.safeParse(currentRaw);
746
+ currentUser = current.success ? current.data : undefined;
747
+ }
748
+ }
663
749
  const permissions = ExperimentPermissionsResponseSchema.safeParse(
664
750
  await readResponseJson(permissionsResponse),
665
751
  );
666
- if (!permissions.success || (!viewerUserName && !current?.success)) return undefined;
752
+ const hasForwardedViewer = Boolean(viewerUserName || viewerUserId);
753
+ if (!permissions.success || (!hasForwardedViewer && !currentUser)) return undefined;
667
754
 
668
755
  const userNames = new Set(
669
756
  [
670
757
  viewerUserName,
671
- ...(current?.success
672
- ? [current.data.userName, current.data.applicationId, current.data.displayName]
758
+ ...(currentUser
759
+ ? [currentUser.userName, currentUser.applicationId, currentUser.displayName]
673
760
  : []),
674
761
  ]
675
762
  .map((value) => value?.trim())
676
763
  .filter((value): value is string => Boolean(value)),
677
764
  );
678
765
  const groupNames = new Set(
679
- (current?.success ? (current.data.groups ?? []) : []).flatMap(({ value, display }) =>
766
+ (currentUser?.groups ?? []).flatMap(({ value, display }) =>
680
767
  [value, display].filter((entry): entry is string => Boolean(entry)),
681
768
  ),
682
769
  );
683
- const canManage = (permissions.data.access_control_list ?? []).some((entry) => {
770
+ if (viewer.workspaceUser) groupNames.add("users");
771
+ const canView = (permissions.data.access_control_list ?? []).some((entry) => {
684
772
  const matches =
685
773
  (entry.user_name !== undefined && userNames.has(entry.user_name)) ||
686
774
  (entry.service_principal_name !== undefined && userNames.has(entry.service_principal_name)) ||
@@ -688,11 +776,14 @@ async function resolveMlflowExperimentManagerUrl(
688
776
  return (
689
777
  matches &&
690
778
  (entry.all_permissions ?? []).some(
691
- (permission) => permission.permission_level === "CAN_MANAGE",
779
+ (permission) =>
780
+ permission.permission_level === "CAN_READ" ||
781
+ permission.permission_level === "CAN_EDIT" ||
782
+ permission.permission_level === "CAN_MANAGE",
692
783
  )
693
784
  );
694
785
  });
695
- if (!canManage) return undefined;
786
+ if (!canView) return undefined;
696
787
 
697
788
  const host = (await client.config.getHost()).toString();
698
789
  return new URL(`/ml/experiments/${encodeURIComponent(experimentId)}`, host).toString();
@@ -744,13 +835,27 @@ export async function logFeedback(
744
835
  const hasValue = params.value !== undefined;
745
836
  const name = params.name?.trim() || (hasValue ? DEFAULT_FEEDBACK_NAME : DEFAULT_COMMENT_NAME);
746
837
  const value = hasValue ? params.value : params.comment;
747
- const assessmentTraceId = mlflowAssessmentTraceId(
748
- params.traceId,
749
- await resolveUcTracePrefix(client),
750
- );
838
+ const prefix = await resolveUcTracePrefix(client);
839
+ const location = ucTraceLocation(prefix);
840
+ const rawTraceId = params.traceId.replace(/^tr-/, "");
841
+ const assessmentTraceId = location
842
+ ? mlflowAssessmentTraceId(rawTraceId, location.location)
843
+ : params.traceId;
751
844
  const assessment: Record<string, unknown> = {
752
- trace_id: assessmentTraceId,
845
+ trace_id: location ? rawTraceId : assessmentTraceId,
753
846
  assessment_name: name,
847
+ ...(location
848
+ ? {
849
+ trace_location: {
850
+ type: "UC_TABLE_PREFIX",
851
+ uc_table_prefix: {
852
+ catalog_name: location.catalog,
853
+ schema_name: location.schema,
854
+ table_prefix: location.tablePrefix,
855
+ },
856
+ },
857
+ }
858
+ : {}),
754
859
  source: {
755
860
  source_type: "HUMAN",
756
861
  source_id: params.sourceId?.trim() || "user",
@@ -758,12 +863,22 @@ export async function logFeedback(
758
863
  feedback: { value },
759
864
  ...(hasValue && params.comment?.trim() ? { rationale: params.comment } : {}),
760
865
  };
761
- const body = { assessment };
866
+ const body = location
867
+ ? {
868
+ ...assessment,
869
+ create_time: new Date().toISOString(),
870
+ last_update_time: new Date().toISOString(),
871
+ valid: true,
872
+ }
873
+ : { assessment };
874
+ const path = location
875
+ ? ucAssessmentsPath(location.location, rawTraceId)
876
+ : assessmentsPath(assessmentTraceId);
762
877
 
763
878
  for (let attempt = 0; attempt <= NOT_FOUND_RETRIES; attempt++) {
764
879
  let res: Response;
765
880
  try {
766
- res = await databricksFetch(client, assessmentsPath(assessmentTraceId), {
881
+ res = await databricksFetch(client, path, {
767
882
  method: "POST",
768
883
  body,
769
884
  });
package/src/model.ts CHANGED
@@ -77,10 +77,11 @@ export const SMART_ROUTER_ENDPOINT: ServingEndpointSummary = {
77
77
  status: { deprecated: false },
78
78
  };
79
79
 
80
- /** Keep Responses turns stateless so tool continuations replay encrypted reasoning inline. */
80
+ /** Default Responses options: stateless replay plus visible reasoning summaries. */
81
81
  export const RESPONSES_PROVIDER_OPTIONS = {
82
82
  openai: {
83
83
  store: false,
84
+ reasoningSummary: "auto",
84
85
  },
85
86
  } as const;
86
87
 
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,25 @@ 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<ExecutionResult<string | undefined>> {
1273
+ const client = getExecutionContext().client;
1274
+ return this.execute(() => mlflowExperimentViewerUrl(client), feedbackWriteDefaults);
1275
+ }
1276
+
1277
+ /** Resolve the configured UC trace prefix for an authorized Debug link. */
1278
+ private async fetchMlflowTracePrefix(): Promise<ExecutionResult<string | undefined>> {
1279
+ const client = getExecutionContext().client;
1280
+ return this.execute(() => mlflowUcTracePrefix(client), feedbackWriteDefaults);
1244
1281
  }
1245
1282
 
1246
1283
  /**
@@ -1467,16 +1504,16 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
1467
1504
  this.config,
1468
1505
  { mlflowFeedback: this.feedbackEnabled("mlflow") },
1469
1506
  {
1470
- app: this.mastraApp,
1471
- mastra: this.mastra,
1472
- prefix: "",
1473
- customApiRoutes: [
1474
- ...agentChatRoutes(this.config),
1475
- workflowRoute({
1476
- path: "/route/workflows/:workflowId/stream",
1477
- version: "v7",
1478
- }),
1479
- ],
1507
+ app: this.mastraApp,
1508
+ mastra: this.mastra,
1509
+ prefix: "",
1510
+ customApiRoutes: [
1511
+ ...agentChatRoutes(this.config),
1512
+ workflowRoute({
1513
+ path: "/route/workflows/:workflowId/stream",
1514
+ version: "v7",
1515
+ }),
1516
+ ],
1480
1517
  },
1481
1518
  );
1482
1519
  await this.mastraServer.init();