@dbx-tools/appkit-mastra 0.1.4 → 0.1.12

package/dist/src/history.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Thread history loader exposed as a Mastra custom API route.
+ *
+ * Backed entirely by native Mastra: looks up the active agent by id,
+ * asks its `Memory` instance to `recall` a page of `MastraDBMessage`s,
+ * and converts the result to AI SDK V5 `UIMessage`s with the official
+ * {@link toAISdkV5Messages} helper from `@mastra/ai-sdk/ui`. No direct
+ * database reads.
+ *
+ * The route is registered through {@link historyRoute} as a Mastra
+ * `registerApiRoute` so it sits in the same dispatcher pipeline as
+ * `chatRoute`. That means the `MastraServer` auth middleware (in
+ * `./server.ts`) has already populated `RequestContext` with
+ * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
+ * the handler runs - no cookie or user lookups happen here, and the
+ * session-cookie logic stays the single source of truth in `server.ts`.
+ */
+import type { Agent } from "@mastra/core/agent";
+import type { MastraHistoryResponse } from "@dbx-tools/appkit-mastra-shared";
+/** Inputs accepted by {@link loadHistory}. */
+export interface LoadHistoryOptions {
+    agent: Agent;
+    threadId: string;
+    resourceId?: string;
+    page?: number;
+    perPage?: number;
+    /** When true, returns the *oldest* page first (chronological). */
+    ascending?: boolean;
+}
+/**
+ * Fetch a page of UI-formatted messages for a thread.
+ *
+ * Uses the agent's resolved `Memory` (`getMemory()`) so per-agent
+ * storage namespaces (`mastra_<agentId>` schemas) and any future
+ * memory-side filters apply automatically. When the agent has no
+ * memory configured the response is a successful empty page so
+ * callers don't have to special-case stateless agents.
+ *
+ * Pagination is descending-by-default: page 0 is the most recent
+ * page, page 1 the page before that, etc. The returned `uiMessages`
+ * are always re-sorted into chronological order (oldest -> newest)
+ * so the client can prepend them above the existing transcript
+ * without sorting locally.
+ */
+export declare function loadHistory(opts: LoadHistoryOptions): Promise<MastraHistoryResponse>;
+/** Options accepted by {@link historyRoute}. */
+export type HistoryRouteOptions = {
+    path: `${string}:agentId${string}`;
+    agent?: never;
+} | {
+    path: string;
+    agent: string;
+};
+/**
+ * Register a `GET <path>` Mastra custom API route that returns a page
+ * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ *
+ * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
+ * fixed-agent mount, or include `:agentId` in the path for dynamic
+ * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
+ * layout (`/route/chat` + `/route/chat/:agentId`).
+ *
+ * The handler reads `threadId` and `resourceId` from `RequestContext`
+ * (populated upstream by `MastraServer.registerAuthMiddleware`), so
+ * no cookie or user lookups happen here.
+ */
+export declare function historyRoute(options: HistoryRouteOptions): import("@mastra/core/server").ApiRoute;

package/dist/src/history.js

