@dbx-tools/appkit-mastra 0.1.40 → 0.1.42

package/src/model.ts

@@ -7,237 +7,53 @@
  * 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 / tier / 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 / tier / 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 { type ModelTier, parseModelTier, selectModel } from "@dbx-tools/model";
 import { commonUtils, logUtils, netUtils, stringUtils } from "@dbx-tools/shared";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
 
 import { MASTRA_USER_KEY, type MastraPluginConfig, type User } from "./config.js";
-import {
-  listServingEndpoints,
-  MASTRA_MODEL_OVERRIDE_KEY,
-  resolveModelId,
-  resolveServingConfig,
-  type ServingEndpointSummary,
-} 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 enum ModelTier {
-  Thinking = "thinking",
-  Balanced = "balanced",
-  Fast = "fast",
-}
-
-/**
- * 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",
-    ],
-  },
-} as const satisfies Record<ModelTier, Record<string, readonly string[]>>;
-
-/**
- * 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<T>(...lists: readonly (readonly T[])[]): T[] {
-  const out: T[] = [];
-  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: ModelTier): readonly string[] {
-  const bucket = MODEL_CATALOG[tier];
-  return [
-    ...interleave(bucket.claude, bucket.gpt, bucket.gemini),
-    ...bucket.openSource,
-  ];
-}
+import { MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig } from "./serving.js";
 
-/**
- * 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: ModelTier): string {
-  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: readonly string[] = [
-  ...modelsForTier(ModelTier.Thinking),
-  ...modelsForTier(ModelTier.Balanced),
-  ...modelsForTier(ModelTier.Fast),
-];
+export {
+  classifyEndpoints,
+  FALLBACK_MODEL_IDS,
+  modelForTier,
+  modelsForTier,
+  ModelTier,
+} from "@dbx-tools/model";
 
 /** Optional overrides accepted by {@link buildModel}. */
 export interface BuildModelOverrides {
   /**
    * Static model id from the agent / plugin config (string sugar on
    * `def.model` or `config.defaultModel`). Loses to the per-request
-   * override but wins over env / fallback.
+   * override but wins over env / tier / fallback.
    */
   modelId?: string;
+  /**
+   * Capability tier to resolve when no explicit model id is supplied.
+   * Used by internal agents (e.g. the chart planner asks for
+   * {@link ModelTier.Fast}) to express intent without pinning an
+   * endpoint name; the live catalogue is classified and the top
+   * available model in the tier is chosen, falling back to the
+   * tier's static list when the workspace has none.
+   */
+  tier?: ModelTier;
 }
 
 /**
@@ -262,91 +78,41 @@ export async function buildModel(
   // 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: MastraPluginConfig,
-  requestContext: RequestContext,
-  overrides: BuildModelOverrides,
-  user: User,
-  host: string,
-): Promise<string> {
   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) as string | undefined)
     : 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;
-  }
+  // The override / agent default / env value can be either a concrete
+  // endpoint name or a capability tier slug ("thinking" / "balanced" /
+  // "fast"). A tier slug becomes a tier 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.tier` (e.g. the chart planner) is the floor when nothing
+  // was requested.
+  const requested =
+    override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
+  const requestedTier = requested !== undefined ? parseModelTier(requested) : null;
+  const explicit = requestedTier === null ? requested : undefined;
+  const tier = requestedTier ?? overrides.tier;
 
-  const endpoints = await listServingEndpoints(user.executionContext.client, host, {
+  const { modelId, source } = await selectModel(user.executionContext.client, host, {
+    ...(explicit !== undefined ? { explicit } : {}),
+    fuzzy: serving.fuzzy,
+    threshold: serving.threshold,
+    ...(tier !== undefined ? { tier } : {}),
+    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", {
-    modelId,
-    source: explicit !== undefined ? "fuzzy-match" : "fallback",
-    requestedExplicit: explicit,
-  });
-  return modelId;
-}
+  log.debug("model selected", { modelId, source, requested });
 
-/**
- * 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: readonly string[],
-  endpoints: readonly ServingEndpointSummary[],
-): string {
-  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]!;
+  return {
+    providerId: config.providerId ?? "databricks",
+    modelId,
+    url,
+    headers: Object.fromEntries(headers.entries()),
+  };
 }
 
 /** Path prefix that identifies a Databricks Model Serving REST call. */

