@dbx-tools/appkit-mastra 0.1.4 → 0.1.5

package/dist/src/history.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { 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";
+/** 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) {
+        return { uiMessages: [], page, perPage, total: 0, hasMore: false };
+    }
+    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);
+    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/plugin.d.ts

@@ -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,8 @@ 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 { renderChartRoute } from "./render-chart-route.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
@@ -159,6 +161,9 @@ 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`,
+            renderChartPath: `${basePath}/route/render-chart`,
             defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
             agents: Object.keys(this.built?.agents ?? {}),
         };
@@ -171,7 +176,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 +184,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
@@ -227,6 +244,9 @@ 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" }),
+                renderChartRoute({ path: "/route/render-chart", config: this.config }),
             ],
         });
         await this.mastraServer.init();

package/dist/src/render-chart-route.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Chart-render HTTP endpoint for the Mastra plugin.
+ *
+ * The `render_data` tool returns immediately with a `chartId` and
+ * emits the dataset over `ctx.writer`; the client then POSTs that
+ * dataset to this endpoint to actually run the chart-planner
+ * agent and get back an Echarts `EChartsOption` JSON. Planning
+ * happens out-of-band so the calling agent's response stream
+ * doesn't sit idle waiting for it - the model can finish the
+ * report while the client is still rendering charts.
+ *
+ * Auth flows through the standard Mastra middleware: the route
+ * sits in the same dispatcher pipeline as `chatRoute` /
+ * `historyRoute`, so by the time the handler runs the
+ * `RequestContext` is populated with the workspace user and
+ * the chart-planner's model resolver has the OBO token it
+ * needs.
+ */
+import type { MastraPluginConfig } from "./config.js";
+/** Options accepted by {@link renderChartRoute}. */
+export interface RenderChartRouteOptions {
+    path: string;
+    config: MastraPluginConfig;
+}
+/**
+ * Register a `POST <path>` Mastra custom API route that runs the
+ * chart-planner agent against a dataset and returns an Echarts
+ * `EChartsOption` JSON.
+ *
+ * Body shape: {@link RenderChartRequest}; response:
+ * {@link RenderChartResponse}.
+ */
+export declare function renderChartRoute(options: RenderChartRouteOptions): import("@mastra/core/server").ApiRoute;

package/dist/src/render-chart-route.js

@@ -0,0 +1,120 @@
+/**
+ * Chart-render HTTP endpoint for the Mastra plugin.
+ *
+ * The `render_data` tool returns immediately with a `chartId` and
+ * emits the dataset over `ctx.writer`; the client then POSTs that
+ * dataset to this endpoint to actually run the chart-planner
+ * agent and get back an Echarts `EChartsOption` JSON. Planning
+ * happens out-of-band so the calling agent's response stream
+ * doesn't sit idle waiting for it - the model can finish the
+ * report while the client is still rendering charts.
+ *
+ * Auth flows through the standard Mastra middleware: the route
+ * sits in the same dispatcher pipeline as `chatRoute` /
+ * `historyRoute`, so by the time the handler runs the
+ * `RequestContext` is populated with the workspace user and
+ * the chart-planner's model resolver has the OBO token it
+ * needs.
+ */
+import { registerApiRoute } from "@mastra/core/server";
+import { runChartPlanner } from "./chart.js";
+/** Hard cap so a misbehaving client can't hand us a million-row payload. */
+const MAX_ROWS = 5_000;
+/**
+ * Hard cap on the JSON body the route accepts (in bytes). Mirrors
+ * the same intent as {@link MAX_ROWS}: bound the chart-planner's
+ * prompt size and protect against accidental denial-of-service
+ * from a runaway tool that ships an enormous payload.
+ */
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+/**
+ * Register a `POST <path>` Mastra custom API route that runs the
+ * chart-planner agent against a dataset and returns an Echarts
+ * `EChartsOption` JSON.
+ *
+ * Body shape: {@link RenderChartRequest}; response:
+ * {@link RenderChartResponse}.
+ */
+export function renderChartRoute(options) {
+    const { path, config } = options;
+    return registerApiRoute(path, {
+        method: "POST",
+        handler: async (c) => {
+            const requestContext = c.get("requestContext");
+            // Hono parses the body as JSON; we still validate shape /
+            // size since the tool's structured output is a contract,
+            // not a guarantee, and the route is publicly mountable.
+            const raw = (await c.req.json().catch(() => null));
+            const validation = validateBody(raw);
+            if ("error" in validation) {
+                return c.json({ error: validation.error }, 400);
+            }
+            const { title, description, data } = validation.body;
+            try {
+                const result = await runChartPlanner({
+                    config,
+                    ...(requestContext ? { requestContext } : {}),
+                    title,
+                    ...(description ? { description } : {}),
+                    data,
+                });
+                const payload = {
+                    option: result.option,
+                    chartType: result.chartType,
+                };
+                return c.json(payload);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return c.json({ error: message }, 500);
+            }
+        },
+    });
+}
+/**
+ * Best-effort body validation. Surfaces a 400 for malformed input
+ * instead of letting a downstream `.map` / `.length` blow up
+ * inside the planner agent. Field-level shape mirrors
+ * {@link RenderChartRequest}.
+ */
+function validateBody(raw) {
+    if (!raw || typeof raw !== "object") {
+        return { error: "request body must be a JSON object" };
+    }
+    const r = raw;
+    const title = r.title;
+    if (typeof title !== "string" || title.length === 0) {
+        return { error: "`title` must be a non-empty string" };
+    }
+    if (r.description !== undefined && typeof r.description !== "string") {
+        return { error: "`description` must be a string when provided" };
+    }
+    if (!Array.isArray(r.data)) {
+        return { error: "`data` must be an array of row objects" };
+    }
+    if (r.data.length === 0) {
+        return { error: "`data` must contain at least one row" };
+    }
+    if (r.data.length > MAX_ROWS) {
+        return { error: `\`data\` exceeds the per-request limit of ${MAX_ROWS} rows` };
+    }
+    for (const [i, row] of r.data.entries()) {
+        if (!row || typeof row !== "object" || Array.isArray(row)) {
+            return { error: `data[${i}] must be a plain object` };
+        }
+    }
+    // Approximate body-size check; spares us pulling Buffer in.
+    const approximateBytes = JSON.stringify(r.data).length;
+    if (approximateBytes > MAX_BODY_BYTES) {
+        return {
+            error: `\`data\` exceeds the per-request size limit of ${MAX_BODY_BYTES} bytes`,
+        };
+    }
+    return {
+        body: {
+            title,
+            ...(typeof r.description === "string" ? { description: r.description } : {}),
+            data: r.data,
+        },
+    };
+}

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

package/dist/src/server.js

@@ -27,55 +27,59 @@ export class MastraServer extends MastraServerExpress {
     registerAuthMiddleware() {
         super.registerAuthMiddleware();
         this.app.use((req, res, next) => {
-            const executionContext = getExecutionContext();
-            const user = {
-                id: "userId" in executionContext
-                    ? executionContext.userId
-                    : executionContext.serviceUserId,
-                executionContext,
-            };
             const requestContext = res.locals.requestContext;
-            requestContext.set(MASTRA_USER_KEY, user);
-            if (!requestContext.get(MASTRA_RESOURCE_ID_KEY)) {
-                this.log.debug(`Setting resource id: ${user.id}`);
-                requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
-            }
-            const cookies = httpUtils.parseCookies(req.headers.cookie);
-            const cookieName = stringUtils.toIdentifierWithOptions({ delimiter: "_", distinct: true }, "appkit", this.config.name, "sessionId");
-            let sessionId = cookies[cookieName];
-            if (!sessionId) {
-                sessionId = randomUUID();
-                res.cookie(cookieName, sessionId, {
-                    httpOnly: true,
-                    sameSite: "lax",
-                    secure: req.secure,
-                    path: "/",
-                });
-            }
-            res.locals.sessionId = sessionId;
-            if (!requestContext.get(MASTRA_THREAD_ID_KEY)) {
-                this.log.debug(`Setting thread id: ${sessionId}`);
-                requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
-            }
-            // Per-request model override: only honored when the plugin
-            // opts in (default). Sources, in priority order, are
-            // `X-Mastra-Model` header, `?model=` query, and `model` /
-            // `modelId` body field; see `serving.ts`.
-            const serving = resolveServingConfig(this.config);
-            if (serving.allowOverride) {
-                const override = extractModelOverride({
-                    headers: req.headers,
-                    query: req.query,
-                    body: req.body,
-                });
-                if (override) {
-                    this.log.debug(`Model override: ${override}`);
-                    requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
-                }
-            }
+            this.configureRequestContextUser(requestContext);
+            this.configureRequestContextThreadId(req, res, requestContext);
+            this.configureRequestContextModelOverride(req, requestContext);
             next();
         });
     }
+    configureRequestContextUser(requestContext) {
+        if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key)))
+            return;
+        const executionContext = getExecutionContext();
+        const user = {
+            id: "userId" in executionContext
+                ? executionContext.userId
+                : executionContext.serviceUserId,
+            executionContext,
+        };
+        requestContext.set(MASTRA_USER_KEY, user);
+        requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+    }
+    configureRequestContextThreadId(req, res, requestContext) {
+        if (requestContext.get(MASTRA_THREAD_ID_KEY))
+            return;
+        const cookies = httpUtils.parseCookies(req.headers.cookie);
+        const cookieName = stringUtils.toIdentifierWithOptions({ delimiter: "_", distinct: true }, "appkit", this.config.name, "sessionId");
+        let sessionId = cookies[cookieName];
+        if (!sessionId) {
+            sessionId = randomUUID();
+            res.cookie(cookieName, sessionId, {
+                httpOnly: true,
+                sameSite: "lax",
+                secure: req.secure,
+                path: "/",
+            });
+        }
+        requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
+    }
+    configureRequestContextModelOverride(req, requestContext) {
+        // Per-request model override: only honored when the plugin
+        // opts in (default). Sources, in priority order, are
+        // `X-Mastra-Model` header, `?model=` query, and `model` /
+        // `modelId` body field; see `serving.ts`.
+        const serving = resolveServingConfig(this.config);
+        if (serving.allowOverride) {
+            const override = extractModelOverride({
+                headers: req.headers,
+                query: req.query,
+                body: req.body,
+            });
+            if (override)
+                requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
+        }
+    }
 }
 /**
  * Patches around `@mastra/express`'s custom-route dispatcher so

package/index.ts

@@ -13,6 +13,7 @@ export * from "./src/plugin.js";
 export * from "@dbx-tools/appkit-mastra-shared";
 export * from "./src/config.js";
 export * from "./src/agents.js";
+export * from "./src/chart.js";
 export * from "./src/genie.js";
 export {
   clearServingEndpointsCache,

package/package.json

@@ -28,12 +28,12 @@
     "directory": "packages/mastra"
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "module": "index.ts",
   "type": "module",
   "dependencies": {
-    "@dbx-tools/appkit-shared": "0.1.3",
-    "@dbx-tools/appkit-mastra-shared": "0.1.3",
+    "@dbx-tools/appkit-mastra-shared": "0.1.5",
+    "@dbx-tools/appkit-shared": "0.1.5",
     "@mastra/ai-sdk": "^1.3",
     "@mastra/core": "^1.32",
     "@mastra/express": "^1.3",

package/src/agents.ts

@@ -21,6 +21,7 @@ import { createTool } from "@mastra/core/tools";
 import type { Tool } from "@mastra/core/tools";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
+import { buildRenderDataTool } from "./chart.js";
 import type { MastraPluginConfig } from "./config.js";
 import { buildGenieProvider } from "./genie.js";
 import type { MemoryBuilder } from "./memory.js";
@@ -344,16 +345,21 @@ Rules:
  * Override globally via {@link MastraPluginConfig.styleInstructions}
  * (pass `false` to disable entirely, or a string to replace).
  */
