@dbx-tools/appkit-mastra 0.1.74 → 0.1.75

package/README.md

@@ -13,10 +13,14 @@ is a one-line import change.
 
 The implementation lives under `src/`: agent registration in
 [`agents.ts`](src/agents.ts), the plugin + routes in
-[`plugin.ts`](src/plugin.ts) / [`server.ts`](src/server.ts), Model
-Serving resolution in [`model.ts`](src/model.ts) / [`serving.ts`](src/serving.ts),
-Genie tooling in [`genie.ts`](src/genie.ts), and the chart pipeline in
-[`chart.ts`](src/chart.ts).
+[`plugin.ts`](src/plugin.ts) / [`server.ts`](src/server.ts), thread
+history / listing in [`history.ts`](src/history.ts) /
+[`threads.ts`](src/threads.ts), Model Serving resolution in
+[`model.ts`](src/model.ts) / [`serving.ts`](src/serving.ts), Genie
+tooling in [`genie.ts`](src/genie.ts), the chart pipeline in
+[`chart.ts`](src/chart.ts), and MLflow feedback logging in
+[`mlflow.ts`](src/mlflow.ts) (over the shared REST helper in
+[`rest.ts`](src/rest.ts)).
 
 ## Quick start
 
@@ -267,6 +271,35 @@ entry settles. Cache entries carry a 1h TTL; after expiry the route
 placement contract are in [`chart.ts`](src/chart.ts); the wire shapes
 are in [`@dbx-tools/appkit-mastra-shared`](../appkit-mastra-shared).
 
