@dbx-tools/appkit-mastra 0.1.73 → 0.1.74

package/dist/index.d.ts

@@ -599,6 +599,24 @@ interface MastraPluginConfig extends BasePluginConfig {
    * to drill deep into a dataset within a single turn.
    */
   agentMaxSteps?: number;
+  /**
+   * Log user feedback (thumbs up/down + freeform comments) to MLflow as
+   * trace assessments, and surface the feedback controls in the chat UI.
+   *
+   * - `undefined` (default, auto): enabled only when MLflow tracing is
+   *   wired - an OTLP exporter endpoint is set and an MLflow experiment
+   *   is named (the same signals the observability pipeline needs to
+   *   ship traces to MLflow). Otherwise off, since there'd be no trace
+   *   to attach feedback to.
+   * - `true`: force on. Feedback controls show and writes are attempted
+   *   regardless of env detection (use when the env is configured in a
+   *   way the auto-probe doesn't recognize).
+   * - `false`: force off. No trace-id header, no feedback route, no UI.
+   *
+   * Feedback attaches to a turn's MLflow trace via the OpenTelemetry
+   * trace id the server stamps on each response; see `mlflow.ts`.
+   */
+  feedback?: boolean;
   /**
    * Expose the plugin's agents (and optionally tools) as a Mastra MCP
    * server so external MCP clients - Claude Desktop, Cursor, the Mastra
@@ -1292,14 +1310,15 @@ declare function buildMcpServer(opts: {
 }): ResolvedMcp | null;
 //#endregion
 //#region packages/appkit-mastra/src/server.d.ts
-/**
- * `@mastra/express` subclass that stamps `RequestContext` with the
- * AppKit user, resource id, and a thread id backed by an HTTP-only
- * session cookie (`appkit_<plugin-name>_session_id`).
- */
 declare class MastraServer$1 extends MastraServer {
   private config;
   private log;
+  /**
+   * Whether to stamp the MLflow trace-id header on responses. Mirrors
+   * the plugin's feedback gate: the explicit `config.feedback` override
+   * wins, else auto-detect from the MLflow tracing env.
+   */
+  private feedbackEnabled;
   constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServer>);
   registerAuthMiddleware(): void;
   configureRequestContextUser(requestContext: RequestContext): void;
@@ -1315,6 +1334,20 @@ declare class MastraServer$1 extends MastraServer {
    * response header so dev tools can copy it from either side.
    */
   configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  /**
+   * Stamp the turn's MLflow trace id on the response so the chat client
+   * can attach thumbs / comment feedback to it later. MLflow derives
+   * its trace id from the OpenTelemetry trace id (`tr-<hex>`), and every
+   * Mastra span for this request inherits the ambient OTel context (see
+   * `observability.ts`), so the active span's trace id here is the id
+   * MLflow will record for the turn.
+   *
+   * No-op unless feedback is enabled, and when no live OTel span is
+   * active (e.g. the OTLP SDK isn't registered): in that case the header
+   * is simply absent and the client hides feedback for that message,
+   * degrading gracefully rather than emitting a bogus trace id.
+   */
+  configureMlflowTraceId(res: express.Response): void;
   /**
    * Resolve the thread id this request targets and pin it on
    * `RequestContext` (consumed by the agent stream for persistence and
@@ -1452,6 +1485,13 @@ declare class MastraPlugin extends Plugin<MastraPluginConfig> {
     clearModelsCache: (host?: string) => Promise<void>;
   };
   clientConfig(): Record<string, unknown>;
+  /**
+   * Whether user feedback can be logged to MLflow. The explicit
+   * `config.feedback` override wins; otherwise auto-detect from the
+   * MLflow tracing env ({@link mlflowEnabled}). Gates both the client
+   * config flag and the feedback route so the two never disagree.
+   */
+  private feedbackEnabled;
   injectRoutes(router: IAppRouter): void;
   /**
    * Invoke the Mastra express sub-app. Exists as a method (instead of reading
@@ -1472,6 +1512,15 @@ declare class MastraPlugin extends Plugin<MastraPluginConfig> {
    * shows a bare empty state instead of built-in example prompts.
    */
   private fetchSuggestions;
+  /**
+   * Implementation backing the `/route/feedback` route. Runs inside the
+   * AppKit user-context proxy so `getExecutionContext()` returns the
+   * OBO-scoped client and the assessment is attributed to the signed-in
+   * user (their email / id as the assessment source). Returns the
+   * created assessment id on success, or `undefined` on a soft failure
+   * (see {@link logFeedback} in `./mlflow.js`).
+   */
+  private logFeedback;
   /**
    * Implementation backing the `data` embed resolver
    * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ChartSchema, ChartTypeSchema, MASTRA_ROUTES, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, THREAD_ID_HEADER, THREAD_ID_QUERY } from "@dbx-tools/appkit-mastra-shared";
+import { ChartSchema, ChartTypeSchema, DEFAULT_COMMENT_NAME, DEFAULT_FEEDBACK_NAME, MASTRA_ROUTES, MLFLOW_TRACE_ID_HEADER, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, MastraFeedbackRequestSchema, THREAD_ID_HEADER, THREAD_ID_QUERY } from "@dbx-tools/appkit-mastra-shared";
 import { DEFAULT_FUZZY_THRESHOLD, DEFAULT_MODEL_CACHE_TTL_MS, FALLBACK_MODEL_IDS, ModelClass, ModelClass as ModelClass$1, clearServingEndpointsCache, listServingEndpoints, parseModelClass, selectModel } from "@dbx-tools/model";
 import { apiUtils, appkitUtils, commonUtils, httpUtils, logUtils, netUtils, projectUtils, stringUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";
@@ -22,6 +22,7 @@ import { Pool } from "pg";
 import { Observability } from "@mastra/observability";
 import { OtelBridge } from "@mastra/otel-bridge";
 import { MastraServer } from "@mastra/express";
+import { trace } from "@opentelemetry/api";
 
 export * from "@dbx-tools/appkit-mastra-shared"
 
@@ -337,7 +338,7 @@ function sanitizeServingMessages(messages) {
 * the demo client and any other UI consumer share the exact same
 * shape this module reads and writes.
 */
-const log$8 = logUtils.logger("mastra/chart");
+const log$9 = logUtils.logger("mastra/chart");
 /**
 * TTL for cached chart entries. One hour balances "long enough for
 * the host UI to fetch the chart well after the model finished
@@ -593,7 +594,7 @@ async function writeChart(entry) {
 		const key = await chartCacheKey(entry.chartId);
 		await CacheManager.getInstanceSync().set(key, entry, { ttl: CHART_CACHE_TTL_SEC });
 	} catch (err) {
-		log$8.warn("write-error", {
+		log$9.warn("write-error", {
 			chartId: entry.chartId,
 			error: commonUtils.errorMessage(err)
 		});
@@ -608,7 +609,7 @@ async function readChart(chartId) {
 		const key = await chartCacheKey(chartId);
 		return await CacheManager.getInstanceSync().get(key) ?? void 0;
 	} catch (err) {
-		log$8.warn("read-error", {
+		log$9.warn("read-error", {
 			chartId,
 			error: commonUtils.errorMessage(err)
 		});
@@ -633,7 +634,7 @@ async function readChart(chartId) {
 async function prepareChart(opts) {
 	const chartId = commonUtils.id();
 	await writeChart({ chartId });
-	log$8.debug("queued", { chartId });
+	log$9.debug("queued", { chartId });
 	runPrepareChart(chartId, opts);
 	return { chartId };
 }
@@ -654,14 +655,14 @@ async function runPrepareChart(chartId, opts) {
 			chartId,
 			result
 		});
-		log$8.info("done", {
+		log$9.info("done", {
 			chartId,
 			chartType: result.chartType,
 			elapsedMs: Date.now() - startedAt
 		});
 	} catch (err) {
 		const error = commonUtils.errorMessage(err);
-		log$8.warn("error", {
+		log$9.warn("error", {
 			chartId,
 			error
 		});
@@ -906,8 +907,8 @@ async function rawFetch(client, path, init) {
 */
 async function requestJson(client, path, init) {
 	const res = await rawFetch(client, path, init);
-	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await safeText(res));
-	return safeJson(res);
+	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await safeText$1(res));
+	return safeJson$1(res);
 }
 /**
 * Fetch a store by full name. Returns the raw store payload when it
@@ -921,8 +922,8 @@ async function getStore(client, fullName, signal) {
 		...signal ? { signal } : {}
 	});
 	if (res.status === 404) return null;
-	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await safeText(res));
-	return safeJson(res);
+	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await safeText$1(res));
+	return safeJson$1(res);
 }
 /**
 * Probe for the store and create it when missing. Returns `true` when
@@ -1008,8 +1009,8 @@ function firstString(...values) {
 	for (const v of values) if (typeof v === "string" && v.trim() !== "") return v;
 }
 /** Parse a response body as JSON, returning `{}` on empty / invalid bodies. */