@@ -0,0 +1,172 @@
+/**
+ * Thread history loader exposed as a Mastra custom API route.
+ *
+ * Backed entirely by native Mastra: looks up the active agent by id,
+ * asks its `Memory` instance to `recall` a page of `MastraDBMessage`s,
+ * and converts the result to AI SDK V5 `UIMessage`s with the official
+ * {@link toAISdkV5Messages} helper from `@mastra/ai-sdk/ui`. No direct
+ * database reads.
+ *
+ * The route is registered through {@link historyRoute} as a Mastra
+ * `registerApiRoute` so it sits in the same dispatcher pipeline as
+ * `chatRoute`. That means the `MastraServer` auth middleware (in
+ * `./server.ts`) has already populated `RequestContext` with
+ * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
+ * the handler runs - no cookie or user lookups happen here, and the
+ * session-cookie logic stays the single source of truth in `server.ts`.
+ */
+import { logUtils } from "@dbx-tools/appkit-shared";
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
+import { registerApiRoute } from "@mastra/core/server";
+const log = logUtils.logger("mastra/history");
+/** Default history page size; matches the Mastra storage default. */
+const DEFAULT_PER_PAGE = 20;
+/** Hard cap so a misbehaving client can't fetch the whole thread at once. */
+const MAX_PER_PAGE = 200;
+/**
+ * Fetch a page of UI-formatted messages for a thread.
+ *
+ * Uses the agent's resolved `Memory` (`getMemory()`) so per-agent
+ * storage namespaces (`mastra_<agentId>` schemas) and any future
+ * memory-side filters apply automatically. When the agent has no
+ * memory configured the response is a successful empty page so
+ * callers don't have to special-case stateless agents.
+ *
+ * Pagination is descending-by-default: page 0 is the most recent
+ * page, page 1 the page before that, etc. The returned `uiMessages`
+ * are always re-sorted into chronological order (oldest -> newest)
+ * so the client can prepend them above the existing transcript
+ * without sorting locally.
+ */
+export async function loadHistory(opts) {
+    const perPage = clampPerPage(opts.perPage);
+    const page = Math.max(0, Math.trunc(opts.page ?? 0));
+    const memory = await opts.agent.getMemory();
+    if (!memory) {
+        log.debug("recall:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
+        return { uiMessages: [], page, perPage, total: 0, hasMore: false };
+    }
+    const startedAt = Date.now();
+    const result = await memory.recall({
+        threadId: opts.threadId,
+        ...(opts.resourceId ? { resourceId: opts.resourceId } : {}),
+        page,
+        perPage,
+        orderBy: {
+            field: "createdAt",
+            direction: opts.ascending ? "ASC" : "DESC",
+        },
+    });
+    const chronological = sortChronological(result.messages);
+    const uiMessages = toAISdkV5Messages(chronological);
+    log.debug("recall:done", {
+        agentId: opts.agent.id,
+        threadId: opts.threadId,
+        page,
+        perPage,
+        returned: uiMessages.length,
+        total: result.total,
+        hasMore: result.hasMore,
+        elapsedMs: Date.now() - startedAt,
+    });
+    return {
+        uiMessages,
+        page,
+        perPage,
+        total: result.total,
+        hasMore: result.hasMore,
+    };
+}
+/**
+ * Register a `GET <path>` Mastra custom API route that returns a page
+ * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ *
+ * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
+ * fixed-agent mount, or include `:agentId` in the path for dynamic
+ * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
+ * layout (`/route/chat` + `/route/chat/:agentId`).
+ *
+ * The handler reads `threadId` and `resourceId` from `RequestContext`
+ * (populated upstream by `MastraServer.registerAuthMiddleware`), so
+ * no cookie or user lookups happen here.
+ */
+export function historyRoute(options) {
+    const { path } = options;
+    const fixedAgent = "agent" in options ? options.agent : undefined;
+    if (!fixedAgent && !path.includes(":agentId")) {
+        throw new Error("historyRoute path must include `:agentId` or `agent` must be passed explicitly");
+    }
+    return registerApiRoute(path, {
+        method: "GET",
+        handler: async (c) => {
+            const mastra = c.get("mastra");
+            const requestContext = c.get("requestContext");
+            const agentId = fixedAgent ?? c.req.param("agentId");
+            if (!agentId) {
+                return c.json({ error: "agentId is required" }, 400);
+            }
+            const agent = mastra.getAgentById(agentId);
+            if (!agent) {
+                return c.json({ error: `Unknown agent "${agentId}"` }, 404);
+            }
+            const threadId = requestContext.get(MASTRA_THREAD_ID_KEY);
+            if (!threadId) {
+                return c.json({ error: "thread id missing from request context" }, 400);
+            }
+            const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY);
+            const payload = await loadHistory({
+                agent,
+                threadId,
+                ...(resourceId ? { resourceId } : {}),
+                page: parseIntParam(c.req.query("page")),
+                perPage: parseIntParam(c.req.query("perPage")),
+            });
+            return c.json(payload);
+        },
+    });
+}
+/** Coerce / clamp `perPage`; falls back to the page-size default. */
+function clampPerPage(value) {
+    if (value === undefined || 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);
+}
+/**
+ * Sort messages oldest-first by `createdAt`, falling back to whatever
+ * order the storage returned them in. The native `recall` call honors
+ * `orderBy` but doesn't guarantee a stable secondary sort, so we
+ * normalize here before handing the page to the AI SDK converter.
+ */
+function sortChronological(messages) {
+    return [...messages].sort((a, b) => {
+        const ta = toEpoch(a.createdAt);
+        const tb = toEpoch(b.createdAt);
+        return ta - tb;
+    });
+}
+function toEpoch(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === "string" || typeof value === "number") {
+        const parsed = new Date(value).getTime();
+        return Number.isNaN(parsed) ? 0 : parsed;
+    }
+    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(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return Math.trunc(n);
+}

package/dist/src/memory.js

