@dbx-tools/appkit-mastra 0.1.5 → 0.1.10

package/dist/src/plugin.js

@@ -1,255 +0,0 @@
-/**
- * AppKit plugin that builds one or more Mastra `Agent` instances and
- * mounts the `@mastra/express` server plus `@mastra/ai-sdk` `chatRoute`
- * handlers. The UI message stream matches what `chatRoute()` emits, so
- * the client can use `useChat()` from `@ai-sdk/react` without custom
- * parsing.
- *
- * - Agents: registered through `config.agents` at plugin creation
- *   ({@link MastraAgentDefinition}). Each entry's `tools` field accepts
- *   either a plain record or a `(plugins) => tools` callback that gets
- *   a typed sibling-plugin index ({@link MastraPlugins}). Omit
- *   `config.agents` to get a single built-in `default` analyst.
- * - Model: each agent call resolves a `MastraModelConfig` via
- *   {@link buildModel} from `./model.js`. Per-agent `model` overrides
- *   (`AgentConfig["model"]` or a `modelId` string) flow through
- *   {@link buildAgents}.
- * - Memory / storage: per-agent, built by {@link createMemoryBuilder}
- *   from `./memory.js`. Both auto-default to `true` when the
- *   `lakebase` plugin is registered (unless the caller passed
- *   `false` or a custom config). Storage namespaces per agent via
- *   `schemaName: "mastra_<agentId>"`; the vector store is a single
- *   shared singleton across every agent.
- * - Server: the Express subapp wiring lives in `./server.js`.
- * - HTTP: AppKit mounts this plugin under `/api/mastra`. `chatRoute`
- *   is registered at `/route/chat` (bound to `config.defaultAgent` or
- *   the first registered id) and `/route/chat/:agentId`, so the
- *   AI SDK transport URL is `/api/mastra/route/chat/<agentId>`.
- */
-import { genie, getExecutionContext, lakebase, Plugin, toPlugin, } from "@databricks/appkit";
-import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
-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";
-const GENIE_MANIFEST = pluginUtils.data(genie).plugin.manifest;
-const LAKEBASE_MANIFEST = pluginUtils.data(lakebase).plugin.manifest;
-/**
- * AppKit plugin (registered name: `mastra`) that hosts Mastra agents
- * with optional Lakebase-backed memory and AI SDK chat routes under
- * the plugin mount (typically `/api/mastra`).
- */
-export class MastraPlugin extends Plugin {
-    static manifest = {
-        name: "mastra",
-        displayName: "Mastra",
-        description: "Builds a Mastra Agent with user-scoped workspace auth (asUser) " +
-            "and optional Postgres-backed Mastra Memory via the `lakebase` plugin.",
-        stability: "beta",
-        resources: {
-            required: [],
-            optional: [
-                ...GENIE_MANIFEST.resources.required,
-                ...LAKEBASE_MANIFEST.resources.required,
-            ],
-        },
-    };
-    /**
-     * Tighten resource requirements based on which features are enabled.
-     * AppKit calls this at registration time (config-aware) so disabled
-     * features don't surface their resource asks to the host app.
-     */
-    static getResourceRequirements(config) {
-        const resources = [];
-        const enabledManifests = [];
-        if (needsLakebase(config)) {
-            enabledManifests.push(LAKEBASE_MANIFEST);
-        }
-        for (const m of enabledManifests) {
-            for (const resource of m.resources.required) {
-                resources.push({ ...resource, required: true });
-            }
-        }
-        return resources;
-    }
-    log = logUtils.logger(this);
-    built = null;
-    mastra = null;
-    mastraApp = null;
-    mastraServer = null;
-    async setup() {
-        // Wait until sibling plugins (e.g. `lakebase`) finish `setup()` so
-        // the lakebase pool is valid when storage/memory are enabled.
-        this.context?.onLifecycle("setup:complete", async () => {
-            this.applyLakebaseAutoDefaults();
-            this.log.info("setup:complete");
-            await this.buildAgentAndServer();
-        });
-    }
-    /**
-     * When the `lakebase` plugin is registered, auto-enable `storage`
-     * and `memory` unless the caller opted out explicitly (`false` or a
-     * custom config object). Run after `setup:complete` so the lookup
-     * is reliable: any plugin that registers itself synchronously is
-     * already in the registry by the time this fires.
-     */
-    applyLakebaseAutoDefaults() {
-        const hasLakebase = pluginUtils.instance(this.context, lakebase) !== undefined;
-        if (!hasLakebase)
-            return;
-        if (this.config.storage === undefined)
-            this.config.storage = true;
-        if (this.config.memory === undefined)
-            this.config.memory = true;
-    }
-    exports() {
-        return {
-            /**
-             * Ids of every registered agent in registration order. Matches
-             * AppKit `agents.list()` so callers can iterate the registry the
-             * same way under both plugins.
-             */
-            list: () => Object.keys(this.built?.agents ?? {}),
-            /**
-             * Look up a registered agent by id. Returns `null` (not
-             * undefined) when unknown so call sites can early-return without
-             * a separate `in` check.
-             */
-            get: (id) => this.built?.agents[id] ?? null,
-            /**
-             * The agent `chatRoute` binds to when the client doesn't name
-             * one. Resolves to `config.defaultAgent`, the first registered
-             * id, or the built-in `default` fallback.
-             */
-            getDefault: () => (this.built && this.built.agents[this.built.defaultAgentId]) ?? null,
-            /** Underlying Mastra instance for advanced use (custom routes etc.). */
-            getMastra: () => this.mastra,
-            /** Express subapp Mastra is mounted on; mostly for tests. */
-            getMastraServer: () => this.mastraServer,
-            /**
-             * Fetch the workspace's Model Serving endpoints (cached). Same
-             * payload the `GET /models` route returns; surfaced here so
-             * other plugins / scripts can introspect the catalogue without
-             * an HTTP round-trip. AppKit wraps this with `asUser(req)` for
-             * OBO scoping automatically.
-             */
-            listModels: () => this.listModels(),
-            /**
-             * Force-evict cached endpoint listings via AppKit's
-             * `CacheManager`. Useful in tests or right after an admin
-             * deploys a new endpoint and doesn't want to wait for the TTL.
-             * Returns the underlying `CacheManager.delete`/`clear` promise.
-             */
-            clearModelsCache: (host) => clearServingEndpointsCache(host),
-        };
-    }
-    clientConfig() {
-        // AppKit mounts every plugin at `/api/<plugin.name>`. `this.name`
-        // honors `config.name` overrides, so the published paths stay
-        // accurate if someone remounts the plugin under a custom id.
-        // Return widens to `Record<string, unknown>` to satisfy the
-        // base-class signature; consumers read it through the typed
-        // `MastraClientConfig` shape via `usePluginClientConfig<...>(...)`.
-        const basePath = `/api/${this.name}`;
-        const config = {
-            basePath,
-            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 ?? {}),
-        };
-        return config;
-    }
-    injectRoutes(router) {
-        // `GET /models` exposes the cached endpoint list so clients can
-        // populate model pickers, validate `?model=` choices, etc. Must
-        // be registered before the catch-all that forwards everything to
-        // 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.userScopedSelf(req)
-                .listModels()
-                .then((endpoints) => res.json({ endpoints }))
-                .catch(next);
-        });
-        router.use("", (req, res, next) => {
-            if (!this.mastraApp)
-                return res.status(503).end();
-            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
-     * `getExecutionContext()` returns the OBO-scoped client.
-     */
-    async listModels() {
-        const client = getExecutionContext().client;
-        const host = (await client.config.getHost()).toString();
-        const serving = resolveServingConfig(this.config);
-        return listServingEndpoints(client, host, { ttlMs: serving.ttlMs });
-    }
-    async buildAgentAndServer() {
-        // Per-agent memory factory. The builder resolves the Lakebase pool
-        // lazily (on first agent that actually needs storage / vector) and
-        // caches both the pool and the shared `PgVector` singleton so
-        // registering N agents stays cheap. See `./memory.js`.
-        const memoryBuilder = needsLakebase(this.config)
-            ? createMemoryBuilder(this.config, this.context)
-            : undefined;
-        // 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
-        // distinct user identities; the `asUser(req)` scope around
-        // `handleChat` is what lets `getExecutionContext()` return the
-        // right user inside the resolver.
-        this.built = await buildAgents({
-            config: this.config,
-            context: this.context,
-            memoryBuilder,
-            log: this.log,
-        });
-        // `mastra.server.apiRoutes` is only honored by Mastra's standalone
-        // dev server. Since we're hosting Mastra inside our own Express
-        // subapp via `@mastra/express`, custom routes must be passed to
-        // the `MastraServer` constructor directly.
-        this.mastra = new Mastra({ agents: this.built.agents });
-        this.mastraApp = express();
-        attachRoutePatchMiddleware(this.mastraApp);
-        this.mastraServer = new MastraServer(this.config, {
-            app: this.mastraApp,
-            mastra: this.mastra,
-            prefix: "",
-            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();
-    }
-}
-export const mastra = toPlugin(MastraPlugin);

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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,120 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * Express-layer plumbing for the Mastra plugin: a `MastraServer` that
- * stamps the per-request `RequestContext`, and a route-patch middleware
- * 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";
-/**
- * `@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;
-    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
- * `chatRoute` works when `MastraServer` is hosted on an Express subapp
- * mounted under a parent path (e.g. `/api/mastra`).
- *
- * Two concerns:
- *
- * 1. 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 `chatRoute` paths
- *    (for example `/route/chat`), so the absolute URL never matches
- *    until we overwrite `originalUrl` for `/route` and `/route/*` to
- *    the mount-relative path.
- *
- * 2. `memory.resource` must be the authenticated user, not whatever the
- *    client posts. The custom-route forwarder re-serializes `req.body`
- *    into the Request body it hands Hono, so mutating the parsed body
- *    here would propagate into `handleChatStream`'s params (kept for
- *    future use; `express.json()` runs first so `req.body` is parsed).
- */
-export declare function attachRoutePatchMiddleware(app: express.Express): void;

package/dist/src/server.js

@@ -1,113 +0,0 @@
-/**
- * Express-layer plumbing for the Mastra plugin: a `MastraServer` that
- * stamps the per-request `RequestContext`, and a route-patch middleware
- * that lets `@mastra/ai-sdk` `chatRoute` work behind an Express mount
- * point.
- */
-import { getExecutionContext } from "@databricks/appkit";
-import { httpUtils, logUtils, stringUtils } from "@dbx-tools/appkit-shared";
-import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
-import { MastraServer as MastraServerExpress } from "@mastra/express";
-import { randomUUID } from "node:crypto";
-import { MASTRA_USER_KEY } from "./config.js";
-import { extractModelOverride, MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig, } from "./serving.js";
-/**
- * `@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 class MastraServer extends MastraServerExpress {
-    config;
-    log;
-    constructor(config, ...args) {
-        super(...args);
-        this.config = config;
-        this.log = logUtils.logger(config);
-    }
-    registerAuthMiddleware() {
-        super.registerAuthMiddleware();
-        this.app.use((req, res, next) => {
-            const requestContext = res.locals.requestContext;
-            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
- * `chatRoute` works when `MastraServer` is hosted on an Express subapp
- * mounted under a parent path (e.g. `/api/mastra`).
- *
- * Two concerns:
- *
- * 1. 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 `chatRoute` paths
- *    (for example `/route/chat`), so the absolute URL never matches
- *    until we overwrite `originalUrl` for `/route` and `/route/*` to
- *    the mount-relative path.
- *
- * 2. `memory.resource` must be the authenticated user, not whatever the
- *    client posts. The custom-route forwarder re-serializes `req.body`
- *    into the Request body it hands Hono, so mutating the parsed body
- *    here would propagate into `handleChatStream`'s params (kept for
- *    future use; `express.json()` runs first so `req.body` is parsed).
- */
-export function attachRoutePatchMiddleware(app) {
-    app.use((req, _res, next) => {
-        const isChat = req.path === "/route" || req.path.startsWith("/route/");
-        if (!isChat)
-            return next();
-        req.originalUrl = req.path;
-        next();
-    });
-}