@dbx-tools/appkit-mastra 0.1.41 → 0.1.48

package/dist/src/model.js

@@ -7,214 +7,24 @@
  * fresh bearer header, then point Mastra's OpenAI-compatible provider
  * at `/serving-endpoints` on that host.
  *
- * Model id resolution walks three sources before falling back to the
- * hard-coded default, **in this priority order**:
- *
- *   1. Per-request override stashed by the auth middleware under
- *      {@link MASTRA_MODEL_OVERRIDE_KEY} (header / query / body).
- *   2. The static `modelId` passed in by the agent / plugin (string
- *      sugar on `def.model` or `config.defaultModel`).
- *   3. `DATABRICKS_SERVING_ENDPOINT_NAME` env var.
- *   4. {@link FALLBACK_MODEL_ID}.
- *
- * Whatever wins is then fuzzy-matched against the live
- * `/serving-endpoints` list ({@link listServingEndpoints}) so loose
- * names like `"claude sonnet"` resolve to the real endpoint name.
- * Fuzzy matching is best-effort: when the workspace client throws
- * (network blip, expired token at cache-fill time) we fall back to
- * the input verbatim and let Databricks return the canonical error.
+ * This module only adds the Mastra-specific glue. The actual model
+ * selection - listing the workspace catalogue and resolving an
+ * explicit name / class / fallback chain to a real endpoint id - lives
+ * in `@dbx-tools/model` ({@link selectModel}) so non-Mastra consumers
+ * (e.g. a job that just needs a model name) can reuse it. Here we
+ * assemble the explicit ask from Mastra's request context (the
+ * per-request override under {@link MASTRA_MODEL_OVERRIDE_KEY}, the
+ * agent / plugin `modelId`, or `DATABRICKS_SERVING_ENDPOINT_NAME`),
+ * pass the plugin's fuzzy / class / fallback knobs through, and wrap
+ * the resolved id in the OpenAI-compatible provider config Mastra
+ * expects. Catalogue fetches fail loud: network / auth errors
+ * propagate so callers see the real SDK message.
  */
+import { parseModelClass, selectModel } from "@dbx-tools/model";
 import { commonUtils, logUtils, netUtils, stringUtils } from "@dbx-tools/shared";
 import { MASTRA_USER_KEY } from "./config.js";