+## Feedback (MLflow)
+
+When MLflow tracing is wired for the deployment, the plugin lets users
+rate an assistant turn (thumbs up / down) and leave a comment, logged as
+a HUMAN [assessment](https://mlflow.org/docs/latest/genai/assessments/)
+on that turn's trace and attributed to the signed-in (OBO) user.
+
+Enablement is auto-detected: it turns on when an OTLP exporter endpoint
+(`OTEL_EXPORTER_OTLP_ENDPOINT` / `..._TRACES_ENDPOINT`) **and** an MLflow
+experiment (`MLFLOW_EXPERIMENT_ID` / `MLFLOW_EXPERIMENT_NAME`) are
+configured - the two signals that traces actually materialize in MLflow.
+Set `config.feedback` to `true` / `false` to force it on or off
+regardless of the env.
+
+```ts
+mastra({ agents: support, feedback: true }); // force-enable
+```
+
+Under the hood the server derives MLflow's trace id from the active
+OpenTelemetry span (`tr-<hex(otelTraceId)>`) and stamps it on each
+turn's response (`MLFLOW_TRACE_ID_HEADER`); the client sends it back to
+`POST ${basePath}/route/feedback`, which posts the assessment to the
+Databricks MLflow REST API. Trace export is asynchronous, so a
+just-finished trace may not exist yet - the log call retries briefly on
+"not found" and otherwise fails softly (the chat stays usable). The
+current state is published to the client as
+`clientConfig().feedbackEnabled`; see [`mlflow.ts`](src/mlflow.ts) and
+the UI wiring in [`@dbx-tools/appkit-mastra-ui`](../appkit-mastra-ui).
+
 ## Model resolution
 
 Each agent call resolves a model lazily (so concurrent requests keep
@@ -338,6 +371,36 @@ resolves its model and tools as the calling user. The resolved endpoint
 paths are available in-process via
 `appkitUtils.require(this.context, mastra).exports().getMcp()`.
 
+## Client API surface (`apiAccess`)
+
+`@mastra/express` registers its full management route table under the
+plugin mount - agent inference *plus* admin / mutating routes (direct
+tool execution, workflow control, raw memory read/write, telemetry,
+logs, scores). AppKit authenticates every request as the OBO user, but
+does not restrict *which* of those a browser client may call.
+
+`config.apiAccess` gates that surface at the plugin's dispatch point:
+
+- `"scoped"` (default): only the routes the chat client needs are
+  dispatched to Mastra - agent inference (`stream` / `generate` /
+  `network`), read-only agent metadata (`GET /agents`,
+  `GET /agents/:id`), this plugin's own OBO- and resource-scoped
+  `/route/*` routes (history / threads / feedback), and, when `mcp` is
+  enabled, the MCP transport. Everything else is refused with `403`
+  before it reaches Mastra.
+- `"full"`: dispatch the entire stock Mastra API. Use only for a trusted
+  first-party console that genuinely needs the management surface.
+
+```ts
+mastra({ agents: support }); // scoped by default
+mastra({ agents: support, apiAccess: "full" }); // opt into the full API
+```
+
+The gate is a pure allowlist (`isMastraRequestAllowed` in
+[`server.ts`](src/server.ts)); the browser chat client only ever uses
+the agent stream and the `/route/*` routes, so the default breaks
+nothing.
+
 ## License
 
 Apache-2.0

package/dist/index.d.ts

@@ -642,6 +642,28 @@ interface MastraPluginConfig extends BasePluginConfig {
    * calling user.
    */
   mcp?: boolean | MastraMcpConfig;
+  /**
+   * How much of the stock `@mastra/express` management API is reachable
+   * through the plugin mount. `@mastra/express` registers its full route
+   * table (agent inference plus admin / mutating routes: direct tool
+   * execution, workflow control, raw memory read/write, telemetry, logs,
+   * scores). AppKit already authenticates every request as the OBO user,
+   * but nothing there restricts *which* of those operations the browser
+   * client may invoke.
+   *
+   * - `"scoped"` (default): only the routes the chat client legitimately
+   *   needs are dispatched to Mastra - agent inference
+   *   (`stream` / `generate` / `network`), read-only agent metadata, this
+   *   plugin's own OBO- and resource-scoped `/route/*` routes (history /
+   *   threads), and, when {@link mcp} is enabled, the MCP transport.
+   *   Everything else (tool execution, workflow control, raw memory,
+   *   telemetry, logs, scores, and other mutations) is rejected with
+   *   `403` before it reaches Mastra.
+   * - `"full"`: dispatch the entire stock Mastra API. Use only for a
+   *   trusted first-party console that genuinely needs the management
+   *   surface.
+   */
+  apiAccess?: "scoped" | "full";
 }
 //#endregion
 //#region packages/appkit-mastra/src/memory.d.ts
@@ -1310,13 +1332,17 @@ 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.
+   * Whether to stamp the MLflow trace-id header on responses. Shares the
+   * plugin's feedback gate via {@link resolveFeedbackEnabled}.
    */
   private feedbackEnabled;
   constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServer>);
@@ -1486,10 +1512,9 @@ declare class MastraPlugin extends Plugin<MastraPluginConfig> {
   };
   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.
+   * Whether user feedback can be logged to MLflow. Delegates to
+   * {@link resolveFeedbackEnabled} so the client-config flag and the
+   * feedback route share the same gate as the server's trace-id header.
    */
   private feedbackEnabled;
   injectRoutes(router: IAppRouter): void;

package/dist/index.js

@@ -849,8 +849,63 @@ function buildRenderDataTool(config) {
 	});
 }
 
+//#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 } : {}
+	});
+}
+/** Read a response body as text, swallowing read errors (returns `""`). */
+async function readResponseText(res) {
+	try {
+		return await res.text();
+	} catch {
+		return "";
+	}
+}
+/** Parse a response body as JSON, returning `{}` on empty / invalid bodies. */
+async function readResponseJson(res) {
+	const text = await readResponseText(res);
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return {};
+	}
+}
+
 //#endregion
 //#region packages/appkit-mastra/src/connectors/managed-memory/client.ts
