@dbx-tools/appkit-mastra 0.3.44 → 0.4.1

package/lib/src/processors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Mastra stream processors wired onto the plugin's agents.
+ *
+ * Two complementary processors live here:
+ *
+ * - An **input** processor ({@link stripStaleChartsProcessor}) that
+ *   scrubs turn-scoped `chartId` fields out of prior tool results
+ *   replayed from Memory, so the model can't copy a stale id into the
+ *   new turn's `[chart:<id>]` markers.
+ * - An **output** processor ({@link ResultProcessor}) that trims the
+ *   bulky, redundant payload fields off targeted outbound stream frames
+ *   before they're serialized to the SSE client.
+ *
+ * @module
+ */
+import type { InputProcessor, Processor } from "@mastra/core/processors";
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are turn-scoped from the model's point of view -
+ * each `prepare_chart` / `render_data` call mints a fresh id and
+ * the host UI binds it to that turn's reply. Mastra Memory
+ * replays prior tool results into the prompt; if old chartIds
+ * leak through, the model is tempted to copy them verbatim into
+ * the new turn's `[chart:<id>]` markers and the host UI ends up
+ * rendering an unrelated chart from the chart cache (or
+ * a 404 once the 1h TTL elapsed). This processor removes the
+ * temptation by deleting `chartId` keys from every assistant
+ * message's tool results before the prompt is built. The current
+ * turn's tool results don't exist yet at `processInput` time, so
+ * they pass through unmodified.
+ *
+ * The strip is recursive - any nested `chartId` field is removed,
+ * regardless of which tool produced the result. This covers
+ * `prepare_chart` / `render_data` top-level chartIds and any
+ * legacy `datasets[].chartId` payloads uniformly without coupling
+ * to specific tool ids.
+ *
+ * Wired onto every agent by default via `buildAgents`; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export declare const stripStaleChartsProcessor: InputProcessor;
+/**
+ * Mastra output processor that trims the bulky, redundant payload
+ * fields off targeted outbound stream frames.
+ *
+ * Mastra emits step / finish / tool-result frames whose payloads
+ * echo the full tool `output` / `result` / assistant `messages` /
+ * `response` - data the chat client already received inline and
+ * doesn't need re-sent. This processor empties those keys on the
+ * targeted frame types so the outbound SSE stream stays lean;
+ * every other frame passes through untouched.
+ */
+export declare class ResultProcessor implements Processor {
+    id: string;
+    processDataParts: boolean;
+    processOutputStream({ part }: {
+        part: any;
+    }): Promise<any | null>;
+}

package/lib/src/processors.js

