@dbx-tools/appkit-mastra 0.1.12 → 0.1.14

package/dist/src/plugin.js

@@ -1,261 +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 { 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`,
-            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;
-        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
-        // 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" }),
-            ],
-        });
-        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

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

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

@@ -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,123 +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);
-            this.log.debug("auth:middleware", {
-                method: req.method,
-                path: req.path,
-                threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
-                resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
-                modelOverride: requestContext.get(
-                // imported below; logged so a misrouted request shows
-                // up alongside its model selection in `LOG_LEVEL=debug`.
-                "mastra__model_override"),
-            });
-            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();
-    });
-}