@@ -19,11 +19,12 @@
  * is registered); per-agent settings cascade on top of that.
  */
 import { lakebase } from "@databricks/appkit";
-import { pluginUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
 import { randomUUID } from "node:crypto";
+const log = logUtils.logger("mastra/memory");
 /**
  * True when any plugin-level or per-agent setting could need the
  * Lakebase pool. Used by `plugin.ts` to gate pool acquisition; the
@@ -80,8 +81,20 @@ export class MemoryBuilder {
         const memorySetting = def.memory ?? this.config.memory;
         const storage = this.buildStorage(agentId, storageSetting);
         const vector = this.buildVector(memorySetting);
-        if (!storage && !vector)
+        if (!storage && !vector) {
+            log.debug("agent:stateless", { agentId });
             return undefined;
+        }
+        log.debug("agent:configured", {
+            agentId,
+            storage: storage !== undefined,
+            vector: vector !== undefined,
+            vectorMode: vector === undefined
+                ? "off"
+                : typeof memorySetting === "object"
+                    ? "dedicated"
+                    : "shared",
+        });
         return new Memory({
             ...(storage ? { storage } : {}),
             ...(vector ? { vector, embedder: fastembed } : {}),

package/dist/src/model.js

@@ -263,6 +263,7 @@ export async function buildModel(config, requestContext, overrides = {}) {
  * to the top of the priority list.
  */
 async function pickModelId(config, requestContext, overrides, user, host) {
+    const log = logUtils.logger(config);
     const serving = resolveServingConfig(config, FALLBACK_MODEL_IDS);
     const override = serving.allowOverride
         ? requestContext.get(MASTRA_MODEL_OVERRIDE_KEY)
@@ -270,15 +271,21 @@ async function pickModelId(config, requestContext, overrides, user, host) {
     const explicit = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
     // Cheap exit: when the caller named a specific model and fuzzy
     // matching is off, there's no reason to touch the catalogue at all.
-    if (explicit !== undefined && !serving.fuzzy)
+    if (explicit !== undefined && !serving.fuzzy) {
+        log.debug("model selected", { modelId: explicit, source: "explicit" });
         return explicit;
+    }
     const endpoints = await listServingEndpoints(user.executionContext.client, host, {
         ttlMs: serving.ttlMs,
     });
     const modelId = explicit !== undefined
         ? resolveModelId(explicit, endpoints, { threshold: serving.threshold }).modelId
         : pickFirstAvailable(serving.fallbacks, endpoints);
-    //logUtils.logger(config).debug(`model selected: ${modelId}`);
+    log.debug("model selected", {
+        modelId,
+        source: explicit !== undefined ? "fuzzy-match" : "fallback",
+        requestedExplicit: explicit,
+    });
     return modelId;
 }
 /**
@@ -305,9 +312,9 @@ const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
  *   1. Rewrites the outgoing `messages` array to repair Mastra/AI SDK
  *      stream-replay quirks that Databricks-hosted Claude rejects (see
  *      {@link sanitizeServingMessages}).
- *   2. When `MASTRA_DEBUG_LLM=1`, dumps the (post-sanitize) JSON body
- *      to stderr so 4xx debugging doesn't have to fight AI SDK's
- *      `[Array]` formatter.
+ *   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
+ *      4xx debugging doesn't have to fight AI SDK's `[Array]`
+ *      formatter.
  *
  * Safe to call from any hot path: {@link commonUtils.memoize} ensures
  * the wrapper is installed at most once per process, so subsequent
@@ -315,7 +322,7 @@ const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
  * {@link buildModel} fires on every agent step.
  */
 const setupFetchInterceptor = commonUtils.memoize(() => {
-    const debug = Boolean(process.env.MASTRA_DEBUG_LLM);
+    const log = logUtils.logger("mastra/llm");
     const original = globalThis.fetch.bind(globalThis);
     globalThis.fetch = (async (input, init) => {
         const url = httpUtils.toURL(input);
@@ -328,14 +335,11 @@ const setupFetchInterceptor = commonUtils.memoize(() => {
         if (rewritten !== init.body) {
             init = { ...init, body: rewritten };
         }
-        if (debug) {
-            try {
-                console.error("[mastra:llm-debug] -> POST", url.toString());
-                console.error(JSON.stringify(JSON.parse(rewritten), null, 2));
-            }
-            catch {
-                console.error("[mastra:llm-debug] -> POST", url.toString(), "(non-JSON body)");
-            }
+        try {
+            log.debug("POST", { url: url.toString(), body: JSON.parse(rewritten) });
+        }
+        catch {
+            log.debug("POST", { url: url.toString(), bodyType: "non-JSON" });
         }
         return original(input, init);
     });

package/dist/src/plugin.d.ts

@@ -88,7 +88,7 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
          */
         getDefault: () => Agent | null;
         /** Underlying Mastra instance for advanced use (custom routes etc.). */
-        getMastra: () => Mastra<Record<string, Agent<any, import("@mastra/core/agent").ToolsInput, undefined, unknown>>, Record<string, import("@mastra/core/workflows").AnyWorkflow>, Record<string, import("@mastra/core/vector").MastraVector<any>>, Record<string, import("@mastra/core/tts").MastraTTS>, import("@mastra/core/logger").IMastraLogger, Record<string, import("@mastra/core/mcp").MCPServerBase<any>>, Record<string, import("@mastra/core/evals").MastraScorer<any, any, any, any>>, Record<string, import("@mastra/core/tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, import("@mastra/core/processors").Processor<any, unknown>>, Record<string, import("@mastra/core/memory").MastraMemory>, Record<string, import("@mastra/core/channels").ChannelProvider>> | null;
+        getMastra: () => Mastra<Record<string, Agent<any, import("@mastra/core/agent").ToolsInput, undefined, unknown, import("@mastra/core/agent").AgentEditorConfig | undefined>>, Record<string, import("@mastra/core/workflows").AnyWorkflow>, Record<string, import("@mastra/core/vector").MastraVector<any>>, Record<string, import("@mastra/core/tts").MastraTTS>, import("@mastra/core/logger").IMastraLogger, Record<string, import("@mastra/core/mcp").MCPServerBase<any>>, Record<string, import("@mastra/core/evals").MastraScorer<any, any, any, any>>, Record<string, import("@mastra/core/tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, import("@mastra/core/processors").Processor<any, unknown>>, Record<string, import("@mastra/core/memory").MastraMemory>, Record<string, import("@mastra/core/channels").ChannelProvider>> | null;
         /** Express subapp Mastra is mounted on; mostly for tests. */
         getMastraServer: () => MastraServer | null;
         /**
@@ -109,6 +109,16 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
     };
     clientConfig(): Record<string, unknown>;
     injectRoutes(router: IAppRouter): void;
+    /**
+     * Return `this.asUser(req)` when the request carries an OBO token,
+     * otherwise return `this` directly. Prevents the noisy AppKit warn
+     * (`asUser() called without user token in development mode. Skipping
+     * user impersonation.`) on every request in local dev where the
+     * browser never sends `x-forwarded-access-token`. Behavior is
+     * unchanged in production: a missing token always means a real OBO
+     * proxy call (and AppKit will throw upstream if that's wrong).
+     */
+    private userScopedSelf;
     /**
      * Implementation backing both the `/models` route and the
      * `listModels` export. Runs inside the AppKit user-context proxy so

package/dist/src/plugin.js

@@ -32,6 +32,7 @@ import { chatRoute } from "@mastra/ai-sdk";
 import { Mastra } from "@mastra/core/mastra";
 import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.js";
+import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
@@ -159,6 +160,8 @@ export class MastraPlugin extends Plugin {
             chatPath: `${basePath}/route/chat`,
             chatPathTemplate: `${basePath}/route/chat/:agentId`,
             modelsPath: `${basePath}/models`,
+            historyPath: `${basePath}/route/history`,
+            historyPathTemplate: `${basePath}/route/history/:agentId`,
             defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
             agents: Object.keys(this.built?.agents ?? {}),
         };
@@ -171,7 +174,7 @@ export class MastraPlugin extends Plugin {
         // the Mastra subapp. Errors propagate to Express's default error
         // handler via `next(err)` so callers see the real SDK message.
         router.get("/models", (req, res, next) => {
-            this.asUser(req)
+            this.userScopedSelf(req)
                 .listModels()
                 .then((endpoints) => res.json({ endpoints }))
                 .catch(next);
@@ -179,9 +182,21 @@ export class MastraPlugin extends Plugin {
         router.use("", (req, res, next) => {
             if (!this.mastraApp)
                 return res.status(503).end();
-            return this.asUser(req).mastraApp(req, res, next);
+            return this.userScopedSelf(req).mastraApp(req, res, next);
         });
     }
+    /**
+     * Return `this.asUser(req)` when the request carries an OBO token,
+     * otherwise return `this` directly. Prevents the noisy AppKit warn
+     * (`asUser() called without user token in development mode. Skipping
+     * user impersonation.`) on every request in local dev where the
+     * browser never sends `x-forwarded-access-token`. Behavior is
+     * unchanged in production: a missing token always means a real OBO
+     * proxy call (and AppKit will throw upstream if that's wrong).
+     */
+    userScopedSelf(req) {
+        return req.header("x-forwarded-access-token") ? this.asUser(req) : this;
+    }
     /**
      * Implementation backing both the `/models` route and the
      * `listModels` export. Runs inside the AppKit user-context proxy so
@@ -201,6 +216,10 @@ export class MastraPlugin extends Plugin {
         const memoryBuilder = needsLakebase(this.config)
             ? createMemoryBuilder(this.config, this.context)
             : undefined;
+        this.log.debug("build:start", {
+            lakebase: memoryBuilder !== undefined,
+            stripStaleCharts: this.config.stripStaleCharts !== false,
+        });
         // Build every agent declared in `config.agents` (or the built-in
         // fallback when none are declared). Each agent's `model` resolves
         // workspace URL + bearer at call time so concurrent requests get
@@ -227,9 +246,16 @@ export class MastraPlugin extends Plugin {
             customApiRoutes: [
                 chatRoute({ path: "/route/chat", agent: this.built.defaultAgentId }),
                 chatRoute({ path: "/route/chat/:agentId" }),
+                historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
+                historyRoute({ path: "/route/history/:agentId" }),
             ],
         });
         await this.mastraServer.init();
+        this.log.debug("build:done", {
+            agents: Object.keys(this.built.agents),
+            defaultAgent: this.built.defaultAgentId,
+            routes: ["/route/chat", "/route/history", "/models"],
+        });
     }
 }
 export const mastra = toPlugin(MastraPlugin);

package/dist/src/processors/strip-stale-charts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are only meaningful within the assistant turn that
+ * minted them - the writer events backing them are gone after the
+ * stream closes. When the model sees old chartIds in memory recall
+ * (Mastra Memory persists tool results), it's tempted to type
+ * those ids into the new turn's `[[chart:<id>]]` markers, leaving
+ * the chat client's chart slots stuck with no matching event. 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 Genie's
+ * `datasets[].chartId` and `render_data`'s top-level `chartId`
+ * uniformly without coupling to specific tool ids.
+ */
+import type { InputProcessor } from "@mastra/core/processors";
+/**
+ * Input processor that scrubs `chartId` from every tool-invocation
+ * result in the message list. Wired onto every agent by default
+ * via {@link buildAgents}; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export declare const stripStaleChartsProcessor: InputProcessor;

package/dist/src/processors/strip-stale-charts.js

@@ -0,0 +1,96 @@
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are only meaningful within the assistant turn that
+ * minted them - the writer events backing them are gone after the
+ * stream closes. When the model sees old chartIds in memory recall
+ * (Mastra Memory persists tool results), it's tempted to type
+ * those ids into the new turn's `[[chart:<id>]]` markers, leaving
+ * the chat client's chart slots stuck with no matching event. 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 Genie's
+ * `datasets[].chartId` and `render_data`'s top-level `chartId`
+ * uniformly without coupling to specific tool ids.
+ */
+import { logUtils } from "@dbx-tools/appkit-shared";
+const log = logUtils.logger("mastra/processor/strip-stale-charts");
+/**
+ * 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;
+}
+/**
+ * Input processor that scrubs `chartId` from every tool-invocation
+ * result in the message list. Wired onto every agent by default
+ * via {@link 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) {
+            log.debug("stripped", { results: stripped });
+        }
+        return args.messages;
+    },
+};

package/dist/src/server.d.ts

@@ -4,6 +4,7 @@
  * that lets `@mastra/ai-sdk` `chatRoute` work behind an Express mount
  * point.
  */
+import { type RequestContext } from "@mastra/core/request-context";
 import { MastraServer as MastraServerExpress } from "@mastra/express";
 import type express from "express";
 import { type MastraPluginConfig } from "./config.js";
@@ -17,6 +18,9 @@ export declare class MastraServer extends MastraServerExpress {
     private log;
     constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServerExpress>);
     registerAuthMiddleware(): void;
+    configureRequestContextUser(requestContext: RequestContext): void;
+    configureRequestContextThreadId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+    configureRequestContextModelOverride(req: express.Request, requestContext: RequestContext): void;
 }
 /**
  * Patches around `@mastra/express`'s custom-route dispatcher so