-async function safeJson(res) {
-	const text = await safeText(res);
+async function safeJson$1(res) {
+	const text = await safeText$1(res);
 	if (!text) return {};
 	try {
 		return JSON.parse(text);
@@ -1018,7 +1019,7 @@ async function safeJson(res) {
 	}
 }
 /** Read a response body as text, swallowing read errors. */
-async function safeText(res) {
+async function safeText$1(res) {
 	try {
 		return await res.text();
 	} catch {
@@ -1084,7 +1085,7 @@ function resolveMemoryContext(requestContext) {
 * failure degrades to a short error string rather than aborting the
 * turn.
 */
-const log$7 = logUtils.logger("mastra/managed-memory/tools");
+const log$8 = logUtils.logger("mastra/managed-memory/tools");
 const saveMemoryInput = z.object({
 	content: z.string().describe("The durable fact or preference to remember."),
 	summary: z.string().optional().describe("Optional one-line summary used to label the memory.")
@@ -1121,10 +1122,10 @@ function buildManagedMemoryTools(runtime) {
 						contents: content,
 						...summary ? { description: summary } : {}
 					});
-					log$7.debug("saved", { scope: ctx.scope });
+					log$8.debug("saved", { scope: ctx.scope });
 					return "Saved to memory.";
 				} catch (err) {
-					log$7.warn("save:error", { error: commonUtils.errorMessage(err) });
+					log$8.warn("save:error", { error: commonUtils.errorMessage(err) });
 					return "Could not save to memory right now.";
 				}
 			}
@@ -1145,7 +1146,7 @@ function buildManagedMemoryTools(runtime) {
 				try {
 					return { memories: (await search(ctx.client, runtime.storeName, ctx.scope, query, runtime.topK)).map(renderEntry) };
 				} catch (err) {
-					log$7.warn("search:error", { error: commonUtils.errorMessage(err) });
+					log$8.warn("search:error", { error: commonUtils.errorMessage(err) });
 					return { memories: [] };
 				}
 			}
@@ -1283,7 +1284,7 @@ async function safeWrite(log, writer, chunk, context = {}) {
 * `instructions` when you want the canonical "how to drive the
 * Genie tools" guidance.
 */
-const log$6 = logUtils.logger("mastra/genie");
+const log$7 = logUtils.logger("mastra/genie");
 /** Default alias used when a single unnamed Genie space is wired up. */
 const DEFAULT_GENIE_ALIAS = "default";
 /**
@@ -1398,7 +1399,7 @@ async function readCachedConversationId(cacheKey) {
 	try {
 		return await CacheManager.getInstanceSync().get(cacheKey) ?? void 0;
 	} catch (err) {
-		log$6.warn("conversation-cache:read-error", { error: commonUtils.errorMessage(err) });
+		log$7.warn("conversation-cache:read-error", { error: commonUtils.errorMessage(err) });
 		return;
 	}
 }
@@ -1414,7 +1415,7 @@ async function saveCachedConversationId(cacheKey, conversationId) {
 	try {
 		await CacheManager.getInstanceSync().set(cacheKey, conversationId, { ttl: CONVERSATION_TTL_SEC });
 	} catch (err) {
-		log$6.warn("conversation-cache:write-error", { error: commonUtils.errorMessage(err) });
+		log$7.warn("conversation-cache:write-error", { error: commonUtils.errorMessage(err) });
 	}
 }
 /** Force-evict a cached conversation id. Used on the stale-id recovery path. */
@@ -1423,7 +1424,7 @@ async function evictCachedConversationId(cacheKey) {
 	try {
 		await CacheManager.getInstanceSync().delete(cacheKey);
 	} catch (err) {
-		log$6.warn("conversation-cache:delete-error", { error: commonUtils.errorMessage(err) });
+		log$7.warn("conversation-cache:delete-error", { error: commonUtils.errorMessage(err) });
 	}
 }
 /**
@@ -1537,7 +1538,7 @@ function buildAskGenieTool(opts) {
 			if (trimmed.length === 0 || PLACEHOLDER_QUESTIONS.has(trimmed.toLowerCase())) throw new Error(`${toolId}: refusing placeholder question "${question}" - call ${toolId} only with a real natural-language question, or skip the call entirely`);
 			const cacheKey = await conversationCacheKey(spaceId, threadId);
 			await ensureConversationSeeded(requestContext, spaceId, cacheKey);
-			await safeWrite(log$6, writer, {
+			await safeWrite(log$7, writer, {
 				type: "started",
 				spaceId,
 				content: question
@@ -1550,7 +1551,7 @@ function buildAskGenieTool(opts) {
 					...seedConversationId ? { conversationId: seedConversationId } : {},
 					...signal ? { context: signal } : {}
 				})) {
-					if (event.type !== "message") await safeWrite(log$6, writer, event);
+					if (event.type !== "message") await safeWrite(log$7, writer, event);
 					const eventConversationId = event.conversation_id;
 					if (eventConversationId) writeContextConversationId(requestContext, spaceId, eventConversationId);
 					if (event.type === "result") finalMessage = event.message;
@@ -1564,7 +1565,7 @@ function buildAskGenieTool(opts) {
 			} catch (err) {
 				const seeded = readContextConversationId(requestContext, spaceId);
 				if (seeded && apiUtils.isNotFoundError(err)) {
-					log$6.warn("conversation-cache:stale, resetting", {
+					log$7.warn("conversation-cache:stale, resetting", {
 						spaceId,
 						conversationId: seeded,
 						error: commonUtils.errorMessage(err)
@@ -2049,7 +2050,7 @@ async function collectSpaceSuggestions(opts) {
 			}));
 			writeSuggestionCache(spaceId, questions);
 		} catch (err) {
-			log$6.warn("suggestions:fetch-error", {
+			log$7.warn("suggestions:fetch-error", {
 				spaceId,
 				error: commonUtils.errorMessage(err)
 			});
@@ -2110,7 +2111,7 @@ var ResultProcessor = class {
 * query, or any REST failure the processor passes the messages through
 * unchanged so a recall hiccup never blocks the conversation.
 */
-const log$5 = logUtils.logger("mastra/processor/managed-memory-recall");
+const log$6 = logUtils.logger("mastra/processor/managed-memory-recall");
 /**
 * Build the recall processor bound to a managed-memory runtime. Created
 * once at setup (when managed memory is active) and wired onto every
@@ -2129,7 +2130,7 @@ function buildManagedMemoryRecallProcessor(runtime) {
 				const entries = await search(ctx.client, runtime.storeName, ctx.scope, query, runtime.topK, args.abortSignal);
 				if (entries.length === 0) return args.messages;
 				const block = ["Relevant memories about the user (from long-term memory):", ...entries.map((e) => `- ${renderEntry(e)}`)].join("\n");
-				log$5.debug("recalled", {
+				log$6.debug("recalled", {
 					scope: ctx.scope,
 					entries: entries.length
 				});
@@ -2141,7 +2142,7 @@ function buildManagedMemoryRecallProcessor(runtime) {
 					}]
 				};
 			} catch (err) {
-				log$5.warn("recall:error", { error: commonUtils.errorMessage(err) });
+				log$6.warn("recall:error", { error: commonUtils.errorMessage(err) });
 				return args.messages;
 			}
 		}
@@ -2191,7 +2192,7 @@ function latestUserText(messages) {
 * legacy `datasets[].chartId` payloads uniformly without coupling
 * to specific tool ids.
 */
-const log$4 = logUtils.logger("mastra/processor/strip-stale-charts");
+const log$5 = logUtils.logger("mastra/processor/strip-stale-charts");
 /**
 * Recursively clone `value`, omitting any property whose key is
 * `chartId`. Arrays are mapped element-wise; primitives are
@@ -2239,7 +2240,7 @@ const stripStaleChartsProcessor = {
 				}
 			}
 		}
-		if (stripped > 0) log$4.debug("stripped", { results: stripped });
+		if (stripped > 0) log$5.debug("stripped", { results: stripped });
 		return args.messages;
 	}
 };
@@ -2899,7 +2900,7 @@ function buildMcpServer(opts) {
 
 //#endregion
 //#region packages/appkit-mastra/src/history.ts
-const log$3 = logUtils.logger("mastra/history");
+const log$4 = logUtils.logger("mastra/history");
 /** Default history page size; matches the Mastra storage default. */
 const DEFAULT_PER_PAGE$1 = 20;
 /** Hard cap so a misbehaving client can't fetch the whole thread at once. */
@@ -2924,7 +2925,7 @@ async function loadHistory(opts) {
 	const page = Math.max(0, Math.trunc(opts.page ?? 0));
 	const memory = await opts.agent.getMemory();
 	if (!memory) {
-		log$3.debug("recall:no-memory", {
+		log$4.debug("recall:no-memory", {
 			agentId: opts.agent.id,
 			threadId: opts.threadId
 		});
@@ -2948,7 +2949,7 @@ async function loadHistory(opts) {
 		}
 	});
 	const uiMessages = toAISdkV5Messages(sortChronological(result.messages));
-	log$3.debug("recall:done", {
+	log$4.debug("recall:done", {
 		agentId: opts.agent.id,
 		threadId: opts.threadId,
 		page,
@@ -2982,7 +2983,7 @@ async function loadHistory(opts) {
 async function clearHistory(opts) {
 	const memory = await opts.agent.getMemory();
 	if (!memory) {
-		log$3.debug("clear:no-memory", {
+		log$4.debug("clear:no-memory", {
 			agentId: opts.agent.id,
 			threadId: opts.threadId
 		});
@@ -2996,7 +2997,7 @@ async function clearHistory(opts) {
 			perPage: 1
 		})).total;
 	} catch (err) {
-		log$3.debug("clear:probe-failed", {
+		log$4.debug("clear:probe-failed", {
 			agentId: opts.agent.id,
 			threadId: opts.threadId,
 			error: commonUtils.errorMessage(err)
@@ -3006,13 +3007,13 @@ async function clearHistory(opts) {
 	try {
 		await memory.deleteThread(opts.threadId);
 	} catch (err) {
-		log$3.warn("clear:delete-soft-failed", {
+		log$4.warn("clear:delete-soft-failed", {
 			agentId: opts.agent.id,
 			threadId: opts.threadId,
 			error: commonUtils.errorMessage(err)
 		});
 	}
-	log$3.info("clear:done", {
+	log$4.info("clear:done", {
 		agentId: opts.agent.id,
 		threadId: opts.threadId,
 		cleared,
@@ -3131,6 +3132,144 @@ function parseIntParam$1(value) {
 	return Math.trunc(n);
 }
 
+//#endregion
+//#region packages/appkit-mastra/src/rest.ts
+/**
+* Resolve the workspace host + an authenticated header set off the
+* client and issue a `fetch` against `path` (mounted on the host).
+* Runs as whatever identity the client carries - the per-request OBO
+* user when called from a request scope, the service principal
+* otherwise.
+*/
+async function databricksFetch(client, path, init) {
+	const host = (await client.config.getHost()).toString();
+	const headers = new Headers({
+		"Content-Type": "application/json",
+		...init.headers
+	});
+	await client.config.authenticate(headers);
+	const url = new URL(path, host).toString();
+	return fetch(url, {
+		method: init.method,
+		headers,
+		...init.body !== void 0 ? { body: JSON.stringify(init.body) } : {},
+		...init.signal ? { signal: init.signal } : {}
+	});
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/mlflow.ts
+/**
+* MLflow user-feedback logging: detect whether MLflow tracing is wired
+* for this deployment, and log a thumbs / comment as a trace
+* *assessment* via the Databricks MLflow REST API.
+*
+* Feedback attaches to a trace, and the plugin's spans reach MLflow
+* through the same OTel pipeline as every other AppKit span (see
+* `observability.ts`). MLflow derives its trace id from the OpenTelemetry
+* trace id (`tr-<hex(otelTraceId)>`), so the server stamps the active
+* trace id on each turn's response and the client sends it back here.
+*
+* There is no MLflow JS SDK, so this posts to the assessments REST
+* endpoint directly using the OBO-scoped workspace client (the feedback
+* is thus attributed to the signed-in user). Trace export is
+* asynchronous, so the just-finished trace may not exist in MLflow yet
+* when the user reacts; the log call retries briefly on "not found"
+* before giving up softly.
+*/
+const log$3 = logUtils.logger("mastra/mlflow");
+/** Assessments REST path for a trace. `3.0` is the current MLflow API version. */
+const assessmentsPath = (traceId) => `/api/3.0/mlflow/traces/${encodeURIComponent(traceId)}/assessments`;
+/** Number of times to retry a "trace not found" response before giving up. */
+const NOT_FOUND_RETRIES = 3;
+/** Base backoff between "trace not found" retries, in ms (grows linearly). */
+const NOT_FOUND_BACKOFF_MS = 1200;
+/**
+* Whether MLflow feedback logging is available for this deployment.
+*
+* Enabled when an OTLP exporter endpoint is configured (traces are
+* actually shipped somewhere) AND an MLflow experiment is named - the
+* two signals that the OTLP backend is MLflow and traces will
+* materialize there. Both are standard env vars, so no plugin config is
+* required; a deployment opts in simply by wiring MLflow tracing.
+*/
+function mlflowEnabled() {
+	const hasExporter = Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim());
+	const hasExperiment = Boolean(process.env.MLFLOW_EXPERIMENT_ID?.trim() || process.env.MLFLOW_EXPERIMENT_NAME?.trim());
+	return hasExporter && hasExperiment;
+}
+/**
+* Log a HUMAN feedback assessment to a trace. Returns the created
+* assessment id on success, or `undefined` when the trace can't be
+* found (even after retrying for export lag) or the request otherwise
+* fails - callers surface that as a soft "not recorded" rather than an
+* error, keeping the chat usable.
+*/
+async function logFeedback(client, params) {
+	const hasValue = params.value !== void 0;
+	const name = params.name?.trim() || (hasValue ? DEFAULT_FEEDBACK_NAME : DEFAULT_COMMENT_NAME);
+	const value = hasValue ? params.value : params.comment;
+	const body = { assessment: {
+		trace_id: params.traceId,
+		assessment_name: name,
+		source: {
+			source_type: "HUMAN",
+			source_id: params.sourceId?.trim() || "user"
+		},
+		feedback: { value },
+		...hasValue && params.comment?.trim() ? { rationale: params.comment } : {}
+	} };
+	for (let attempt = 0; attempt <= NOT_FOUND_RETRIES; attempt++) {
+		let res;
+		try {
+			res = await databricksFetch(client, assessmentsPath(params.traceId), {
+				method: "POST",
+				body
+			});
+		} catch (err) {
+			log$3.warn("feedback request failed", {
+				traceId: params.traceId,
+				error: commonUtils.errorMessage(err)
+			});
+			return;
+		}
+		if (res.ok) {
+			const parsed = await safeJson(res);
+			const assessmentId = parsed?.assessment?.assessment_id ?? parsed?.assessment_id;
+			return typeof assessmentId === "string" ? assessmentId : "";
+		}
+		if (res.status === 404 && attempt < NOT_FOUND_RETRIES) {
+			await delay(NOT_FOUND_BACKOFF_MS * (attempt + 1));
+			continue;
+		}
+		log$3.warn("feedback not recorded", {
+			traceId: params.traceId,
+			status: res.status,
+			body: await safeText(res)
+		});
+		return;
+	}
+}
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function safeJson(res) {
+	const text = await safeText(res);
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return {};
+	}
+}
+async function safeText(res) {
+	try {
+		return await res.text();
+	} catch {
+		return "";
+	}
+}
+
 //#endregion
 //#region packages/appkit-mastra/src/memory.ts
 /**
@@ -3446,12 +3585,26 @@ async function buildObservability(options) {
 * AppKit user, resource id, and a thread id backed by an HTTP-only
 * session cookie (`appkit_<plugin-name>_session_id`).
 */
+/**
+* OpenTelemetry's sentinel for "no valid trace" - 32 zero hex chars.
+* `trace.getActiveSpan()` returns a non-recording span with this id
+* when no SDK is registered, which must never be surfaced as a trace to
+* attach feedback to.
+*/
+const INVALID_TRACE_ID = "0".repeat(32);
 var MastraServer$1 = class extends MastraServer {
 	log;
+	/**
+	* Whether to stamp the MLflow trace-id header on responses. Mirrors
+	* the plugin's feedback gate: the explicit `config.feedback` override
+	* wins, else auto-detect from the MLflow tracing env.
+	*/
+	feedbackEnabled;
 	constructor(config, ...args) {
 		super(...args);
 		this.config = config;
 		this.log = logUtils.logger(config);
+		this.feedbackEnabled = config.feedback ?? mlflowEnabled();
 	}
 	registerAuthMiddleware() {
 		super.registerAuthMiddleware();
@@ -3461,6 +3614,7 @@ var MastraServer$1 = class extends MastraServer {
 			this.configureRequestContextThreadId(req, res, requestContext);
 			this.configureRequestContextModelOverride(req, requestContext);
 			this.configureRequestContextRequestId(req, res, requestContext);
+			this.configureMlflowTraceId(res);
 			this.log.debug("auth:middleware", {
 				method: req.method,
 				path: req.path,
@@ -3507,6 +3661,25 @@ var MastraServer$1 = class extends MastraServer {
 		res.setHeader("X-Request-Id", requestId);
 	}
 	/**
+	* Stamp the turn's MLflow trace id on the response so the chat client
+	* can attach thumbs / comment feedback to it later. MLflow derives
+	* its trace id from the OpenTelemetry trace id (`tr-<hex>`), and every
+	* Mastra span for this request inherits the ambient OTel context (see
+	* `observability.ts`), so the active span's trace id here is the id
+	* MLflow will record for the turn.
+	*
+	* No-op unless feedback is enabled, and when no live OTel span is
+	* active (e.g. the OTLP SDK isn't registered): in that case the header
+	* is simply absent and the client hides feedback for that message,
+	* degrading gracefully rather than emitting a bogus trace id.
+	*/
+	configureMlflowTraceId(res) {
+		if (!this.feedbackEnabled || res.headersSent) return;
+		const traceId = trace.getActiveSpan()?.spanContext().traceId;
+		if (!traceId || traceId === INVALID_TRACE_ID) return;
+		res.setHeader(MLFLOW_TRACE_ID_HEADER, `tr-${traceId}`);
+	}
+	/**
 	* Resolve the thread id this request targets and pin it on
 	* `RequestContext` (consumed by the agent stream for persistence and
 	* by the history / threads routes). Resolution order:
@@ -3938,9 +4111,19 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 		return {
 			basePath: `/api/${this.name}`,
 			defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
-			agents: Object.keys(this.built?.agents ?? {})
+			agents: Object.keys(this.built?.agents ?? {}),
+			feedbackEnabled: this.feedbackEnabled()
 		};
 	}
+	/**
+	* Whether user feedback can be logged to MLflow. The explicit
+	* `config.feedback` override wins; otherwise auto-detect from the
+	* MLflow tracing env ({@link mlflowEnabled}). Gates both the client
+	* config flag and the feedback route so the two never disagree.
+	*/
+	feedbackEnabled() {
+		return this.config.feedback ?? mlflowEnabled();
+	}
 	injectRoutes(router) {
 		router.get(MASTRA_ROUTES.models, (req, res, next) => {
 			this.userScopedSelf(req).listModels().then((endpoints) => res.json({ endpoints })).catch(next);
@@ -3993,6 +4176,24 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 		};
 		router.get(MASTRA_ROUTES.suggestions, handleSuggestions);
 		router.get(`${MASTRA_ROUTES.suggestions}/:agentId`, handleSuggestions);
+		router.post(MASTRA_ROUTES.feedback, (req, res, next) => {
+			if (!this.feedbackEnabled()) {
+				res.status(404).json({ ok: false });
+				return;
+			}
+			const parsed = MastraFeedbackRequestSchema.safeParse(req.body);
+			if (!parsed.success) {
+				res.status(400).json({
+					ok: false,
+					error: parsed.error.message
+				});
+				return;
+			}
+			this.userScopedSelf(req).logFeedback(parsed.data).then((assessmentId) => res.json({
+				ok: assessmentId !== void 0,
+				...assessmentId ? { assessmentId } : {}
+			})).catch(next);
+		});
 		router.use((req, res, next) => {
 			if (!this.mastraApp) return res.status(503).end();
 			return this.userScopedSelf(req).dispatchMastra(req, res, next);
@@ -4029,6 +4230,22 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 		});
 	}
 	/**
+	* Implementation backing the `/route/feedback` route. Runs inside the
+	* AppKit user-context proxy so `getExecutionContext()` returns the
+	* OBO-scoped client and the assessment is attributed to the signed-in
+	* user (their email / id as the assessment source). Returns the
+	* created assessment id on success, or `undefined` on a soft failure
+	* (see {@link logFeedback} in `./mlflow.js`).
+	*/
+	async logFeedback(feedback) {
+		const ctx = getExecutionContext();
+		const sourceId = "userEmail" in ctx && ctx.userEmail ? ctx.userEmail : "userId" in ctx ? ctx.userId : ctx.serviceUserId;
+		return logFeedback(ctx.client, {
+			...feedback,
+			...sourceId ? { sourceId } : {}
+		});
+	}
+	/**
 	* Implementation backing the `data` embed resolver
 	* (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so
 	* `getExecutionContext()` returns the OBO-scoped workspace

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.73",
+  "version": "0.1.74",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@dbx-tools/appkit-mastra-shared": "0.1.73",
-    "@dbx-tools/genie": "0.1.73",
-    "@dbx-tools/genie-shared": "0.1.73",
-    "@dbx-tools/model": "0.1.73",
-    "@dbx-tools/shared": "0.1.73",
+    "@dbx-tools/appkit-mastra-shared": "0.1.74",
+    "@dbx-tools/genie": "0.1.74",
+    "@dbx-tools/genie-shared": "0.1.74",
+    "@dbx-tools/model": "0.1.74",
+    "@dbx-tools/shared": "0.1.74",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",
@@ -17,6 +17,7 @@
     "@mastra/observability": "^1",
     "@mastra/otel-bridge": "^1",
     "@mastra/pg": "^1",
+    "@opentelemetry/api": "^1.9.0",
     "pg": "^8.20.0",
     "zod": "^4.3.6"
   },