+/**
+* Thin REST client over the Databricks Unity Catalog Managed Agent
+* Memory API (Beta). There is no TS SDK for memory-stores yet, so this
+* issues authenticated requests through the shared {@link databricksFetch}
+* primitive (`rest.ts`) as whatever identity the caller's client carries
+* - the per-request OBO user for tools / recall, the service principal
+* for setup-time probes.
+*
+* Responses are parsed defensively: the Beta wire shape may still drift,
+* so the search parser tolerates missing / renamed entry fields and the
+* store probe maps a 404 to `null` rather than throwing.
+*/
 /** Base path for the Unity Catalog memory-stores REST surface. */
 const MEMORY_STORES_PATH = "/api/2.1/unity-catalog/memory-stores";
 /**
@@ -883,32 +938,14 @@ function parseStoreName(fullName) {
 	};
 }
 /**
-* Resolve the workspace host and an authenticated header set off the
-* client, then issue a `fetch`. Returns the raw `Response` so callers
-* decide how to handle status codes (the store probe wants the 404, the
-* mutating calls want a throw).
-*/
-async function rawFetch(client, path, init) {
-	const host = (await client.config.getHost()).toString();
-	const headers = new Headers({ "Content-Type": "application/json" });
-	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 } : {}
-	});
-}
-/**
 * Issue a request and parse the JSON body, throwing
 * {@link ManagedMemoryError} on any non-2xx status. Used by the calls
 * where anything but success is a real error (create / write / search).
 */
 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$1(res));
-	return safeJson$1(res);
+	const res = await databricksFetch(client, path, init);
+	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await readResponseText(res));
+	return readResponseJson(res);
 }
 /**
 * Fetch a store by full name. Returns the raw store payload when it
@@ -917,13 +954,13 @@ async function requestJson(client, path, init) {
 * Any other non-2xx status throws.
 */
 async function getStore(client, fullName, signal) {
-	const res = await rawFetch(client, `${MEMORY_STORES_PATH}/${fullName}`, {
+	const res = await databricksFetch(client, `${MEMORY_STORES_PATH}/${fullName}`, {
 		method: "GET",
 		...signal ? { signal } : {}
 	});
 	if (res.status === 404) return null;
-	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await safeText$1(res));
-	return safeJson$1(res);
+	if (!res.ok) throw new ManagedMemoryError(res.status, res.statusText, await readResponseText(res));
+	return readResponseJson(res);
 }
 /**
 * Probe for the store and create it when missing. Returns `true` when
@@ -990,10 +1027,14 @@ function parseEntries(body) {
 	for (const raw of list) {
 		if (!raw || typeof raw !== "object") continue;
 		const obj = raw;
-		const contents = firstString(obj["contents"], obj["content"], obj["text"]);
+		const contents = stringUtils.firstNonEmpty([
+			obj["contents"],
+			obj["content"],
+			obj["text"]
+		]);
 		if (!contents) continue;
-		const path = firstString(obj["path"]);
-		const description = firstString(obj["description"], obj["summary"]);
+		const path = stringUtils.firstNonEmpty(obj["path"]);
+		const description = stringUtils.firstNonEmpty([obj["description"], obj["summary"]]);
 		const score = typeof obj["score"] === "number" ? obj["score"] : void 0;
 		out.push({
 			contents,
@@ -1004,28 +1045,6 @@ function parseEntries(body) {
 	}
 	return out;
 }
-/** Return the first argument that is a non-empty string, else undefined. */
-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$1(res) {
-	const text = await safeText$1(res);
-	if (!text) return {};
-	try {
-		return JSON.parse(text);
-	} catch {
-		return {};
-	}
-}
-/** Read a response body as text, swallowing read errors. */
-async function safeText$1(res) {
-	try {
-		return await res.text();
-	} catch {
-		return "";
-	}
-}
 
 //#endregion
 //#region packages/appkit-mastra/src/connectors/managed-memory/context.ts
@@ -2898,6 +2917,27 @@ function buildMcpServer(opts) {
 	};
 }
 
+//#endregion
+//#region packages/appkit-mastra/src/pagination.ts
+/** Coerce / clamp a `perPage` value, falling back to `bounds.fallback`. */
+function clampPerPage(value, bounds) {
+	if (value === void 0 || Number.isNaN(value)) return bounds.fallback;
+	const n = Math.trunc(value);
+	if (n <= 0) return bounds.fallback;
+	return Math.min(n, bounds.max);
+}
+/**
+* Coerce a Hono query value into a non-negative integer. Returns
+* `undefined` for empty / non-numeric / negative inputs so the caller
+* can apply its built-in defaults.
+*/
+function parseIntParam(value) {
+	if (!value) return void 0;
+	const n = Number(value);
+	if (!Number.isFinite(n) || n < 0) return void 0;
+	return Math.trunc(n);
+}
+
 //#endregion
 //#region packages/appkit-mastra/src/history.ts
 const log$4 = logUtils.logger("mastra/history");