-export const DEFAULT_STYLE_INSTRUCTIONS = `Output style:
-
-- Plain prose. Use hyphens (-) only. Never use em dashes (—) or en dashes (–).
-- Never use emojis.
-- Skip openers like "Great question", "Absolutely", "I'd be happy to help".
-- Skip closers like "Let me know if you have any questions".
-- Skip self-disclaimers ("I should mention", "It's important to note").
-- Answer directly. No preamble before the actual answer.
-- Use lists and headers only when they clarify a multi-part answer; not for short replies.
-- Quote numbers, code, identifiers, and tool output verbatim. Never paraphrase them.`;
+export const DEFAULT_STYLE_INSTRUCTIONS = [
+  "Output style:",
+  "",
+  "Use markdown formatting, including headings, lists, and code blocks.",
+  "Avoid lists and headers for short replies.",
+  "Plain prose.",
+  "Use hyphens (-) only. Never use em dashes or en dashes.",
+  "Never use emojis.",
+  "Skip openers like 'Great question', 'Absolutely', and 'I'd be happy to help'.",
+  "Skip closers like 'Let me know if you have any questions'.",
+  "Skip self-disclaimers like 'I should mention' and 'It's important to note'.",
+  "Answer directly.",
+  "Do not include a preamble before the actual answer.",
+  "Use lists and headers only when they clarify a multi-part answer.",
+].join("\n");
 
 /**
  * Resolve the style block to append to every agent's instructions.
@@ -364,6 +370,7 @@ function resolveStyleInstructions(config: MastraPluginConfig): string | null {
   if (typeof config.styleInstructions === "string") {
     return config.styleInstructions;
   }
+
   return DEFAULT_STYLE_INSTRUCTIONS;
 }
 
@@ -371,10 +378,7 @@ function resolveStyleInstructions(config: MastraPluginConfig): string | null {
  * Join an agent's bespoke instructions with the resolved style block.
  * Returns the bespoke text unchanged when the style block is disabled.
  */
-function composeInstructions(
-  agentInstructions: string,
-  style: string | null,
-): string {
+function composeInstructions(agentInstructions: string, style: string | null): string {
   if (!style) return agentInstructions;
   return `${agentInstructions.trimEnd()}\n\n${style}`;
 }
@@ -404,7 +408,15 @@ export async function buildAgents(opts: {
   const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
 
   const plugins = buildPluginsMap(context);
-  const ambientTools = config.tools ?? {};
+  // System-default ambient tools every agent gets out of the box.
+  // Currently just `render_data` for inline visualizations; the
+  // user can shadow it by including a same-named tool in their own
+  // `config.tools` or per-agent `tools`. Order in {@link resolveTools}
+  // is `system -> user-ambient -> per-agent`, last write wins.
+  const systemTools: MastraTools = {
+    render_data: buildRenderDataTool(config),
+  };
+  const ambientTools = { ...systemTools, ...(config.tools ?? {}) };
   const style = resolveStyleInstructions(config);
   const agents: Record<string, Agent> = {};