package/src/plugin.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,10 +21,11 @@
  *   `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 {
@@ -37,30 +38,35 @@ import {
   type PluginManifest,
   type ResourceRequirement,
 } from "@databricks/appkit";
-import { appkitUtils, logUtils } from "@dbx-tools/shared";
-import { chatRoute } from "@mastra/ai-sdk";
+import { appkitUtils, commonUtils, logUtils } from "@dbx-tools/shared";
 import type { Agent } from "@mastra/core/agent";
 import { Mastra } from "@mastra/core/mastra";
 import express from "express";
+import type { Pool } from "pg";
 
-import type {
-  MastraClientConfig,
-  StatementData,
+import {
+  MASTRA_ROUTES,
+  type MastraClientConfig,
+  type StatementData,
 } from "@dbx-tools/appkit-mastra-shared";
+import {
+  clearServingEndpointsCache,
+  listServingEndpoints,
+  type ServingEndpointSummary,
+} from "@dbx-tools/model";
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.js";
 import { fetchChart } from "./chart.js";
 import type { MastraPluginConfig } from "./config.js";
 import { collectSpaceSuggestions, resolveGenieSpaces } from "./genie.js";
 import { historyRoute } from "./history.js";
-import { createMemoryBuilder, needsLakebase } from "./memory.js";
+import {
+  createMemoryBuilder,
+  createServicePrincipalPool,
+  needsLakebase,
+} from "./memory.js";
 import { buildObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
-import {
-  clearServingEndpointsCache,
-  listServingEndpoints,
-  resolveServingConfig,
-  type ServingEndpointSummary,
-} from "./serving.js";
+import { resolveServingConfig } from "./serving.js";
 import {
   fetchStatementData,
   isStatementNotFoundError,
@@ -125,6 +131,14 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
   private mastra: Mastra | null = null;
   private mastraApp: express.Express | null = null;
   private mastraServer: MastraServer | null = null;
+  /**
+   * Dedicated service-principal Lakebase pool backing Mastra memory /
+   * storage. Built once in {@link buildAgentAndServer} (outside any
+   * `asUser` scope, so it never inherits a request's OBO identity) and
+   * drained in {@link abortActiveOperations}. `null` until setup runs
+   * or when Lakebase isn't needed.
+   */
+  private servicePrincipalPool: Pool | null = null;
 
   override async setup(): Promise<void> {
     // Wait until sibling plugins (e.g. `lakebase`) finish `setup()` so
@@ -150,6 +164,26 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     if (this.config.memory === undefined) this.config.memory = true;
   }
 
+  /**
+   * Drain the memory service-principal pool on shutdown. AppKit calls
+   * this during teardown; the lakebase plugin closes its own SP / OBO
+   * pools the same way. Fire-and-forget so shutdown isn't blocked on a
+   * slow drain, and clear the handle so a re-`setup()` rebuilds it.
+   */
+  override abortActiveOperations(): void {
+    super.abortActiveOperations();
+    if (this.servicePrincipalPool) {
+      this.log.info("closing memory SP pool");
+      const pool = this.servicePrincipalPool;
+      this.servicePrincipalPool = null;
+      pool.end().catch((err) => {
+        this.log.error("error closing memory SP pool", {
+          error: commonUtils.errorMessage(err),
+        });
+      });
+    }
+  }
+
   override exports() {
     return {
       /**
@@ -165,9 +199,9 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
        */
       get: (id: string): Agent | null => 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: (): Agent | null =>
         (this.built && this.built.agents[this.built.defaultAgentId]) ?? null,
@@ -196,22 +230,16 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
 
   override clientConfig(): Record<string, unknown> {
     // 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: MastraClientConfig = {
-      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 ?? {}),
     };
@@ -224,7 +252,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // 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 }))
@@ -278,7 +306,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       },
     };
 
-    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];
@@ -334,8 +362,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
           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();
@@ -451,12 +479,25 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
   }
 
   private async buildAgentAndServer(): Promise<void> {
-    // 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)
+    // Per-agent memory factory. When any storage / memory setting needs
+    // Postgres, stand up a dedicated service-principal pool first so
+    // memory acts as the app SP (owner of the `mastra_*` schemas),
+    // never the per-request OBO identity the chat turn runs under.
+    // `getPgConfig()` is read here, outside any `asUser` scope, so it
+    // returns the SP connection target + token refresh plus any
+    // `lakebase({ pool })` overrides; `require` turns a missing
+    // sibling into a clear wiring error. The builder caches the shared
+    // `PgVector` singleton so registering N agents stays cheap. See
+    // `./memory.js`.
+    if (needsLakebase(this.config)) {
+      const spPgConfig = appkitUtils
+        .require(this.context, lakebase, this.config)
+        .exports()
+        .getPgConfig();
+      this.servicePrincipalPool = await createServicePrincipalPool(spPgConfig);
+    }
+    const memoryBuilder = this.servicePrincipalPool
+      ? createMemoryBuilder(this.config, this.servicePrincipalPool)
       : undefined;
 
     this.log.debug("build:start", {
@@ -507,20 +548,28 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       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` as `${string}: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",
     });