@@ -2921,7 +2961,10 @@ const MAX_PER_PAGE$1 = 200;
 * without sorting locally.
 */
 async function loadHistory(opts) {
-	const perPage = clampPerPage$1(opts.perPage);
+	const perPage = clampPerPage(opts.perPage, {
+		fallback: DEFAULT_PER_PAGE$1,
+		max: MAX_PER_PAGE$1
+	});
 	const page = Math.max(0, Math.trunc(opts.page ?? 0));
 	const memory = await opts.agent.getMemory();
 	if (!memory) {
@@ -3070,8 +3113,8 @@ function historyRoute(options) {
 				agent: ctx.agent,
 				threadId: ctx.threadId,
 				...ctx.resourceId ? { resourceId: ctx.resourceId } : {},
-				page: parseIntParam$1(c.req.query("page")),
-				perPage: parseIntParam$1(c.req.query("perPage"))
+				page: parseIntParam(c.req.query("page")),
+				perPage: parseIntParam(c.req.query("perPage"))
 			});
 			return c.json(payload);
 		}
@@ -3094,13 +3137,6 @@ function historyRoute(options) {
 		}
 	})];
 }
-/** Coerce / clamp `perPage`; falls back to the page-size default. */
-function clampPerPage$1(value) {
-	if (value === void 0 || Number.isNaN(value)) return DEFAULT_PER_PAGE$1;
-	const n = Math.trunc(value);
-	if (n <= 0) return DEFAULT_PER_PAGE$1;
-	return Math.min(n, MAX_PER_PAGE$1);
-}
 /**
 * Sort messages oldest-first by `createdAt`, falling back to whatever
 * order the storage returned them in. The native `recall` call honors
@@ -3120,155 +3156,6 @@ function toEpoch(value) {
 	}
 	return 0;
 }
-/**
-* Coerce a Hono query value into a non-negative integer. Returns
-* `undefined` for empty / non-numeric / negative inputs so
-* {@link loadHistory} can apply its built-in defaults.
-*/
-function parseIntParam$1(value) {
-	if (!value) return void 0;
-	const n = Number(value);
-	if (!Number.isFinite(n) || n < 0) return void 0;
-	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
@@ -3300,7 +3187,7 @@ async function safeText(res) {
 * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
 * is registered); per-agent settings cascade on top of that.
 */
-const log$2 = logUtils.logger("mastra/memory");
+const log$3 = logUtils.logger("mastra/memory");
 /**
 * Build a dedicated **service-principal** Lakebase pool for Mastra
 * memory from the lakebase plugin's resolved SP pg config.
@@ -3392,10 +3279,10 @@ var MemoryBuilder = class {
 		const storage = this.buildStorage(agentId, storageSetting);
 		const vector = this.buildVector(memorySetting);
 		if (!storage && !vector) {
-			log$2.debug("agent:stateless", { agentId });
+			log$3.debug("agent:stateless", { agentId });
 			return;
 		}
-		log$2.debug("agent:configured", {
+		log$3.debug("agent:configured", {
 			agentId,
 			storage: storage !== void 0,
 			vector: vector !== void 0,
@@ -3507,6 +3394,110 @@ function withId(value, fallback) {
 	};
 }
 
+//#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$2 = 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;
+}
+/**
+* Resolve whether user feedback is enabled from the plugin's optional
+* `config.feedback` override: the explicit boolean wins, otherwise fall
+* back to auto-detecting MLflow tracing ({@link mlflowEnabled}). Shared
+* by the plugin's client-config gate and the server's trace-id header so
+* the two never disagree.
+*/
+function resolveFeedbackEnabled(explicit) {
+	return explicit ?? mlflowEnabled();
+}
+/**
+* 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$2.warn("feedback request failed", {
+				traceId: params.traceId,
+				error: commonUtils.errorMessage(err)
+			});
+			return;
+		}
+		if (res.ok) {
+			const parsed = await readResponseJson(res);
+			const assessmentId = parsed?.assessment?.assessment_id ?? parsed?.assessment_id;
+			return typeof assessmentId === "string" ? assessmentId : "";
+		}
+		if (res.status === 404 && attempt < NOT_FOUND_RETRIES) {
+			await commonUtils.sleep(NOT_FOUND_BACKOFF_MS * (attempt + 1));
+			continue;
+		}
+		log$2.warn("feedback not recorded", {
+			traceId: params.traceId,
+			status: res.status,
+			body: await readResponseText(res)
+		});
+		return;
+	}
+}
+
 //#endregion
 //#region packages/appkit-mastra/src/observability.ts
 /**
@@ -3581,30 +3572,29 @@ async function buildObservability(options) {
 * behind an Express mount point.
 */
 /**
-* `@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`).
-*/
-/**
 * 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);
+/**
+* `@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`).
+*/
 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.
+	* Whether to stamp the MLflow trace-id header on responses. Shares the
+	* plugin's feedback gate via {@link resolveFeedbackEnabled}.
 	*/
 	feedbackEnabled;
 	constructor(config, ...args) {
 		super(...args);
 		this.config = config;
 		this.log = logUtils.logger(config);
-		this.feedbackEnabled = config.feedback ?? mlflowEnabled();
+		this.feedbackEnabled = resolveFeedbackEnabled(config.feedback);
 	}
 	registerAuthMiddleware() {
 		super.registerAuthMiddleware();
@@ -3744,6 +3734,37 @@ var MastraServer$1 = class extends MastraServer {
 	}
 };
 /**
+* Mount-relative agent inference paths (`/agents/:id/<verb>...`). Matched
+* by prefix on the verb so future variants (`streamVNext`, `stream/vnext`,
+* `generateVNext`) stay covered without a code change. These are the only
+* *writes* the browser client is allowed to make against stock Mastra.
+*/
+const AGENT_INFERENCE = /^\/agents\/[^/]+\/(stream|generate|network)/i;
+/** Mount-relative read-only agent metadata (`/agents`, `/agents/:id`). */
+const AGENT_METADATA = /^\/agents(\/[^/]+)?$/;
+/**
+* Whether a request to the stock `@mastra/express` sub-app should be
+* dispatched, given the configured {@link MastraApiGateOptions.access}.
+*
+* `path` is mount-relative (what the plugin's catch-all sees, e.g.
+* `/agents/x/stream`, `/route/history/x`, `/mcp/...`). In `"scoped"`
+* mode the allowlist is deliberately tight - the chat client only ever
+* needs agent inference, read-only agent metadata, this plugin's own
+* OBO/resource-scoped `/route/*` routes, and (when enabled) MCP - so the
+* whole admin / mutating / bulk-export surface Mastra also exposes is
+* denied by default rather than enumerated.
+*/
+function isMastraRequestAllowed(method, path, opts) {
+	if (opts.access === "full") return true;
+	const p = path.startsWith("/") ? path : `/${path}`;
+	if (p === "/route" || p.startsWith("/route/")) return true;
+	if (opts.mcpEnabled && (p === "/mcp" || p.startsWith("/mcp/"))) return true;
+	const m = method.toUpperCase();
+	if (m === "POST" && AGENT_INFERENCE.test(p)) return true;
+	if (m === "GET" && AGENT_METADATA.test(p)) return true;
+	return false;
+}
+/**
 * Patches around `@mastra/express`'s custom-route dispatcher so the
 * plugin's custom API routes (e.g. `historyRoute`) work when
 * `MastraServer` is hosted on an Express subapp mounted under a parent
@@ -3782,7 +3803,10 @@ const MAX_PER_PAGE = 200;
 * empty page so callers don't have to special-case stateless agents.
 */
 async function listThreads(opts) {
-	const perPage = clampPerPage(opts.perPage);
+	const perPage = clampPerPage(opts.perPage, {
+		fallback: DEFAULT_PER_PAGE,
+		max: MAX_PER_PAGE
+	});
 	const page = Math.max(0, Math.trunc(opts.page ?? 0));
 	const memory = await opts.agent.getMemory();
 	if (!memory) {
@@ -3946,24 +3970,6 @@ function toIso(value) {
 	const parsed = new Date(value);
 	return Number.isNaN(parsed.getTime()) ? (/* @__PURE__ */ new Date(0)).toISOString() : parsed.toISOString();
 }
-/** Coerce / clamp `perPage`; falls back to the page-size default. */
-function clampPerPage(value) {
-	if (value === void 0 || Number.isNaN(value)) return DEFAULT_PER_PAGE;
-	const n = Math.trunc(value);
-	if (n <= 0) return DEFAULT_PER_PAGE;
-	return Math.min(n, MAX_PER_PAGE);
-}
-/**
-* Coerce a Hono query value into a non-negative integer. Returns
-* `undefined` for empty / non-numeric / negative inputs so
-* {@link listThreads} can apply its built-in defaults.
-*/
-function parseIntParam(value) {
-	if (!value) return void 0;
-	const n = Number(value);
-	if (!Number.isFinite(n) || n < 0) return void 0;
-	return Math.trunc(n);
-}
 
 //#endregion
 //#region packages/appkit-mastra/src/plugin.ts
@@ -3994,8 +4000,13 @@ function parseIntParam(value) {
 *   Mastra agent routes, the plugin registers `/route/history`
 *   (load + clear a thread's messages), `/route/threads` (list the
 *   caller's conversations + delete one), `/models`, `/suggestions`,
-*   and the generic `/embed/:type/:id` resolver for inline chart /
-*   data markers.
+*   `/route/feedback` (log a thumbs / comment to MLflow when feedback
+*   is enabled), and the generic `/embed/:type/:id` resolver for inline
+*   chart / data markers. The stock `@mastra/express` surface is gated
+*   by `config.apiAccess` (default `"scoped"`): only agent inference,
+*   read-only agent metadata, the `/route/*` routes, and (when enabled)
+*   MCP are dispatched to Mastra; admin / mutating / bulk-export routes
+*   are refused with `403`. See {@link isMastraRequestAllowed}.
 * - MCP: opt in with `config.mcp` to expose the agents (and optionally
 *   tools) as a Mastra `MCPServer`. It is registered on the `Mastra`
 *   instance via `mcpServers`, so `@mastra/express` serves the stock
@@ -4116,13 +4127,12 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 		};
 	}
 	/**
-	* 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.
+	* Whether user feedback can be logged to MLflow. Delegates to
+	* {@link resolveFeedbackEnabled} so the client-config flag and the
+	* feedback route share the same gate as the server's trace-id header.
 	*/
 	feedbackEnabled() {
-		return this.config.feedback ?? mlflowEnabled();
+		return resolveFeedbackEnabled(this.config.feedback);
 	}
 	injectRoutes(router) {
 		router.get(MASTRA_ROUTES.models, (req, res, next) => {
@@ -4196,6 +4206,13 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 		});
 		router.use((req, res, next) => {
 			if (!this.mastraApp) return res.status(503).end();
+			if (!isMastraRequestAllowed(req.method, req.path, {
+				access: this.config.apiAccess ?? "scoped",
+				mcpEnabled: Boolean(this.config.mcp)
+			})) {
+				res.status(403).json({ error: "Endpoint not exposed to the client (apiAccess=scoped)" });
+				return;
+			}
 			return this.userScopedSelf(req).dispatchMastra(req, res, next);
 		});
 	}
@@ -4402,6 +4419,7 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 				"/route/threads",
 				"/models",
 				"/suggestions",
+				"/route/feedback",
 				"/embed/:type/:id"
 			],
 			instanceStorage: instanceStorage !== void 0,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.74",
+  "version": "0.1.75",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@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",
+    "@dbx-tools/appkit-mastra-shared": "0.1.75",
+    "@dbx-tools/genie": "0.1.75",
+    "@dbx-tools/genie-shared": "0.1.75",
+    "@dbx-tools/model": "0.1.75",
+    "@dbx-tools/shared": "0.1.75",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",