@@ -0,0 +1,162 @@
+/**
+ * Mastra stream processors wired onto the plugin's agents.
+ *
+ * Two complementary processors live here:
+ *
+ * - An **input** processor ({@link stripStaleChartsProcessor}) that
+ *   scrubs turn-scoped `chartId` fields out of prior tool results
+ *   replayed from Memory, so the model can't copy a stale id into the
+ *   new turn's `[chart:<id>]` markers.
+ * - An **output** processor ({@link ResultProcessor}) that trims the
+ *   bulky, redundant payload fields off targeted outbound stream frames
+ *   before they're serialized to the SSE client.
+ *
+ * @module
+ */
+import { log } from "@dbx-tools/shared-core";
+const logger = log.logger("mastra/processors");
+/**
+ * Recursively clone `value`, omitting any property whose key is
+ * `chartId`. Arrays are mapped element-wise; primitives are
+ * returned as-is. The result is structurally identical to the
+ * input minus chartIds, so downstream message-shape consumers
+ * keep working.
+ */
+function stripChartIds(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripChartIds);
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const out = {};
+        for (const [key, val] of Object.entries(obj)) {
+            if (key === "chartId")
+                continue;
+            out[key] = stripChartIds(val);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are turn-scoped from the model's point of view -
+ * each `prepare_chart` / `render_data` call mints a fresh id and
+ * the host UI binds it to that turn's reply. Mastra Memory
+ * replays prior tool results into the prompt; if old chartIds
+ * leak through, the model is tempted to copy them verbatim into
+ * the new turn's `[chart:<id>]` markers and the host UI ends up
+ * rendering an unrelated chart from the chart cache (or
+ * a 404 once the 1h TTL elapsed). This processor removes the
+ * temptation by deleting `chartId` keys from every assistant
+ * message's tool results before the prompt is built. The current
+ * turn's tool results don't exist yet at `processInput` time, so
+ * they pass through unmodified.
+ *
+ * The strip is recursive - any nested `chartId` field is removed,
+ * regardless of which tool produced the result. This covers
+ * `prepare_chart` / `render_data` top-level chartIds and any
+ * legacy `datasets[].chartId` payloads uniformly without coupling
+ * to specific tool ids.
+ *
+ * Wired onto every agent by default via `buildAgents`; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export const stripStaleChartsProcessor = {
+    id: "strip-stale-charts",
+    description: "Removes chartId fields from prior tool-invocation results so the model can't reuse turn-scoped ids from memory.",
+    processInput(args) {
+        let stripped = 0;
+        for (const message of args.messages) {
+            if (message.role !== "assistant")
+                continue;
+            const parts = message.content?.parts;
+            if (!Array.isArray(parts))
+                continue;
+            for (const part of parts) {
+                // Tool-invocation parts hold the persisted tool result.
+                // We don't scrub the input args (`rawInput` / `args`) because
+                // the chartId there is the model's outgoing claim, not
+                // anything it could re-reference; only `result` carries
+                // ids that subsequent turns might copy.
+                if (part.type !== "tool-invocation") {
+                    continue;
+                }
+                const inv = part.toolInvocation;
+                if (!inv || inv.result === undefined)
+                    continue;
+                const before = inv.result;
+                const after = stripChartIds(before);
+                // Cheap structural check via JSON length - the actual
+                // strip writes a fresh object only when chartId keys
+                // existed, so different stringification length is a
+                // reliable signal that something was removed.
+                if (typeof before === "object" &&
+                    before !== null &&
+                    JSON.stringify(before).length !== JSON.stringify(after).length) {
+                    inv.result = after;
+                    stripped += 1;
+                }
+            }
+        }
+        if (stripped > 0) {
+            logger.debug("stripped", { results: stripped });
+        }
+        return args.messages;
+    },
+};
+/**
+ * Mastra output processor that trims the bulky, redundant payload
+ * fields off targeted outbound stream frames.
+ *
+ * Mastra emits step / finish / tool-result frames whose payloads
+ * echo the full tool `output` / `result` / assistant `messages` /
+ * `response` - data the chat client already received inline and
+ * doesn't need re-sent. This processor empties those keys on the
+ * targeted frame types so the outbound SSE stream stays lean;
+ * every other frame passes through untouched.
+ */
+export class ResultProcessor {
+    id = "result-processor";
+    // Tell Mastra to also route tool/data parts to this processor method
+    processDataParts = true;
+    async processOutputStream({ part }) {
+        // 1. Guard clause: Ensure the chunk is a valid object
+        if (!part || typeof part !== "object") {
+            return part;
+        }
+        // 2. Filter for the targeted frame types
+        const targetedTypes = ["step-finish", "finish", "tool-result", "data-tool-agent"];
+        if (!targetedTypes.includes(part.type)) {
+            return part; // Return unchanged to pass-through
+        }
+        // 3. Check for the presence of a payload object
+        const payload = part.payload;
+        if (!payload || typeof payload !== "object") {
+            return part;
+        }
+        // 4. Safely delete the unwanted keys from the payload reference
+        const keysToDelete = ["output", "messages", "response", "result"];
+        for (const key of keysToDelete) {
+            if (key in payload) {
+                const value = payload[key];
+                if (typeof value === "object") {
+                    payload[key] = {};
+                }
+                else if (Array.isArray(value)) {
+                    payload[key] = [];
+                }
+                else {
+                    delete payload[key];
+                }
+            }
+        }
+        // 5. Return the modified part object. Mastra handles re-serialization
+        // for the outbound SSE client stream automatically.
+        return part;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJvY2Vzc29ycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9wcm9jZXNzb3JzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7OztHQWNHO0FBRUgsT0FBTyxFQUFFLEdBQUcsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRzdDLE1BQU0sTUFBTSxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsbUJBQW1CLENBQUMsQ0FBQztBQUUvQzs7Ozs7O0dBTUc7QUFDSCxTQUFTLGFBQWEsQ0FBQyxLQUFjO0lBQ25DLElBQUksS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQ3pCLE9BQU8sS0FBSyxDQUFDLEdBQUcsQ0FBQyxhQUFhLENBQUMsQ0FBQztJQUNsQyxDQUFDO0lBQ0QsSUFBSSxLQUFLLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUSxFQUFFLENBQUM7UUFDdkMsTUFBTSxHQUFHLEdBQUcsS0FBZ0MsQ0FBQztRQUM3QyxNQUFNLEdBQUcsR0FBNEIsRUFBRSxDQUFDO1FBQ3hDLEtBQUssTUFBTSxDQUFDLEdBQUcsRUFBRSxHQUFHLENBQUMsSUFBSSxNQUFNLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUM7WUFDN0MsSUFBSSxHQUFHLEtBQUssU0FBUztnQkFBRSxTQUFTO1lBQ2hDLEdBQUcsQ0FBQyxHQUFHLENBQUMsR0FBRyxhQUFhLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDaEMsQ0FBQztRQUNELE9BQU8sR0FBRyxDQUFDO0lBQ2IsQ0FBQztJQUNELE9BQU8sS0FBSyxDQUFDO0FBQ2YsQ0FBQztBQUVEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQTBCRztBQUNILE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFtQjtJQUN2RCxFQUFFLEVBQUUsb0JBQW9CO0lBQ3hCLFdBQVcsRUFDVCxpSEFBaUg7SUFDbkgsWUFBWSxDQUFDLElBQXNCO1FBQ2pDLElBQUksUUFB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QUcsSUFBSSxPQUFPLEVBQUUsQ0FBQztnQkFDbkIsTUFBTSxLQUFLLEdBQUcsT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDO2dCQUMzQixJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsRUFBRSxDQUFDO29CQUM5QixPQUFPLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxDQUFDO2dCQUNwQixDQUFDO3FCQUFNLElBQUksS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO29CQUNoQyxPQUFPLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxDQUFDO2dCQUNwQixDQUFDO3FCQUFNLENBQUM7b0JBQ04sT0FBTyxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUM7Z0JBQ3RCLENBQUM7WUFDSCxDQUFDO1FBQ0gsQ0FBQztRQUVELHNFQUFzRTtRQUN0RSxvREFBb0Q7UUFDcEQsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIE1hc3RyYSBzdHJlYW0gcHJvY2Vzc29ycyB3aXJlZCBvbnRvIHRoZSBwbHVnaW4ncyBhZ2VudHMuXG4gKlxuICogVHdvIGNvbXBsZW1lbnRhcnkgcHJvY2Vzc29ycyBsaXZlIGhlcmU6XG4gKlxuICogLSBBbiAqKmlucHV0KiogcHJvY2Vzc29yICh7QGxpbmsgc3RyaXBTdGFsZUNoYXJ0c1Byb2Nlc3Nvcn0pIHRoYXRcbiAqICAgc2NydWJzIHR1cm4tc2NvcGVkIGBjaGFydElkYCBmaWVsZHMgb3V0IG9mIHByaW9yIHRvb2wgcmVzdWx0c1xuICogICByZXBsYXllZCBmcm9tIE1lbW9yeSwgc28gdGhlIG1vZGVsIGNhbid0IGNvcHkgYSBzdGFsZSBpZCBpbnRvIHRoZVxuICogICBuZXcgdHVybidzIGBbY2hhcnQ6PGlkPl1gIG1hcmtlcnMuXG4gKiAtIEFuICoqb3V0cHV0KiogcHJvY2Vzc29yICh7QGxpbmsgUmVzdWx0UHJvY2Vzc29yfSkgdGhhdCB0cmltcyB0aGVcbiAqICAgYnVsa3ksIHJlZHVuZGFudCBwYXlsb2FkIGZpZWxkcyBvZmYgdGFyZ2V0ZWQgb3V0Ym91bmQgc3RyZWFtIGZyYW1lc1xuICogICBiZWZvcmUgdGhleSdyZSBzZXJpYWxpemVkIHRvIHRoZSBTU0UgY2xpZW50LlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBsb2cgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuaW1wb3J0IHR5cGUgeyBJbnB1dFByb2Nlc3NvciwgUHJvY2Vzc0lucHV0QXJncywgUHJvY2Vzc29yIH0gZnJvbSBcIkBtYXN0cmEvY29yZS9wcm9jZXNzb3JzXCI7XG5cbmNvbnN0IGxvZ2dlciA9IGxvZy5sb2dnZXIoXCJtYXN0cmEvcHJvY2Vzc29yc1wiKTtcblxuLyoqXG4gKiBSZWN1cnNpdmVseSBjbG9uZSBgdmFsdWVgLCBvbWl0dGluZyBhbnkgcHJvcGVydHkgd2hvc2Uga2V5IGlzXG4gKiBgY2hhcnRJZGAuIEFycmF5cyBhcmUgbWFwcGVkIGVsZW1lbnQtd2lzZTsgcHJpbWl0aXZlcyBhcmVcbiAqIHJldHVybmVkIGFzLWlzLiBUaGUgcmVzdWx0IGlzIHN0cnVjdHVyYWxseSBpZGVudGljYWwgdG8gdGhlXG4gKiBpbnB1dCBtaW51cyBjaGFydElkcywgc28gZG93bnN0cmVhbSBtZXNzYWdlLXNoYXBlIGNvbnN1bWVyc1xuICoga2VlcCB3b3JraW5nLlxuICovXG5mdW5jdGlvbiBzdHJpcENoYXJ0SWRzKHZhbHVlOiB1bmtub3duKTogdW5rbm93biB7XG4gIGlmIChBcnJheS5pc0FycmF5KHZhbHVlKSkge1xuICAgIHJldHVybiB2YWx1ZS5tYXAoc3RyaXBDaGFydElkcyk7XG4gIH1cbiAgaWYgKHZhbHVlICYmIHR5cGVvZiB2YWx1ZSA9PT0gXCJvYmplY3RcIikge1xuICAgIGNvbnN0IG9iaiA9IHZhbHVlIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+O1xuICAgIGNvbnN0IG91dDogUmVjb3JkPHN0cmluZywgdW5rbm93bj4gPSB7fTtcbiAgICBmb3IgKGNvbnN0IFtrZXksIHZhbF0gb2YgT2JqZWN0LmVudHJpZXMob2JqKSkge1xuICAgICAgaWYgKGtleSA9PT0gXCJjaGFydElkXCIpIGNvbnRpbnVlO1xuICAgICAgb3V0W2tleV0gPSBzdHJpcENoYXJ0SWRzKHZhbCk7XG4gICAgfVxuICAgIHJldHVybiBvdXQ7XG4gIH1cbiAgcmV0dXJuIHZhbHVlO1xufVxuXG4vKipcbiAqIE1hc3RyYSBpbnB1dCBwcm9jZXNzb3IgdGhhdCBzdHJpcHMgYGNoYXJ0SWRgIGZpZWxkcyBmcm9tIGV2ZXJ5XG4gKiB0b29sLWludm9jYXRpb24gcmVzdWx0IGluIHByaW9yIGFzc2lzdGFudCBtZXNzYWdlcyBiZWZvcmUgdGhleVxuICogcmVhY2ggdGhlIG1vZGVsLlxuICpcbiAqIFdoeTogY2hhcnRJZHMgYXJlIHR1cm4tc2NvcGVkIGZyb20gdGhlIG1vZGVsJ3MgcG9pbnQgb2YgdmlldyAtXG4gKiBlYWNoIGBwcmVwYXJlX2NoYXJ0YCAvIGByZW5kZXJfZGF0YWAgY2FsbCBtaW50cyBhIGZyZXNoIGlkIGFuZFxuICogdGhlIGhvc3QgVUkgYmluZHMgaXQgdG8gdGhhdCB0dXJuJ3MgcmVwbHkuIE1hc3RyYSBNZW1vcnlcbiAqIHJlcGxheXMgcHJpb3IgdG9vbCByZXN1bHRzIGludG8gdGhlIHByb21wdDsgaWYgb2xkIGNoYXJ0SWRzXG4gKiBsZWFrIHRocm91Z2gsIHRoZSBtb2RlbCBpcyB0ZW1wdGVkIHRvIGNvcHkgdGhlbSB2ZXJiYXRpbSBpbnRvXG4gKiB0aGUgbmV3IHR1cm4ncyBgW2NoYXJ0OjxpZD5dYCBtYXJrZXJzIGFuZCB0aGUgaG9zdCBVSSBlbmRzIHVwXG4gKiByZW5kZXJpbmcgYW4gdW5yZWxhdGVkIGNoYXJ0IGZyb20gdGhlIGNoYXJ0IGNhY2hlIChvclxuICogYSA0MDQgb25jZSB0aGUgMWggVFRMIGVsYXBzZWQpLiBUaGlzIHByb2Nlc3NvciByZW1vdmVzIHRoZVxuICogdGVtcHRhdGlvbiBieSBkZWxldGluZyBgY2hhcnRJZGAga2V5cyBmcm9tIGV2ZXJ5IGFzc2lzdGFudFxuICogbWVzc2FnZSdzIHRvb2wgcmVzdWx0cyBiZWZvcmUgdGhlIHByb21wdCBpcyBidWlsdC4gVGhlIGN1cnJlbnRcbiAqIHR1cm4ncyB0b29sIHJlc3VsdHMgZG9uJ3QgZXhpc3QgeWV0IGF0IGBwcm9jZXNzSW5wdXRgIHRpbWUsIHNvXG4gKiB0aGV5IHBhc3MgdGhyb3VnaCB1bm1vZGlmaWVkLlxuICpcbiAqIFRoZSBzdHJpcCBpcyByZWN1cnNpdmUgLSBhbnkgbmVzdGVkIGBjaGFydElkYCBmaWVsZCBpcyByZW1vdmVkLFxuICogcmVnYXJkbGVzcyBvZiB3aGljaCB0b29sIHByb2R1Y2VkIHRoZSByZXN1bHQuIFRoaXMgY292ZXJzXG4gKiBgcHJlcGFyZV9jaGFydGAgLyBgcmVuZGVyX2RhdGFgIHRvcC1sZXZlbCBjaGFydElkcyBhbmQgYW55XG4gKiBsZWdhY3kgYGRhdGFzZXRzW10uY2hhcnRJZGAgcGF5bG9hZHMgdW5pZm9ybWx5IHdpdGhvdXQgY291cGxpbmdcbiAqIHRvIHNwZWNpZmljIHRvb2wgaWRzLlxuICpcbiAqIFdpcmVkIG9udG8gZXZlcnkgYWdlbnQgYnkgZGVmYXVsdCB2aWEgYGJ1aWxkQWdlbnRzYDsgb3B0IG91dCB3aXRoXG4gKiBgTWFzdHJhUGx1Z2luQ29uZmlnLnN0cmlwU3RhbGVDaGFydHM6IGZhbHNlYC5cbiAqL1xuZXhwb3J0IGNvbnN0IHN0cmlwU3RhbGVDaGFydHNQcm9jZXNzb3I6IElucHV0UHJvY2Vzc29yID0ge1xuICBpZDogXCJzdHJpcC1zdGFsZS1jaGFydHNcIixcbiAgZGVzY3JpcHRpb246XG4gICAgXCJSZW1vdmVzIGNoYXJ0SWQgZmllbGRzIGZyb20gcHJpb3IgdG9vbC1pbnZvY2F0aW9uIHJlc3VsdHMgc28gdGhlIG1vZGVsIGNhbid0IHJldXNlIHR1cm4tc2NvcGVkIGlkcyBmcm9tIG1lbW9yeS5cIixcbiAgcHJvY2Vzc0lucHV0KGFyZ3M6IFByb2Nlc3NJbnB1dEFyZ3MpIHtcbiAgICBsZXQgc3RyaXBwZWQgPSAwO1xuICAgIGZvciAoY29uc3QgbWVzc2FnZSBvZiBhcmdzLm1lc3NhZ2VzKSB7XG4gICAgICBpZiAobWVzc2FnZS5yb2xlICE9PSBcImFzc2lzdGFudFwiKSBjb250aW51ZTtcbiAgICAgIGNvbnN0IHBhcnRzID0gbWVzc2FnZS5jb250ZW50Py5wYXJ0cztcbiAgICAgIGlmICghQXJyYXkuaXNBcnJheShwYXJ0cykpIGNvbnRpbnVlO1xuICAgICAgZm9yIChjb25zdCBwYXJ0IG9mIHBhcnRzKSB7XG4gICAgICAgIC8vIFRvb2wtaW52b2NhdGlvbiBwYXJ0cyBob2xkIHRoZSBwZXJzaXN0ZWQgdG9vbCByZXN1bHQuXG4gICAgICAgIC8vIFdlIGRvbid0IHNjcnViIHRoZSBpbnB1dCBhcmdzIChgcmF3SW5wdXRgIC8gYGFyZ3NgKSBiZWNhdXNlXG4gICAgICAgIC8vIHRoZSBjaGFydElkIHRoZXJlIGlzIHRoZSBtb2RlbCdzIG91dGdvaW5nIGNsYWltLCBub3RcbiAgICAgICAgLy8gYW55dGhpbmcgaXQgY291bGQgcmUtcmVmZXJlbmNlOyBvbmx5IGByZXN1bHRgIGNhcnJpZXNcbiAgICAgICAgLy8gaWRzIHRoYXQgc3Vic2VxdWVudCB0dXJucyBtaWdodCBjb3B5LlxuICAgICAgICBpZiAoKHBhcnQgYXMgeyB0eXBlPzogdW5rbm93biB9KS50eXBlICE9PSBcInRvb2wtaW52b2NhdGlvblwiKSB7XG4gICAgICAgICAgY29udGludWU7XG4gICAgICAgIH1cbiAgICAgICAgY29uc3QgaW52ID0gKHBhcnQgYXMgeyB0b29sSW52b2NhdGlvbj86IHsgcmVzdWx0PzogdW5rbm93biB9IH0pLnRvb2xJbnZvY2F0aW9uO1xuICAgICAgICBpZiAoIWludiB8fCBpbnYucmVzdWx0ID09PSB1bmRlZmluZWQpIGNvbnRpbnVlO1xuICAgICAgICBjb25zdCBiZWZvcmUgPSBpbnYucmVzdWx0O1xuICAgICAgICBjb25zdCBhZnRlciA9IHN0cmlwQ2hhcnRJZHMoYmVmb3JlKTtcbiAgICAgICAgLy8gQ2hlYXAgc3RydWN0dXJhbCBjaGVjayB2aWEgSlNPTiBsZW5ndGggLSB0aGUgYWN0dWFsXG4gICAgICAgIC8vIHN0cmlwIHdyaXRlcyBhIGZyZXNoIG9iamVjdCBvbmx5IHdoZW4gY2hhcnRJZCBrZXlzXG4gICAgICAgIC8vIGV4aXN0ZWQsIHNvIGRpZmZlcmVudCBzdHJpbmdpZmljYXRpb24gbGVuZ3RoIGlzIGFcbiAgICAgICAgLy8gcmVsaWFibGUgc2lnbmFsIHRoYXQgc29tZXRoaW5nIHdhcyByZW1vdmVkLlxuICAgICAgICBpZiAoXG4gICAgICAgICAgdHlwZW9mIGJlZm9yZSA9PT0gXCJvYmplY3RcIiAmJlxuICAgICAgICAgIGJlZm9yZSAhPT0gbnVsbCAmJlxuICAgICAgICAgIEpTT04uc3RyaW5naWZ5KGJlZm9yZSkubGVuZ3RoICE9PSBKU09OLnN0cmluZ2lmeShhZnRlcikubGVuZ3RoXG4gICAgICAgICkge1xuICAgICAgICAgIGludi5yZXN1bHQgPSBhZnRlcjtcbiAgICAgICAgICBzdHJpcHBlZCArPSAxO1xuICAgICAgICB9XG4gICAgICB9XG4gICAgfVxuICAgIGlmIChzdHJpcHBlZCA+IDApIHtcbiAgICAgIGxvZ2dlci5kZWJ1ZyhcInN0cmlwcGVkXCIsIHsgcmVzdWx0czogc3RyaXBwZWQgfSk7XG4gICAgfVxuICAgIHJldHVybiBhcmdzLm1lc3NhZ2VzO1xuICB9LFxufTtcblxuLyoqXG4gKiBNYXN0cmEgb3V0cHV0IHByb2Nlc3NvciB0aGF0IHRyaW1zIHRoZSBidWxreSwgcmVkdW5kYW50IHBheWxvYWRcbiAqIGZpZWxkcyBvZmYgdGFyZ2V0ZWQgb3V0Ym91bmQgc3RyZWFtIGZyYW1lcy5cbiAqXG4gKiBNYXN0cmEgZW1pdHMgc3RlcCAvIGZpbmlzaCAvIHRvb2wtcmVzdWx0IGZyYW1lcyB3aG9zZSBwYXlsb2Fkc1xuICogZWNobyB0aGUgZnVsbCB0b29sIGBvdXRwdXRgIC8gYHJlc3VsdGAgLyBhc3Npc3RhbnQgYG1lc3NhZ2VzYCAvXG4gKiBgcmVzcG9uc2VgIC0gZGF0YSB0aGUgY2hhdCBjbGllbnQgYWxyZWFkeSByZWNlaXZlZCBpbmxpbmUgYW5kXG4gKiBkb2Vzbid0IG5lZWQgcmUtc2VudC4gVGhpcyBwcm9jZXNzb3IgZW1wdGllcyB0aG9zZSBrZXlzIG9uIHRoZVxuICogdGFyZ2V0ZWQgZnJhbWUgdHlwZXMgc28gdGhlIG91dGJvdW5kIFNTRSBzdHJlYW0gc3RheXMgbGVhbjtcbiAqIGV2ZXJ5IG90aGVyIGZyYW1lIHBhc3NlcyB0aHJvdWdoIHVudG91Y2hlZC5cbiAqL1xuZXhwb3J0IGNsYXNzIFJlc3VsdFByb2Nlc3NvciBpbXBsZW1lbnRzIFByb2Nlc3NvciB7XG4gIGlkID0gXCJyZXN1bHQtcHJvY2Vzc29yXCI7XG5cbiAgLy8gVGVsbCBNYXN0cmEgdG8gYWxzbyByb3V0ZSB0b29sL2RhdGEgcGFydHMgdG8gdGhpcyBwcm9jZXNzb3IgbWV0aG9kXG4gIHByb2Nlc3NEYXRhUGFydHMgPSB0cnVlO1xuXG4gIGFzeW5jIHByb2Nlc3NPdXRwdXRTdHJlYW0oeyBwYXJ0IH06IHsgcGFydDogYW55IH0pOiBQcm9taXNlPGFueSB8IG51bGw+IHtcbiAgICAvLyAxLiBHdWFyZCBjbGF1c2U6IEVuc3VyZSB0aGUgY2h1bmsgaXMgYSB2YWxpZCBvYmplY3RcbiAgICBpZiAoIXBhcnQgfHwgdHlwZW9mIHBhcnQgIT09IFwib2JqZWN0XCIpIHtcbiAgICAgIHJldHVybiBwYXJ0O1xuICAgIH1cblxuICAgIC8vIDIuIEZpbHRlciBmb3IgdGhlIHRhcmdldGVkIGZyYW1lIHR5cGVzXG4gICAgY29uc3QgdGFyZ2V0ZWRUeXBlcyA9IFtcInN0ZXAtZmluaXNoXCIsIFwiZmluaXNoXCIsIFwidG9vbC1yZXN1bHRcIiwgXCJkYXRhLXRvb2wtYWdlbnRcIl07XG4gICAgaWYgKCF0YXJnZXRlZFR5cGVzLmluY2x1ZGVzKHBhcnQudHlwZSkpIHtcbiAgICAgIHJldHVybiBwYXJ0OyAvLyBSZXR1cm4gdW5jaGFuZ2VkIHRvIHBhc3MtdGhyb3VnaFxuICAgIH1cblxuICAgIC8vIDMuIENoZWNrIGZvciB0aGUgcHJlc2VuY2Ugb2YgYSBwYXlsb2FkIG9iamVjdFxuICAgIGNvbnN0IHBheWxvYWQgPSBwYXJ0LnBheWxvYWQ7XG4gICAgaWYgKCFwYXlsb2FkIHx8IHR5cGVvZiBwYXlsb2FkICE9PSBcIm9iamVjdFwiKSB7XG4gICAgICByZXR1cm4gcGFydDtcbiAgICB9XG5cbiAgICAvLyA0LiBTYWZlbHkgZGVsZXRlIHRoZSB1bndhbnRlZCBrZXlzIGZyb20gdGhlIHBheWxvYWQgcmVmZXJlbmNlXG4gICAgY29uc3Qga2V5c1RvRGVsZXRlID0gW1wib3V0cHV0XCIsIFwibWVzc2FnZXNcIiwgXCJyZXNwb25zZVwiLCBcInJlc3VsdFwiXTtcbiAgICBmb3IgKGNvbnN0IGtleSBvZiBrZXlzVG9EZWxldGUpIHtcbiAgICAgIGlmIChrZXkgaW4gcGF5bG9hZCkge1xuICAgICAgICBjb25zdCB2YWx1ZSA9IHBheWxvYWRba2V5XTtcbiAgICAgICAgaWYgKHR5cGVvZiB2YWx1ZSA9PT0gXCJvYmplY3RcIikge1xuICAgICAgICAgIHBheWxvYWRba2V5XSA9IHt9O1xuICAgICAgICB9IGVsc2UgaWYgKEFycmF5LmlzQXJyYXkodmFsdWUpKSB7XG4gICAgICAgICAgcGF5bG9hZFtrZXldID0gW107XG4gICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgZGVsZXRlIHBheWxvYWRba2V5XTtcbiAgICAgICAgfVxuICAgICAgfVxuICAgIH1cblxuICAgIC8vIDUuIFJldHVybiB0aGUgbW9kaWZpZWQgcGFydCBvYmplY3QuIE1hc3RyYSBoYW5kbGVzIHJlLXNlcmlhbGl6YXRpb25cbiAgICAvLyBmb3IgdGhlIG91dGJvdW5kIFNTRSBjbGllbnQgc3RyZWFtIGF1dG9tYXRpY2FsbHkuXG4gICAgcmV0dXJuIHBhcnQ7XG4gIH1cbn1cbiJdfQ==

package/lib/src/rest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Minimal authenticated Databricks REST helper. Pulls the workspace
+ * host and a fresh bearer header off an OBO-scoped `WorkspaceClient`
+ * (`client.config.getHost()` + `authenticate()`), then issues a plain
+ * `fetch`. Used by modules that hit REST surfaces without a typed SDK
+ * method (e.g. the MLflow assessments API); returns the raw `Response`
+ * so callers decide how to treat status codes. Also carries the
+ * defensive `Response` body readers those callers share.
+ *
+ * @module
+ */
+import { appkit } from "@dbx-tools/appkit";
+/** Workspace client carried on an AppKit execution context. */
+type WorkspaceClient = appkit.WorkspaceClientLike;
+/** Request options for {@link databricksFetch}. */
+export interface DatabricksFetchInit {
+    method: string;
+    /** JSON-serialized as the request body when present. */
+    body?: unknown;
+    /** Extra headers merged over the default `Content-Type: application/json`. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * 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.
+ */
+export declare function databricksFetch(client: WorkspaceClient, path: string, init: DatabricksFetchInit): Promise<Response>;
+/** Read a response body as text, swallowing read errors (returns `""`). */
+export declare function readResponseText(res: Response): Promise<string>;
+/** Parse a response body as JSON, returning `{}` on empty / invalid bodies. */
+export declare function readResponseJson(res: Response): Promise<unknown>;
+export {};

package/lib/src/rest.js

@@ -0,0 +1,46 @@
+/**
+ * Minimal authenticated Databricks REST helper. Pulls the workspace
+ * host and a fresh bearer header off an OBO-scoped `WorkspaceClient`
+ * (`client.config.getHost()` + `authenticate()`), then issues a plain
+ * `fetch`. Used by modules that hit REST surfaces without a typed SDK
+ * method (e.g. the MLflow assessments API); returns the raw `Response`
+ * so callers decide how to treat status codes. Also carries the
+ * defensive `Response` body readers those callers share.
+ *
+ * @module
+ */
+import { json } from "@dbx-tools/shared-core";
+/**
+ * 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.
+ */
+export 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 !== undefined ? { body: JSON.stringify(init.body) } : {}),
+        ...(init.signal ? { signal: init.signal } : {}),
+    });
+}
+/** Read a response body as text, swallowing read errors (returns `""`). */
+export async function readResponseText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}
+/** Parse a response body as JSON, returning `{}` on empty / invalid bodies. */
+export async function readResponseJson(res) {
+    const text = await readResponseText(res);
+    return json.parse(text, {});
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9yZXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7O0dBVUc7QUFHSCxPQUFPLEVBQUUsSUFBSSxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFlOUM7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxlQUFlLENBQ25DLE1BQXVCLEVBQ3ZCLElBQVksRUFDWixJQUF5QjtJQUV6QixNQUFNLElBQUksR0FBRyxDQUFDLE1BQU0sTUFBTSxDQUFDLE1BQU0sQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQUFDLFFBQVEsRUFBRSxDQUFDO0lBQ3hELE1BQU0sT0FBTyxHQUFHLElBQUksT0FBTyxDQUFDLEVBQUUsY0FBYyxFQUFFLGtCQUFrQixFQUFFLEdBQUcsSUFBSSxDQUFDLE9BQU8sRUFBRSxDQUFDLENBQUM7SUFDckYsTUFBTSxNQUFNLENBQUMsTUFBTSxDQUFDLFlBQVksQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUMxQyxNQUFNLEdBQUcsR0FBRyxJQUFJLEdBQUcsQ0FBQyxJQUFJLEVBQUUsSUFBSSxDQUFDLENBQUMsUUFBUSxFQUFFLENBQUM7SUFDM0MsT0FBTyxLQUFLLENBQUMsR0FBRyxFQUFFO1FBQ2hCLE1BQU0sRUFBRSxJQUFJLENBQUMsTUFBTTtRQUNuQixPQUFPO1FBQ1AsR0FBRyxDQUFDLElBQUksQ0FBQyxJQUFJLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLElBQUksRUFBRSxJQUFJLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7UUFDdkUsR0FBRyxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLEVBQUUsTUFBTSxFQUFFLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0tBQ2hELENBQUMsQ0FBQztBQUNMLENBQUM7QUFFRCwyRUFBMkU7QUFDM0UsTUFBTSxDQUFDLEtBQUssVUFBVSxnQkFBZ0IsQ0FBQyxHQUFhO0lBQ2xELElBQUksQ0FBQztRQUNILE9BQU8sTUFBTSxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDMUIsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE9BQU8sRUFBRSxDQUFDO0lBQ1osQ0FBQztBQUNILENBQUM7QUFFRCwrRUFBK0U7QUFDL0UsTUFBTSxDQUFDLEtBQUssVUFBVSxnQkFBZ0IsQ0FBQyxHQUFhO0lBQ2xELE1BQU0sSUFBSSxHQUFHLE1BQU0sZ0JBQWdCLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDekMsT0FBTyxJQUFJLENBQUMsS0FBSyxDQUFVLElBQUksRUFBRSxFQUFFLENBQUMsQ0FBQztBQUN2QyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBNaW5pbWFsIGF1dGhlbnRpY2F0ZWQgRGF0YWJyaWNrcyBSRVNUIGhlbHBlci4gUHVsbHMgdGhlIHdvcmtzcGFjZVxuICogaG9zdCBhbmQgYSBmcmVzaCBiZWFyZXIgaGVhZGVyIG9mZiBhbiBPQk8tc2NvcGVkIGBXb3Jrc3BhY2VDbGllbnRgXG4gKiAoYGNsaWVudC5jb25maWcuZ2V0SG9zdCgpYCArIGBhdXRoZW50aWNhdGUoKWApLCB0aGVuIGlzc3VlcyBhIHBsYWluXG4gKiBgZmV0Y2hgLiBVc2VkIGJ5IG1vZHVsZXMgdGhhdCBoaXQgUkVTVCBzdXJmYWNlcyB3aXRob3V0IGEgdHlwZWQgU0RLXG4gKiBtZXRob2QgKGUuZy4gdGhlIE1MZmxvdyBhc3Nlc3NtZW50cyBBUEkpOyByZXR1cm5zIHRoZSByYXcgYFJlc3BvbnNlYFxuICogc28gY2FsbGVycyBkZWNpZGUgaG93IHRvIHRyZWF0IHN0YXR1cyBjb2Rlcy4gQWxzbyBjYXJyaWVzIHRoZVxuICogZGVmZW5zaXZlIGBSZXNwb25zZWAgYm9keSByZWFkZXJzIHRob3NlIGNhbGxlcnMgc2hhcmUuXG4gKlxuICogQG1vZHVsZVxuICovXG5cbmltcG9ydCB7IGFwcGtpdCB9IGZyb20gXCJAZGJ4LXRvb2xzL2FwcGtpdFwiO1xuaW1wb3J0IHsganNvbiB9IGZyb20gXCJAZGJ4LXRvb2xzL3NoYXJlZC1jb3JlXCI7XG5cbi8qKiBXb3Jrc3BhY2UgY2xpZW50IGNhcnJpZWQgb24gYW4gQXBwS2l0IGV4ZWN1dGlvbiBjb250ZXh0LiAqL1xudHlwZSBXb3Jrc3BhY2VDbGllbnQgPSBhcHBraXQuV29ya3NwYWNlQ2xpZW50TGlrZTtcblxuLyoqIFJlcXVlc3Qgb3B0aW9ucyBmb3Ige0BsaW5rIGRhdGFicmlja3NGZXRjaH0uICovXG5leHBvcnQgaW50ZXJmYWNlIERhdGFicmlja3NGZXRjaEluaXQge1xuICBtZXRob2Q6IHN0cmluZztcbiAgLyoqIEpTT04tc2VyaWFsaXplZCBhcyB0aGUgcmVxdWVzdCBib2R5IHdoZW4gcHJlc2VudC4gKi9cbiAgYm9keT86IHVua25vd247XG4gIC8qKiBFeHRyYSBoZWFkZXJzIG1lcmdlZCBvdmVyIHRoZSBkZWZhdWx0IGBDb250ZW50LVR5cGU6IGFwcGxpY2F0aW9uL2pzb25gLiAqL1xuICBoZWFkZXJzPzogUmVjb3JkPHN0cmluZywgc3RyaW5nPjtcbiAgc2lnbmFsPzogQWJvcnRTaWduYWw7XG59XG5cbi8qKlxuICogUmVzb2x2ZSB0aGUgd29ya3NwYWNlIGhvc3QgKyBhbiBhdXRoZW50aWNhdGVkIGhlYWRlciBzZXQgb2ZmIHRoZVxuICogY2xpZW50IGFuZCBpc3N1ZSBhIGBmZXRjaGAgYWdhaW5zdCBgcGF0aGAgKG1vdW50ZWQgb24gdGhlIGhvc3QpLlxuICogUnVucyBhcyB3aGF0ZXZlciBpZGVudGl0eSB0aGUgY2xpZW50IGNhcnJpZXMgLSB0aGUgcGVyLXJlcXVlc3QgT0JPXG4gKiB1c2VyIHdoZW4gY2FsbGVkIGZyb20gYSByZXF1ZXN0IHNjb3BlLCB0aGUgc2VydmljZSBwcmluY2lwYWxcbiAqIG90aGVyd2lzZS5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGRhdGFicmlja3NGZXRjaChcbiAgY2xpZW50OiBXb3Jrc3BhY2VDbGllbnQsXG4gIHBhdGg6IHN0cmluZyxcbiAgaW5pdDogRGF0YWJyaWNrc0ZldGNoSW5pdCxcbik6IFByb21pc2U8UmVzcG9uc2U+IHtcbiAgY29uc3QgaG9zdCA9IChhd2FpdCBjbGllbnQuY29uZmlnLmdldEhvc3QoKSkudG9TdHJpbmcoKTtcbiAgY29uc3QgaGVhZGVycyA9IG5ldyBIZWFkZXJzKHsgXCJDb250ZW50LVR5cGVcIjogXCJhcHBsaWNhdGlvbi9qc29uXCIsIC4uLmluaXQuaGVhZGVycyB9KTtcbiAgYXdhaXQgY2xpZW50LmNvbmZpZy5hdXRoZW50aWNhdGUoaGVhZGVycyk7XG4gIGNvbnN0IHVybCA9IG5ldyBVUkwocGF0aCwgaG9zdCkudG9TdHJpbmcoKTtcbiAgcmV0dXJuIGZldGNoKHVybCwge1xuICAgIG1ldGhvZDogaW5pdC5tZXRob2QsXG4gICAgaGVhZGVycyxcbiAgICAuLi4oaW5pdC5ib2R5ICE9PSB1bmRlZmluZWQgPyB7IGJvZHk6IEpTT04uc3RyaW5naWZ5KGluaXQuYm9keSkgfSA6IHt9KSxcbiAgICAuLi4oaW5pdC5zaWduYWwgPyB7IHNpZ25hbDogaW5pdC5zaWduYWwgfSA6IHt9KSxcbiAgfSk7XG59XG5cbi8qKiBSZWFkIGEgcmVzcG9uc2UgYm9keSBhcyB0ZXh0LCBzd2FsbG93aW5nIHJlYWQgZXJyb3JzIChyZXR1cm5zIGBcIlwiYCkuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gcmVhZFJlc3BvbnNlVGV4dChyZXM6IFJlc3BvbnNlKTogUHJvbWlzZTxzdHJpbmc+IHtcbiAgdHJ5IHtcbiAgICByZXR1cm4gYXdhaXQgcmVzLnRleHQoKTtcbiAgfSBjYXRjaCB7XG4gICAgcmV0dXJuIFwiXCI7XG4gIH1cbn1cblxuLyoqIFBhcnNlIGEgcmVzcG9uc2UgYm9keSBhcyBKU09OLCByZXR1cm5pbmcgYHt9YCBvbiBlbXB0eSAvIGludmFsaWQgYm9kaWVzLiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIHJlYWRSZXNwb25zZUpzb24ocmVzOiBSZXNwb25zZSk6IFByb21pc2U8dW5rbm93bj4ge1xuICBjb25zdCB0ZXh0ID0gYXdhaXQgcmVhZFJlc3BvbnNlVGV4dChyZXMpO1xuICByZXR1cm4ganNvbi5wYXJzZTx1bmtub3duPih0ZXh0LCB7fSk7XG59XG4iXX0=

package/lib/src/server.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Express-layer plumbing for the Mastra plugin: a `MastraServer` that
+ * stamps the per-request `RequestContext`, and a route-patch middleware
+ * that lets the plugin's custom API routes (e.g. `historyRoute`) work
+ * behind an Express mount point.
+ *
+ * @module
+ */
+import { RequestContext } from "@mastra/core/request-context";
+import { MastraServer as MastraServerExpress } from "@mastra/express";
+import type express from "express";
+import { type MastraPluginConfig } from "./config.js";
+/**
+ * Stamp the AppKit user (plus the resource id and trace metadata) onto
+ * `requestContext`.
+ *
+ * Split out of {@link MastraServer} because the HTTP middleware is not the only
+ * caller that needs it: an out-of-band turn (a Teams activity arriving on
+ * another plugin's route, a scheduled job) drives `agent.generate` directly, and
+ * without this stamp every user-scoped tool - `ask_genie` above all - fails with
+ * "invoke the tool from an agent turn served by the mastra plugin". Those
+ * callers build a context with {@link createRequestContext} instead of a
+ * request.
+ *
+ * Idempotent: returns immediately when the user and resource id are already
+ * present, so the middleware can call it over a context another layer stamped.
+ */
+export declare function stampRequestContextUser(requestContext: RequestContext): Promise<void>;
+/**
+ * Build the `RequestContext` a NON-HTTP agent turn needs.
+ *
+ * Everything Mastra's tools read off the context is stamped the same way the
+ * request middleware stamps it - the AppKit user (so `ask_genie` and the model
+ * resolver can mint user-scoped tokens), the memory thread / resource pair, and
+ * a request id so the turn's spans join up in traces. The result is passed as
+ * `requestContext` to `agent.generate` / `agent.stream`.
+ *
+ * This is what makes a card turn answer with the SAME data a chat turn does: the
+ * difference between the two endpoints is presentation, not capability.
+ */
+export declare function createRequestContext(options?: {
+    threadId?: string;
+    resourceId?: string;
+    requestId?: string;
+}): Promise<RequestContext>;
+/**
+ * `@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`).
+ */
+export declare class MastraServer extends MastraServerExpress {
+    private config;
+    private log;
+    /**
+     * 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 MastraServerExpress>);
+    registerAuthMiddleware(): void;
+    configureRequestContextUser(requestContext: RequestContext): Promise<void>;
+    /**
+     * Stamp a per-request id and echo it on the response so an upstream
+     * proxy / curl client / browser-side log line can pair its view of
+     * the request with the matching trace span. Reuses `X-Request-Id`
+     * when the upstream already supplies one so multi-hop traces stay
+     * joined; otherwise mints a UUIDv4.
+     *
+     * The id is surfaced as `mastra__requestId` span metadata via
+     * {@link TRACE_REQUEST_CONTEXT_KEYS} and as the `X-Request-Id`
+     * response header so dev tools can copy it from either side.
+     */
+    configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+    /**
+     * Stamp OAuth scopes from the forwarded access token on
+     * {@link MASTRA_SCOPES_KEY} for workspace mount gating.
+     */
+    configureRequestContextScopes(req: express.Request, 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
+     * by the history / threads routes). Resolution order:
+     *
+     *   1. A client-supplied thread id (the thread-selection header /
+     *      `?threadId=` query). This is how the chat UI references a
+     *      specific conversation among the many a user owns - it picks a
+     *      thread id from the `/threads` listing (or mints one for a new
+     *      conversation) and stamps it here. The id is scoped to the
+     *      caller's resource by the recall / list routes, so a client
+     *      can only ever read or write its own threads.
+     *   2. The per-session cookie (`appkit_<plugin-name>_session_id`),
+     *      minted on first contact. This is the default single-thread
+     *      fallback for clients that don't manage threads explicitly, so
+     *      existing embeds keep one stable conversation per session with
+     *      no client changes.
+     */
+    configureRequestContextThreadId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+    /**
+     * Read the client-selected thread id from the request, preferring
+     * the thread-selection header over the `?threadId=` query. Returns
+     * `null` when neither carries a non-empty value so the caller falls
+     * back to the session cookie.
+     */
+    private readRequestedThreadId;
+    configureRequestContextModelOverride(req: express.Request, requestContext: RequestContext): void;
+}
+/** Inputs for {@link isMastraRequestAllowed}. */
+export interface MastraApiGateOptions {
+    /** `config.apiAccess`; `"full"` short-circuits to allow everything. */
+    access: "scoped" | "full";
+    /** Whether the MCP transport is mounted (so `/mcp/*` is legitimate). */
+    mcpEnabled: boolean;
+}
+/**
+ * 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.
+ */
+export declare function isMastraRequestAllowed(method: string, path: string, opts: MastraApiGateOptions): boolean;
+/**
+ * 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
+ * path (e.g. `/api/mastra`).
+ *
+ * The adapter's `registerCustomApiRoutes` matches against `req.path`
+ * (mount-relative, correct) but dispatches to its internal Hono
+ * mini-app using `req.originalUrl`, which still contains the parent
+ * mount prefix. The Hono app registers the literal route paths
+ * (for example `/route/history`), so the absolute URL never matches
+ * until we overwrite `originalUrl` for `/route` and `/route/*` to the
+ * mount-relative path.
+ */
+export declare function attachRoutePatchMiddleware(app: express.Express): void;