@dbx-tools/appkit-mastra 0.1.3 → 0.1.5

package/src/history.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 type { Agent } from "@mastra/core/agent";
+import type {
+  MastraDBMessage,
+} from "@mastra/core/agent/message-list";
+import {
+  MASTRA_RESOURCE_ID_KEY,
+  MASTRA_THREAD_ID_KEY,
+} from "@mastra/core/request-context";
+import { registerApiRoute } from "@mastra/core/server";
+import type {
+  MastraHistoryResponse,
+  MastraHistoryUIMessage,
+} from "@dbx-tools/appkit-mastra-shared";
+
+/** 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;
+
+/** 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 async function loadHistory(
+  opts: LoadHistoryOptions,
+): Promise<MastraHistoryResponse> {
+  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,
+  ) as unknown as MastraHistoryUIMessage[];
+  return {
+    uiMessages,
+    page,
+    perPage,
+    total: result.total,
+    hasMore: result.hasMore,
+  };
+}
+
+/** 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 function historyRoute(options: HistoryRouteOptions) {
+  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) as
+        | string
+        | undefined;
+      if (!threadId) {
+        return c.json({ error: "thread id missing from request context" }, 400);
+      }
+      const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as
+        | string
+        | undefined;
+      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: number | undefined): number {
+  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: MastraDBMessage[]): MastraDBMessage[] {
+  return [...messages].sort((a, b) => {
+    const ta = toEpoch(a.createdAt);
+    const tb = toEpoch(b.createdAt);
+    return ta - tb;
+  });
+}
+
+function toEpoch(value: unknown): number {
+  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: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  return Math.trunc(n);
+}

package/src/plugin.ts

@@ -46,6 +46,8 @@ import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.js";
 import type { MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
 import type { MastraPluginConfig } from "./config.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 {
@@ -187,6 +189,9 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       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 ?? {}),
     };
@@ -200,7 +205,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // 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);
@@ -208,10 +213,23 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
 
     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).
+   */
+  private userScopedSelf(req: express.Request): this {
+    return req.header("x-forwarded-access-token") ? (this.asUser(req) as this) : this;
+  }
+
   /**
    * Implementation backing both the `/models` route and the
    * `listModels` export. Runs inside the AppKit user-context proxy so
@@ -260,6 +278,9 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       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/src/render-chart-route.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 {
+  RenderChartRequest,
+  RenderChartResponse,
+} from "@dbx-tools/appkit-mastra-shared";
+import { registerApiRoute } from "@mastra/core/server";
+
+import { runChartPlanner } from "./chart.js";
+import type { MastraPluginConfig } from "./config.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;
+
+/** 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 function renderChartRoute(options: RenderChartRouteOptions) {
+  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)) as unknown;
+      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: RenderChartResponse = {
+          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);
+      }
+    },
+  });
+}
+
+type ValidationResult =
+  | { body: RenderChartRequest }
+  | { error: string };
+
+/**
+ * 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: unknown): ValidationResult {
+  if (!raw || typeof raw !== "object") {
+    return { error: "request body must be a JSON object" };
+  }
+  const r = raw as Record<string, unknown>;
+  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 as Array<Record<string, unknown>>,
+    },
+  };
+}

package/src/server.ts

@@ -42,61 +42,75 @@ export class MastraServer extends MastraServerExpress {
   override registerAuthMiddleware(): void {
     super.registerAuthMiddleware();
     this.app.use((req, res, next) => {
-      const executionContext = getExecutionContext();
-      const user: User = {
-        id:
-          "userId" in executionContext
-            ? executionContext.userId
-            : executionContext.serviceUserId,
-        executionContext,
-      };
       const requestContext = res.locals.requestContext! as 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 as Record<string, string | string[] | undefined>,
-          query: req.query as Record<string, unknown>,
-          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: RequestContext) {
+    if (
+      [MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))
+    )
+      return;
+    const executionContext = getExecutionContext();
+    const user: 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: express.Request,
+    res: express.Response,
+    requestContext: 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: express.Request,
+    requestContext: 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 as Record<string, string | string[] | undefined>,
+        query: req.query as Record<string, unknown>,
+        body: req.body,
+      });
+      if (override) requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
+    }
+  }
 }
 
 /**