-import { listServingEndpoints, MASTRA_MODEL_OVERRIDE_KEY, resolveModelId, resolveServingConfig, } from "./serving.js";
-/**
- * Capability tiers for Databricks Foundation Model API endpoints.
- *
- * - {@link ModelTier.Thinking}: deepest reasoning / "thinking" models
- *   (Claude Opus, GPT-5.5 Pro, Gemini Pro, Llama 4 Maverick, etc).
- *   Highest cost and latency; reserve for hard multi-step reasoning.
- * - {@link ModelTier.Balanced}: cost/latency sweet spot for general
- *   agent work (Claude Sonnet, GPT-5.x, Gemini Flash, Llama 3.3 70B).
- *   The right default for most agents.
- * - {@link ModelTier.Fast}: cheap and quick; classification, routing,
- *   tool-arg extraction, simple summarisation (Claude Haiku, GPT-5
- *   mini/nano, Gemini Flash Lite, GPT-OSS 20B, Llama 3.1 8B).
- *
- * String enum so the value is the slug we use in cache keys, logs,
- * and as the value users see in serialized configs.
- */
-export var ModelTier;
-(function (ModelTier) {
-    ModelTier["Thinking"] = "thinking";
-    ModelTier["Balanced"] = "balanced";
-    ModelTier["Fast"] = "fast";
-})(ModelTier || (ModelTier = {}));
-/**
- * Catalogue of Databricks-hosted Foundation Model API endpoints,
- * grouped by capability {@link ModelTier} and then by provider. Each
- * inner array is priority-ordered (most powerful first within the
- * same provider+tier).
- *
- * Provider buckets:
- *
- * - `claude`: Anthropic Claude family (closed; flagship reasoning).
- * - `gpt`: OpenAI GPT-5 family (closed; "ChatGPT" on Databricks FMAPI).
- * - `gemini`: Google Gemini family (closed; multimodal + web-search).
- * - `openSource`: open-weights models (widest regional / SKU availability).
- *
- * The list is curated by hand; refresh from the Databricks "supported
- * foundation models" doc when new endpoints land.
- */
-export const MODEL_CATALOG = {
-    [ModelTier.Thinking]: {
-        claude: [
-            "databricks-claude-opus-4-8",
-            "databricks-claude-opus-4-7",
-            "databricks-claude-opus-4-6",
-            "databricks-claude-opus-4-5",
-            "databricks-claude-opus-4-1",
-        ],
-        gpt: ["databricks-gpt-5-5-pro"],
-        gemini: [
-            "databricks-gemini-3-1-pro",
-            "databricks-gemini-3-pro",
-            "databricks-gemini-2-5-pro",
-        ],
-        openSource: [
-            "databricks-llama-4-maverick",
-            "databricks-gpt-oss-120b",
-            "databricks-meta-llama-3-1-405b-instruct",
-        ],
-    },
-    [ModelTier.Balanced]: {
-        claude: [
-            "databricks-claude-sonnet-4-6",
-            "databricks-claude-sonnet-4-5",
-            "databricks-claude-sonnet-4",
-        ],
-        gpt: [
-            "databricks-gpt-5-5",
-            "databricks-gpt-5-4",
-            "databricks-gpt-5-2",
-            "databricks-gpt-5-1",
-            "databricks-gpt-5",
-        ],
-        gemini: [
-            "databricks-gemini-3-5-flash",
-            "databricks-gemini-3-flash",
-            "databricks-gemini-2-5-flash",
-        ],
-        openSource: [
-            "databricks-meta-llama-3-3-70b-instruct",
-            "databricks-qwen3-next-80b-a3b-instruct",
-            "databricks-qwen35-122b-a10b",
-        ],
-    },
-    [ModelTier.Fast]: {
-        claude: ["databricks-claude-haiku-4-5"],
-        gpt: [
-            "databricks-gpt-5-4-mini",
-            "databricks-gpt-5-4-nano",
-            "databricks-gpt-5-mini",
-            "databricks-gpt-5-nano",
-        ],
-        gemini: ["databricks-gemini-3-1-flash-lite"],
-        openSource: [
-            "databricks-gpt-oss-20b",
-            "databricks-gemma-3-12b",
-            "databricks-meta-llama-3-1-8b-instruct",
-        ],
-    },
-};
-/**
- * Round-robin zip: take one from each input list in order, skipping
- * lists that have already been exhausted. Used to interleave provider
- * buckets within a tier so the resolver alternates between vendors
- * instead of draining one before trying the next.
- *
- * Example: `interleave(["a1","a2","a3"], ["b1","b2"])` ->
- * `["a1","b1","a2","b2","a3"]`.
- */
-function interleave(...lists) {
-    const out = [];
-    const max = Math.max(0, ...lists.map((l) => l.length));
-    for (let i = 0; i < max; i++) {
-        for (const list of lists) {
-            if (i < list.length)
-                out.push(list[i]);
-        }
-    }
-    return out;
-}
-/**
- * Priority-ordered model ids for a single capability {@link ModelTier},
- * interleaved across providers so a workspace missing the top Claude
- * still lands on a flagship GPT / Gemini on the next probe.
- *
- * Provider order within the interleave: Claude, GPT, Gemini, then the
- * open-weights tail appended verbatim as the universal floor (widest
- * regional availability).
- *
- * @example
- * ```ts
- * mastra({
- *   defaultModelFallbacks: modelsForTier(ModelTier.Fast),
- * });
- * ```
- */
-export function modelsForTier(tier) {
-    const bucket = MODEL_CATALOG[tier];
-    return [
-        ...interleave(bucket.claude, bucket.gpt, bucket.gemini),
-        ...bucket.openSource,
-    ];
-}
-/**
- * Top model id at the given {@link ModelTier}. Sync; the agent-step
- * resolver fuzzy-matches it against the workspace catalogue at call
- * time, so this works even when the literal top pick isn't deployed.
- *
- * Use when wiring a tier-appropriate model into an agent definition:
- *
- * @example
- * ```ts
- * const classifier = createAgent({
- *   instructions: "Classify this email",
- *   model: modelForTier(ModelTier.Fast),  // cheap, quick
- * });
- *
- * const planner = createAgent({
- *   instructions: "Plan a multi-step migration",
- *   model: modelForTier(ModelTier.Thinking),  // deep reasoning
- * });
- * ```
- */
-export function modelForTier(tier) {
-    return modelsForTier(tier)[0];
-}
-/**
- * Last-resort model ids used when neither `config.defaultModel`,
- * per-agent `model`, nor `DATABRICKS_SERVING_ENDPOINT_NAME` is set.
- *
- * Walked in order at resolve time: the first id whose endpoint is
- * actually present in the workspace's `/serving-endpoints` listing
- * wins. Workspaces vary - not every region / SKU has every model,
- * and the list of Foundation Model APIs evolves quickly - so the
- * resolver degrades all the way from "best thinking model" down to
- * "smallest commodity Llama" before giving up.
- *
- * Built by chaining the per-tier interleaves (Thinking -> Balanced
- * -> Fast); within each tier the providers are round-robin-zipped
- * (Claude, GPT, Gemini, then open-weights tail). Override the entire
- * list via `MastraPluginConfig.defaultModelFallbacks` (e.g. to pin a
- * regulated workspace to a specific approved subset, or to bias the
- * priority toward a particular tier).
- */
-export const FALLBACK_MODEL_IDS = [
-    ...modelsForTier(ModelTier.Thinking),
-    ...modelsForTier(ModelTier.Balanced),
-    ...modelsForTier(ModelTier.Fast),
-];
+import { MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig } from "./serving.js";
+export { classifyEndpoints, FALLBACK_MODEL_IDS, ModelClass, modelForClass, modelsForClass, } from "@dbx-tools/model";
 /**
  * Resolve a `MastraModelConfig` for the current agent step. Runs
  * while `agent.stream` is inside the `asUser(req)` scope so tokens
@@ -232,76 +42,37 @@ export async function buildModel(config, requestContext, overrides = {}) {
     // URL we hand it. Drop the trailing slash so the resulting URL stays
     // well-formed (`/serving-endpoints/chat/completions`).
     const url = new URL("/serving-endpoints", host).toString().replace(/\/$/, "");
-    const modelId = await pickModelId(config, requestContext, overrides, user, host);
-    return {
-        providerId: config.providerId ?? "databricks",
-        modelId,
-        url,
-        headers: Object.fromEntries(headers.entries()),
-    };
-}
-/**
- * Walk the resolution ladder and pick a modelId.
- *
- * 1. **Explicit ask** (per-request override, agent `model` string,
- *    `config.defaultModel` string, or `DATABRICKS_SERVING_ENDPOINT_NAME`):
- *    when fuzzy matching is on, snap the input to the closest live
- *    endpoint so loose names like `"claude sonnet"` resolve. When it's
- *    off (or no endpoint matches within threshold), the input is used
- *    verbatim and Databricks surfaces the canonical 404.
- *
- * 2. **No explicit ask**: walk
- *    {@link MastraPluginConfig.defaultModelFallbacks} (or
- *    {@link FALLBACK_MODEL_IDS} when unset) and return the first id
- *    whose endpoint is actually present in the workspace listing. A
- *    workspace without Claude Opus still gets a sensible default by
- *    skipping ahead to whichever Sonnet / GPT-5 / Llama variant is
- *    wired up.
- *
- * Catalogue fetches fail loud: network / auth errors propagate to the
- * caller so they see the real SDK message instead of a silent fallback
- * to the top of the priority list.
- */
-async function pickModelId(config, requestContext, overrides, user, host) {
     const log = logUtils.logger(config);
-    const serving = resolveServingConfig(config, FALLBACK_MODEL_IDS);
+    const serving = resolveServingConfig(config);
     const override = serving.allowOverride
         ? requestContext.get(MASTRA_MODEL_OVERRIDE_KEY)
         : undefined;
-    const explicit = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
-    // Cheap exit: when the caller named a specific model and fuzzy
-    // matching is off, there's no reason to touch the catalogue at all.
-    if (explicit !== undefined && !serving.fuzzy) {
-        log.debug("model selected", { modelId: explicit, source: "explicit" });
-        return explicit;
-    }
-    const endpoints = await listServingEndpoints(user.executionContext.client, host, {
+    // The override / agent default / env value can be either a concrete
+    // endpoint name or a model class slug ("chat-thinking" /
+    // "chat-balanced" / "chat-fast"). A class slug becomes a class intent
+    // (let the live catalogue pick the best model in that band); anything
+    // else is an explicit name fuzzy-matched against the catalogue. An
+    // internal `overrides.modelClass` (e.g. the chart planner) is the
+    // floor when nothing was requested.
+    const requested = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
+    const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
+    const explicit = requestedClass === null ? requested : undefined;
+    const modelClass = requestedClass ?? overrides.modelClass;
+    const { modelId, source } = await selectModel(user.executionContext.client, host, {
+        ...(explicit !== undefined ? { explicit } : {}),
+        fuzzy: serving.fuzzy,
+        threshold: serving.threshold,
+        ...(modelClass !== undefined ? { modelClass } : {}),
+        fallbacks: serving.fallbacks,
         ttlMs: serving.ttlMs,
     });
-    const modelId = explicit !== undefined
-        ? resolveModelId(explicit, endpoints, { threshold: serving.threshold }).modelId
-        : pickFirstAvailable(serving.fallbacks, endpoints);
-    log.debug("model selected", {
+    log.debug("model selected", { modelId, source, requested });
+    return {
+        providerId: config.providerId ?? "databricks",
         modelId,
-        source: explicit !== undefined ? "fuzzy-match" : "fallback",
-        requestedExplicit: explicit,
-    });
-    return modelId;
-}
-/**
- * Find the first id in `fallbacks` whose endpoint is present in
- * `endpoints`. Returns the top fallback when the workspace has none
- * of them so callers always get a string; an offline workspace will
- * then receive a clean 404 from Databricks instead of a malformed
- * config.
- */
-function pickFirstAvailable(fallbacks, endpoints) {
-    const present = new Set(endpoints.map((e) => e.name));
-    for (const candidate of fallbacks) {
-        if (present.has(candidate))
-            return candidate;
-    }
-    return fallbacks[0] ?? FALLBACK_MODEL_IDS[0];
+        url,
+        headers: Object.fromEntries(headers.entries()),
+    };
 }
 /** Path prefix that identifies a Databricks Model Serving REST call. */
 const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";

package/dist/src/plugin.d.ts

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * mounts the `@mastra/express` server. Clients drive the conversation
+ * over the standard Mastra agent stream (`@mastra/client-js`'s
+ * `getAgent(id).stream()`), so there's no bespoke chat transport to
+ * keep in sync.
  *
  * - Agents: registered through `config.agents` at plugin creation
  *   ({@link MastraAgentDefinition}). Each entry's `tools` field accepts
@@ -21,17 +21,18 @@
  *   `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>`.
+ * - HTTP: AppKit mounts this plugin under `/api/mastra`. Alongside the
+ *   Mastra agent routes, the plugin registers `/route/history`
+ *   (load + clear thread history), `/models`, `/suggestions`, and the
+ *   generic `/embed/:type/:id` resolver for inline chart / data
+ *   markers.
  */
 import { Plugin, type IAppRouter, type ResourceRequirement } from "@databricks/appkit";
 import type { Agent } from "@mastra/core/agent";
 import { Mastra } from "@mastra/core/mastra";
+import { type ServingEndpointSummary } from "@dbx-tools/model";
 import type { MastraPluginConfig } from "./config.js";
 import { MastraServer } from "./server.js";
-import { type ServingEndpointSummary } from "./serving.js";
 /**
  * AppKit plugin (registered name: `mastra`) that hosts Mastra agents
  * with optional Lakebase-backed memory and AI SDK chat routes under
@@ -97,9 +98,9 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
          */
         get: (id: string) => Agent | 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.
+         * The agent the client converses with when it doesn't name one.
+         * Resolves to `config.defaultAgent`, the first registered id, or
+         * the built-in `default` fallback.
          */
         getDefault: () => Agent | null;
         /** Underlying Mastra instance for advanced use (custom routes etc.). */

package/dist/src/plugin.js

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * mounts the `@mastra/express` server. Clients drive the conversation
+ * over the standard Mastra agent stream (`@mastra/client-js`'s
+ * `getAgent(id).stream()`), so there's no bespoke chat transport to
+ * keep in sync.
  *
  * - Agents: registered through `config.agents` at plugin creation
  *   ({@link MastraAgentDefinition}). Each entry's `tools` field accepts
@@ -21,16 +21,18 @@
  *   `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>`.
+ * - HTTP: AppKit mounts this plugin under `/api/mastra`. Alongside the
+ *   Mastra agent routes, the plugin registers `/route/history`
+ *   (load + clear thread history), `/models`, `/suggestions`, and the
+ *   generic `/embed/:type/:id` resolver for inline chart / data
+ *   markers.
  */
 import { genie, getExecutionContext, lakebase, Plugin, toPlugin, } from "@databricks/appkit";
 import { appkitUtils, commonUtils, logUtils } from "@dbx-tools/shared";
-import { chatRoute } from "@mastra/ai-sdk";
 import { Mastra } from "@mastra/core/mastra";
 import express from "express";
+import { MASTRA_ROUTES, } from "@dbx-tools/appkit-mastra-shared";
+import { clearServingEndpointsCache, listServingEndpoints, } from "@dbx-tools/model";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.js";
 import { fetchChart } from "./chart.js";
 import { collectSpaceSuggestions, resolveGenieSpaces } from "./genie.js";
@@ -38,7 +40,7 @@ import { historyRoute } from "./history.js";
 import { createMemoryBuilder, createServicePrincipalPool, needsLakebase, } from "./memory.js";
 import { buildObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
-import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
+import { resolveServingConfig } from "./serving.js";
 import { fetchStatementData, isStatementNotFoundError, STATEMENT_ROW_CAP, } from "./statement.js";
 const GENIE_MANIFEST = appkitUtils.data(genie).plugin.manifest;
 const LAKEBASE_MANIFEST = appkitUtils.data(lakebase).plugin.manifest;
@@ -160,9 +162,9 @@ export class MastraPlugin extends Plugin {
              */
             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.
+             * The agent the client converses with when it 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.). */
@@ -188,22 +190,16 @@ export class MastraPlugin extends Plugin {
     }
     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.
+        // honors `config.name` overrides, so publishing `basePath` is
+        // enough for the client to stay correct under a custom mount id -
+        // the per-route segments are fixed (`MASTRA_ROUTES`) and the
+        // client (`MastraPluginClient`) derives every endpoint from
+        // `basePath`.
         // 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`,
-            embedPathTemplate: `${basePath}/embed/:type/:id`,
-            suggestionsPath: `${basePath}/suggestions`,
-            suggestionsPathTemplate: `${basePath}/suggestions/:agentId`,
+            basePath: `/api/${this.name}`,
             defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
             agents: Object.keys(this.built?.agents ?? {}),
         };
@@ -215,7 +211,7 @@ export class MastraPlugin extends Plugin {
         // 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) => {
+        router.get(MASTRA_ROUTES.models, (req, res, next) => {
             this.userScopedSelf(req)
                 .listModels()
                 .then((endpoints) => res.json({ endpoints }))
@@ -267,7 +263,7 @@ export class MastraPlugin extends Plugin {
                 });
             },
         };
-        router.get("/embed/:type/:id", (req, res, next) => {
+        router.get(`${MASTRA_ROUTES.embed}/:type/:id`, (req, res, next) => {
             const type = req.params["type"] ?? "";
             const id = req.params["id"];
             const resolve = embedResolvers[type];
@@ -322,8 +318,8 @@ export class MastraPlugin extends Plugin {
                 res.json({ questions: [] });
             });
         };
-        router.get("/suggestions", handleSuggestions);
-        router.get("/suggestions/:agentId", handleSuggestions);
+        router.get(MASTRA_ROUTES.suggestions, handleSuggestions);
+        router.get(`${MASTRA_ROUTES.suggestions}/:agentId`, handleSuggestions);
         router.use((req, res, next) => {
             if (!this.mastraApp)
                 return res.status(503).end();
@@ -495,20 +491,28 @@ export class MastraPlugin extends Plugin {
             mastra: this.mastra,
             prefix: "",
             customApiRoutes: [
-                chatRoute({ path: "/route/chat", agent: this.built.defaultAgentId }),
-                chatRoute({ path: "/route/chat/:agentId" }),
                 // `historyRoute` registers both GET (load) and DELETE
                 // (clear) on the same path, so it returns an array we
                 // splice in.
-                ...historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
-                ...historyRoute({ path: "/route/history/:agentId" }),
+                ...historyRoute({
+                    path: MASTRA_ROUTES.history,
+                    agent: this.built.defaultAgentId,
+                }),
+                // Assert the `:agentId` template type: the per-package build's
+                // NodeNext resolution widens the imported `MASTRA_ROUTES.history`
+                // to `string` (the source/bundler typecheck keeps it a literal),
+                // which would otherwise drop this out of the dynamic-agent
+                // overload and demand a fixed `agent`.
+                ...historyRoute({
+                    path: `${MASTRA_ROUTES.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"],
+            routes: ["/route/history", "/models", "/suggestions", "/embed/:type/:id"],
             instanceStorage: instanceStorage !== undefined,
             observability: observability !== undefined ? "mlflow" : "off",
         });

package/dist/src/server.d.ts

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * that lets the plugin's custom API routes (e.g. `historyRoute`) work
+ * behind an Express mount point.
  */
 import { type RequestContext } from "@mastra/core/request-context";
 import { MastraServer as MastraServerExpress } from "@mastra/express";
@@ -35,24 +35,17 @@ export declare class MastraServer extends MastraServerExpress {
     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`).
+ * Patches around `@mastra/express`'s custom-route dispatcher so the
+ * plugin's custom API routes (e.g. `historyRoute`) work 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).
+ * 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 route paths
+ * (for example `/route/history`), so the absolute URL never matches
+ * until we overwrite `originalUrl` for `/route` and `/route/*` to the
+ * mount-relative path.
  */
 export declare function attachRoutePatchMiddleware(app: express.Express): void;

package/dist/src/server.js

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * that lets the plugin's custom API routes (e.g. `historyRoute`) work
+ * behind an Express mount point.
  */
 import { getExecutionContext } from "@databricks/appkit";
 import { httpUtils, logUtils, stringUtils } from "@dbx-tools/shared";
@@ -128,30 +128,23 @@ export class MastraServer extends MastraServerExpress {
     }
 }
 /**
- * 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`).
+ * Patches around `@mastra/express`'s custom-route dispatcher so the
+ * plugin's custom API routes (e.g. `historyRoute`) work 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).
+ * 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 route paths
+ * (for example `/route/history`), so the absolute URL never matches
+ * until we overwrite `originalUrl` for `/route` and `/route/*` to the
+ * mount-relative path.
  */
 export function attachRoutePatchMiddleware(app) {
     app.use((req, _res, next) => {
-        const isChat = req.path === "/route" || req.path.startsWith("/route/");
-        if (!isChat)
+        const isCustomRoute = req.path === "/route" || req.path.startsWith("/route/");
+        if (!isCustomRoute)
             return next();
         req.originalUrl = req.path;
         next();