@dbx-tools/appkit-mastra 0.1.40 → 0.1.42

package/README.md

@@ -2,8 +2,8 @@
 
 An AppKit plugin that hosts [Mastra](https://mastra.ai) agents inside a
 Databricks App with user-scoped workspace auth (OBO), optional
-Lakebase-backed memory, and an AI SDK chat route the React client can
-consume with `useChat()`.
+Lakebase-backed memory, and the standard Mastra agent stream the React
+client drives via `@mastra/client-js` (`getAgent(id).stream()`).
 
 The plugin is designed so that wiring it up looks the same as the
 AppKit
@@ -70,29 +70,25 @@ for routing / one-shot agents that don't need history.
 See [Memory + storage](#memory--storage) for the full cascade and worked
 examples.
 
-On the React side, never hardcode `/api/mastra/...`. Pull the published
-paths from `usePluginClientConfig` and use the `chatUrl` helper. Import
-them from the dependency-free `@dbx-tools/appkit-mastra-shared` package
-so your browser bundle doesn't pull in `pg`, `fastembed`, or Mastra:
+On the React side, drop in the prebuilt chat UI from
+[`@dbx-tools/appkit-mastra-ui`](../appkit-mastra-ui) - it wires itself
+from the plugin's published client config and streams over
+`@mastra/client-js`, so there's no transport code to write:
 
 ```tsx
-import { usePluginClientConfig } from "@databricks/appkit-ui/react";
-import { chatUrl, type MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
-import { useChat } from "@ai-sdk/react";
-import { DefaultChatTransport } from "ai";
-import { useMemo } from "react";
-
-function Chat() {
-  const config = usePluginClientConfig<MastraClientConfig>("mastra");
-  const transport = useMemo(
-    () => new DefaultChatTransport({ api: chatUrl(config) }),
-    [config],
-  );
-  const { messages, sendMessage } = useChat({ transport });
-  // ...
+import { MastraChat } from "@dbx-tools/appkit-mastra-ui/react";
+
+export default function ChatPage() {
+  return <MastraChat showModelPicker />;
 }
 ```
 
+Under the hood that's `useMastraClient()` -> a `MastraPluginClient`
+(a `@mastra/client-js` `MastraClient` subclass) that streams turns and
+adds the plugin's custom routes (history, models, suggestions, embeds).
+Never hardcode `/api/mastra/...`; the client derives every URL from the
+`basePath` published in `clientConfig()`.
+
 See [Client wiring](#client-wiring) for the full `MastraClientConfig`
 shape and per-agent selection.
 
@@ -136,9 +132,9 @@ Plugin-level fields:
 | Field                   | Description                                                                                                                                                                                                                                                                                                                                                                                  |
 | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agents`                | The registry. Omit for a built-in `default` analyst.                                                                                                                                                                                                                                                                                                                                         |
-| `defaultAgent`          | Id that `chatRoute` binds to when no `:agentId` is supplied. Defaults to first registered.                                                                                                                                                                                                                                                                                                   |
+| `defaultAgent`          | Id the client talks to when no `:agentId` is supplied. Defaults to first registered.                                                                                                                                                                                                                                                                                                         |
 | `defaultModel`          | Fallback for any agent that omits `model`. Same shape (string sugar or `DynamicArgument`).                                                                                                                                                                                                                                                                                                   |
-| `defaultModelFallbacks` | Priority-ordered list walked when no `model` / env / override is set. First entry whose endpoint exists in the workspace wins. Default chains the three `ModelTier`s (Thinking → Balanced → Fast); within each tier providers are interleaved Claude ↔ GPT ↔ Gemini with open-weights appended. Compose your own with `modelsForTier(ModelTier.Fast)` or read straight from `MODEL_CATALOG`. |
+| `defaultModelFallbacks` | Priority-ordered list tried first when no `model` / env / override is set, ahead of the dynamic score-classified catalogue. First entry whose endpoint exists in the workspace wins. When unset, resolution is driven by the live Foundation Model API scores (see [Model resolution](#model-resolution)); set this to pin a regulated workspace to an approved subset. Compose one with `modelsForTier(ModelTier.Fast)`. |
 | `tools`                 | Ambient tools merged into every agent (per-agent tools win on collisions).                                                                                                                                                                                                                                                                                                                   |
 | `storage`               | `undefined` (default) auto-enables when `lakebase()` is registered; `true` does the same explicitly; `false` opts out; an object opens a dedicated `PostgresStore`. Per-agent default is `schemaName: "mastra_<agentId>"`.                                                                                                                                                                   |
 | `memory`                | `undefined` (default) auto-enables when `lakebase()` is registered; `true` does the same explicitly; `false` opts out; an object opens a dedicated `PgVector`. Default behavior: one shared `PgVector` singleton across every agent.                                                                                                                                                         |
@@ -254,7 +250,7 @@ Genie writer event flow:
 - Charts ride out-of-band: `prepare_chart` mints a `chartId`
   synchronously, the planner runs in the background and writes
   the spec to the chart cache (1h TTL). The host UI long-polls
-  `${MastraClientConfig.embedPathTemplate}` (`/embed/chart/:id`)
+  `${basePath}/embed/chart/:id` (via `MastraPluginClient.chart(id)`)
   by id and renders inline at the matching `[chart:<chartId>]`
   marker.
 - After a hard reload, the live `started` / `status` / `sql`
@@ -426,43 +422,48 @@ loose tokens like `"claude sonnet"` snap to
 `modelFuzzyThreshold` (default `0.4`) the input is returned verbatim
 and Databricks surfaces the canonical 404.
 
-### No explicit ask (tier-aware fallback list)
-
-When nothing is set, the resolver walks an opinionated
-priority-ordered list and returns **the first id that is actually
-present in the workspace's endpoint listing**. This is how a workspace
-without Claude Opus still gets a sensible default automatically -
-the resolver skips ahead to whichever Sonnet / GPT-5 / Gemini / Llama
-variant is wired up.
-
-The catalogue is grouped two ways:
-
-- By **capability tier** via the `ModelTier` enum:
-`ModelTier.Thinking` (deepest reasoning), `ModelTier.Balanced`
-(cost/latency sweet spot), `ModelTier.Fast` (cheap & quick for
-classification / routing / simple summarisation).
-- By **provider** within each tier: `claude`, `gpt`, `gemini`,
-`openSource`.
-
-Both views live on `MODEL_CATALOG[tier][provider]`. The walked
-`FALLBACK_MODEL_IDS` chains the three tiers in descending power
-(Thinking → Balanced → Fast); within each tier providers are
-round-robin-zipped (Claude ↔ GPT ↔ Gemini) before the open-weights
-tail is appended as the universal floor.
-
-
-| Tier (most powerful first) | Claude                           | GPT                                   | Gemini                          | Open weights                                   |
-| -------------------------- | -------------------------------- | ------------------------------------- | ------------------------------- | ---------------------------------------------- |
-| `ModelTier.Thinking`       | Opus 4.8 → 4.7 → 4.6 → 4.5 → 4.1 | 5.5 Pro                               | 3.1 Pro → 3 Pro → 2.5 Pro       | Llama 4 Maverick, GPT-OSS 120B, Llama 3.1 405B |
-| `ModelTier.Balanced`       | Sonnet 4.6 → 4.5 → 4             | 5.5 → 5.4 → 5.2 → 5.1 → 5             | 3.5 Flash → 3 Flash → 2.5 Flash | Llama 3.3 70B, Qwen3-Next 80B, Qwen35 122B     |
-| `ModelTier.Fast`           | Haiku 4.5                        | 5.4 mini → 5.4 nano → 5 mini → 5 nano | 3.1 Flash Lite                  | GPT-OSS 20B, Gemma 3 12B, Llama 3.1 8B         |
-
+### No explicit ask (dynamic, score-based tiers)
+
+When nothing is set, the resolver classifies the **live** workspace
+catalogue and returns **the first id that is actually present in the
+endpoint listing**. This is how a workspace without Claude Opus still
+gets a sensible default automatically - the resolver skips ahead to
+whichever model is the best fit and actually wired up.
+
+Tiers are derived, not hard-coded. Databricks publishes a
+`quality` / `speed` / `cost` profile per Foundation Model API endpoint
+(the bars in the AI Playground), surfaced on `ServingEndpointSummary.profile`.
+`classifyEndpoints(endpoints)` buckets the scored chat models by the
+**relative distribution** of `quality`: the observed scores are split
+at their 1/3 and 2/3 quantiles, so the top third is
+`ModelTier.Thinking`, the bottom third `ModelTier.Fast`, and the
+middle `ModelTier.Balanced`. Because the thresholds come from the data,
+the split adapts as Databricks adds or rescores models - nothing is
+pinned to a fixed score band, and a brand-new model that lands outside
+today's range still slots in next to its peers.
+
+Two escape hatches cover missing scores:
+
+- **Unscored but recognizable** endpoints (a model Databricks hasn't
+  scored yet, e.g. a fresh release) are placed by a small **family
+  heuristic** keyed on provider + variant words (`opus`/`sonnet`/`haiku`,
+  `pro`/`mini`/`nano`, `flash`/`flash-lite`, Llama parameter sizes).
+  Unrecognized, unscored endpoints are never auto-selected.
+- **Catalogue unreachable**: the resolver falls back to the small,
+  family-classified `FALLBACK_MODEL_IDS` floor (Thinking → Balanced →
+  Fast).
+
+The default chain is therefore: any `defaultModelFallbacks` you set,
+then the live score-classified catalogue in descending tier order,
+then the `FALLBACK_MODEL_IDS` floor.
 
 #### Pick a tier-appropriate model for one agent
 
-Use `modelForTier(tier)` to grab the top of a tier as a string; the
-agent-step resolver fuzzy-matches it against the live catalogue at
-call time so it still works when the literal top pick isn't deployed.
+`modelForTier(tier)` / `modelsForTier(tier)` return the **static
+fallback opinion** for a tier (the small built-in list, no workspace
+call). They're handy for seeding a default; the agent-step resolver
+still fuzzy-matches the result against the live catalogue at call time
+so it works even when the literal pick isn't deployed.
 
 ```ts
 import { createAgent, ModelTier, modelForTier } from "@dbx-tools/appkit-mastra";
@@ -480,7 +481,7 @@ const planner = createAgent({
 
 #### Bias the plugin-level fallback toward a tier
 
-`modelsForTier(tier)` returns the priority-ordered list for one tier;
+`modelsForTier(tier)` returns the static fallback list for one tier;
 pass it to `defaultModelFallbacks` to scope the auto-resolver:
 
 ```ts

package/dist/index.d.ts

@@ -11,11 +11,11 @@
  * consumers.
  */
 export * from "@dbx-tools/appkit-mastra-shared";
+export * from "@dbx-tools/model";
 export * from "./src/agents.js";
 export * from "./src/chart.js";
 export * from "./src/config.js";
 export * from "./src/genie.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, ModelTier, modelForTier, modelsForTier, } from "./src/model.js";
 export * from "./src/plugin.js";
-export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, clearServingEndpointsCache, extractModelOverride, listServingEndpoints, resolveModelId, type ResolveModelOptions, type ResolvedModel, type ServingEndpointSummary, } from "./src/serving.js";
+export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, extractModelOverride, type ModelOverrideRequest, } from "./src/serving.js";
 export * from "./src/tools/email.js";

package/dist/index.js

@@ -11,11 +11,11 @@
  * consumers.
  */
 export * from "@dbx-tools/appkit-mastra-shared";
+export * from "@dbx-tools/model";
 export * from "./src/agents.js";
 export * from "./src/chart.js";
 export * from "./src/config.js";
 export * from "./src/genie.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, ModelTier, modelForTier, modelsForTier, } from "./src/model.js";
 export * from "./src/plugin.js";
-export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, clearServingEndpointsCache, extractModelOverride, listServingEndpoints, resolveModelId, } from "./src/serving.js";
+export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, extractModelOverride, } from "./src/serving.js";
 export * from "./src/tools/email.js";

package/dist/src/agents.d.ts

@@ -10,7 +10,7 @@
  *
  * When no agents are registered the plugin falls back to a single
  * built-in analyst so the bare `mastra()` call still mounts a working
- * `chatRoute` agent for demos.
+ * streamable agent for demos.
  */
 import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
@@ -185,8 +185,8 @@ export type MastraToolsFn = (plugins: MastraPlugins) => MastraTools | Promise<Ma
 /**
  * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
  * plugin uses for `AgentDefinition`. The registry key under
- * `config.agents` is what `chatRoute` matches on; `name` is purely
- * informational (defaults to the key).
+ * `config.agents` is the `agentId` the client streams against; `name`
+ * is purely informational (defaults to the key).
  */
 export interface MastraAgentDefinition {
     /** Display name used as `Agent.name`. Defaults to the registry key. */

package/dist/src/agents.js

@@ -10,7 +10,7 @@
  *
  * When no agents are registered the plugin falls back to a single
  * built-in analyst so the bare `mastra()` call still mounts a working
- * `chatRoute` agent for demos.
+ * streamable agent for demos.
  */
 import { appkitUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";

package/dist/src/chart.d.ts

@@ -144,4 +144,10 @@ export declare function fetchChart(chartId: string, options?: FetchChartOptions)
  * `prepare_chart` tool, which accepts a `statement_id` and
  * resolves the rows lazily.
  */
-export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "render_data", unknown>;
+export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<{
+    title: string;
+    data: readonly Record<string, unknown>[];
+    description?: string | undefined;
+}, {
+    chartId: string;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;

package/dist/src/chart.js

@@ -30,7 +30,7 @@ import { commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
-import { buildModel, modelForTier, ModelTier } from "./model.js";
+import { buildModel, ModelTier } from "./model.js";
 const log = logUtils.logger("mastra/chart");
 /* ------------------------------ constants ------------------------------ */
 /**
@@ -276,9 +276,7 @@ function getPlannerAgent(config) {
             name: "Chart Planner",
             description: "Picks chart type and axis encodings for a dataset.",
             instructions: CHART_PLANNER_INSTRUCTIONS,
-            model: ({ requestContext }) => buildModel(config, requestContext, {
-                modelId: modelForTier(ModelTier.Fast),
-            }),
+            model: ({ requestContext }) => buildModel(config, requestContext, { tier: ModelTier.Fast }),
         });
         plannerAgents.set(config, agent);
     }
@@ -302,7 +300,7 @@ async function runChartPlanner(config, request, options = {}) {
         ...(requestContext ? { requestContext } : {}),
         ...(abortSignal ? { abortSignal } : {}),
     });
-    const plan = result.object;
+    const plan = chartPlanSchema.parse(result.object);
     const option = planToEchartsOption(plan, title);
     return { chartType: plan.chartType, option };
 }

package/dist/src/config.d.ts

@@ -125,7 +125,8 @@ export interface MastraPluginConfig extends BasePluginConfig {
      */
     tools?: MastraTools;
     /**
-     * Agent id used by `chatRoute` when the client doesn't specify one.
+     * Agent id used when the client doesn't specify one (the bare,
+     * un-suffixed history / suggestions routes resolve to it).
      * Defaults to the first key in `agents` (or `"default"` when
      * `agents` is omitted). Must match an id in `agents` when both are
      * set; a mismatch throws at setup with the available candidates.
@@ -173,17 +174,19 @@ export interface MastraPluginConfig extends BasePluginConfig {
      */
     modelOverride?: boolean;
     /**
-     * Priority-ordered list of endpoint names tried when no agent /
-     * plugin / env / request-override model id is set. The resolver
-     * picks the first id that is actually present in the workspace's
-     * `/serving-endpoints` listing - this is what lets a workspace
-     * without Claude Opus still get a sensible default automatically.
+     * Priority-ordered list of endpoint names tried *first* when no
+     * agent / plugin / env / request-override model id is set, ahead of
+     * the dynamic score-classified catalogue. The resolver picks the
+     * first id that is actually present in the workspace's
+     * `/serving-endpoints` listing.
      *
-     * Defaults to the built-in list in `model.ts` (`FALLBACK_MODEL_IDS`):
-     * Claude (Opus -> Sonnet -> Haiku), then OpenAI GPT-5 family, then
-     * open weights (Llama 4, Llama 3.3, GPT-OSS, Qwen, Llama 3.1).
-     * Override here to pin a regulated workspace to an approved subset
-     * or to add custom endpoints in front of the public catalogue.
+     * When unset, resolution is driven by the live Foundation Model API
+     * `quality` / `speed` / `cost` scores: endpoints are classified into
+     * tiers (`classifyEndpoints`) and walked best-first (Thinking ->
+     * Balanced -> Fast), with the small built-in `FALLBACK_MODEL_IDS`
+     * list as the floor when the catalogue can't be read. Set this to
+     * pin a regulated workspace to an approved subset, or to put custom
+     * endpoints in front of the auto-classified catalogue.
      */
     defaultModelFallbacks?: readonly string[];
     /**

package/dist/src/genie.d.ts

@@ -142,18 +142,6 @@ export declare function buildGenieToolkitProvider(opts: {
 }): {
     toolkit(opts?: unknown): MastraTools;
 };
-/**
- * Returns `true` when at least one Genie space is reachable
- * through {@link resolveGenieSpaces} - either via
- * {@link MastraPluginConfig.genieSpaces}, the AppKit `genie()`
- * plugin instance, or the `DATABRICKS_GENIE_SPACE_ID` env var.
- *
- * Cheap to call from `resolveProvider` to short-circuit `genie`
- * lookups when nothing is wired, so the `plugins.genie` lookup
- * still resolves to `undefined` (matching AppKit's
- * absent-plugin semantics) when neither source is configured.
- */
-export declare function hasAnyGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): boolean;
 /**
  * Collect the curated starter questions across every resolved Genie
  * space, deduped and capped. Each space's `sample_questions` are

package/dist/src/genie.js

@@ -37,7 +37,7 @@ import { CacheManager, genie } from "@databricks/appkit";
 import { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
 import { ChartSchema, } from "@dbx-tools/appkit-mastra-shared";
 import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
-import {} from "@dbx-tools/genie-shared";
+import { GenieMessageSchema } from "@dbx-tools/genie-shared";
 import { appkitUtils, commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import { createTool } from "@mastra/core/tools";
@@ -334,7 +334,7 @@ function buildAskGenieTool(opts) {
             question: z.string().min(1, "question is required"),
         }),
         outputSchema: z.object({
-            message: z.custom(),
+            message: GenieMessageSchema,
         }),
         execute: async ({ question }, ctxRaw) => {
             const ctx = ctxRaw;
@@ -891,20 +891,6 @@ export function buildGenieToolkitProvider(opts) {
         },
     };
 }
-/**
- * Returns `true` when at least one Genie space is reachable
- * through {@link resolveGenieSpaces} - either via
- * {@link MastraPluginConfig.genieSpaces}, the AppKit `genie()`
- * plugin instance, or the `DATABRICKS_GENIE_SPACE_ID` env var.
- *
- * Cheap to call from `resolveProvider` to short-circuit `genie`
- * lookups when nothing is wired, so the `plugins.genie` lookup
- * still resolves to `undefined` (matching AppKit's
- * absent-plugin semantics) when neither source is configured.
- */
-export function hasAnyGenieSpaces(config, context) {
-    return Object.keys(resolveGenieSpaces(config, context)).length > 0;
-}
 /* --------------------------- starter suggestions --------------------------- */
 /**
  * Default cap on starter suggestions surfaced to the chat empty

package/dist/src/history.d.ts

@@ -9,8 +9,8 @@
  *
  * The route is registered through {@link historyRoute} as a Mastra
  * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * `chatRoute`. That means the `MastraServer` auth middleware (in
- * `./server.ts`) has already populated `RequestContext` with
+ * the standard agent routes. That means the `MastraServer` auth
+ * middleware (in `./server.ts`) has already populated `RequestContext` with
  * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
@@ -83,10 +83,10 @@ export type HistoryRouteOptions = {
  *     anchors the thread id is left alone so the user keeps the
  *     same thread - only the contents go away.
  *
- * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
- * fixed-agent mount, or include `:agentId` in the path for dynamic
- * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
- * layout (`/route/chat` + `/route/chat/:agentId`).
+ * Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
+ * binding: pass `agent` for a fixed-agent mount, or include
+ * `:agentId` in the path for dynamic routing. The plugin registers
+ * both `/route/history` (default agent) and `/route/history/:agentId`.
  *
  * The handler reads `threadId` and `resourceId` from `RequestContext`
  * (populated upstream by `MastraServer.registerAuthMiddleware`), so

package/dist/src/history.js

@@ -9,8 +9,8 @@
  *
  * The route is registered through {@link historyRoute} as a Mastra
  * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * `chatRoute`. That means the `MastraServer` auth middleware (in
- * `./server.ts`) has already populated `RequestContext` with
+ * the standard agent routes. That means the `MastraServer` auth
+ * middleware (in `./server.ts`) has already populated `RequestContext` with
  * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
@@ -153,10 +153,10 @@ export async function clearHistory(opts) {
  *     anchors the thread id is left alone so the user keeps the
  *     same thread - only the contents go away.
  *
- * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
- * fixed-agent mount, or include `:agentId` in the path for dynamic
- * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
- * layout (`/route/chat` + `/route/chat/:agentId`).
+ * Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
+ * binding: pass `agent` for a fixed-agent mount, or include
+ * `:agentId` in the path for dynamic routing. The plugin registers
+ * both `/route/history` (default agent) and `/route/history/:agentId`.
  *
  * The handler reads `threadId` and `resourceId` from `RequestContext`
  * (populated upstream by `MastraServer.registerAuthMiddleware`), so

package/dist/src/memory.d.ts

@@ -26,45 +26,55 @@
  * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
  * is registered); per-agent settings cascade on top of that.
  */
-import { lakebase } from "@databricks/appkit";
-import { appkitUtils } from "@dbx-tools/shared";
 import { Memory } from "@mastra/memory";
 import { PostgresStore } from "@mastra/pg";
+import { Pool, type PoolConfig } from "pg";
 import type { MastraAgentDefinition } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
-/** Pool handle returned by the AppKit `lakebase` plugin `exports().pool`. */
-export type LakebasePool = ReturnType<InstanceType<ReturnType<typeof lakebase>["plugin"]>["exports"]>["pool"];
 /**
- * True when any plugin-level or per-agent setting could need the
- * Lakebase pool. Used by `plugin.ts` to gate pool acquisition; the
- * builder also acquires lazily so missed cases still fail with a
- * clear lakebase-not-registered error.
+ * Build a dedicated **service-principal** Lakebase pool for Mastra
+ * memory from the lakebase plugin's resolved SP pg config.
+ *
+ * The plugin's `exports().pool` is a `RoutingPool` that switches to
+ * the per-user (OBO) pool whenever a query runs inside an `asUser`
+ * scope - exactly the context the mastra plugin establishes around
+ * every chat turn. Memory (threads / messages + semantic recall) must
+ * instead always act as the app service principal: it owns the
+ * auto-created `mastra_*` schemas (a per-user role usually can't
+ * `CREATE SCHEMA`) and is shared across users, so it cannot inherit a
+ * request's OBO identity.
+ *
+ * `pgConfig` must be the plugin's `exports().getPgConfig()` evaluated
+ * **outside** any `asUser` scope (i.e. during setup), so it carries
+ * the SP connection target, OAuth token-refresh `password` callback,
+ * and any `lakebase({ pool })` tuning overrides - all of which this
+ * pool inherits. See the call site in `plugin.ts`.
  */
-export declare function needsLakebase(config: MastraPluginConfig): boolean;
+export declare function createServicePrincipalPool(pgConfig: PoolConfig): Promise<Pool>;
 /**
- * Look up the `lakebase` plugin and return its managed `pg.Pool`.
- * Throws when the sibling plugin is not registered; enabling
- * `storage` / `memory` without lakebase is a wiring bug, not a runtime
- * condition we can recover from.
+ * True when any plugin-level or per-agent setting could need the
+ * Lakebase pool. Used by `plugin.ts` to gate creation of the
+ * service-principal pool and the {@link MemoryBuilder} that consumes
+ * it; when false neither is built.
  */
-export declare function resolveLakebasePool(context: appkitUtils.PluginContextLike | undefined, caller: MastraPluginConfig): LakebasePool;
+export declare function needsLakebase(config: MastraPluginConfig): boolean;
 /**
- * Construct a per-agent {@link Memory} factory. Caches the shared
- * `PgVector` singleton (built on first need) and the lazily-resolved
- * Lakebase pool so each agent build is O(1) after the first.
+ * Construct a per-agent {@link Memory} factory bound to the supplied
+ * service-principal pool (see {@link createServicePrincipalPool}).
+ * Caches the shared `PgVector` singleton (built on first need) so each
+ * agent build is O(1) after the first.
  */
-export declare function createMemoryBuilder(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): MemoryBuilder;
+export declare function createMemoryBuilder(config: MastraPluginConfig, servicePrincipalPool: Pool): MemoryBuilder;
 /**
- * Builds one `Memory` per agent. Per-instance state keeps the shared
- * `PgVector` and the resolved Lakebase pool alive across calls so
- * registering N agents stays cheap.
+ * Builds one `Memory` per agent against a shared service-principal
+ * Lakebase pool. Per-instance state keeps the shared `PgVector` alive
+ * across calls so registering N agents stays cheap.
  */
 export declare class MemoryBuilder {
     private readonly config;
-    private readonly context;
+    private readonly servicePrincipalPool;
     private sharedVector;
-    private pool;
-    constructor(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined);
+    constructor(config: MastraPluginConfig, servicePrincipalPool: Pool);
     /**
      * Build a `Memory` for `agentId` after the plugin/agent cascade.
      * Returns `undefined` when the agent has neither storage nor a
@@ -96,5 +106,4 @@ export declare class MemoryBuilder {
      */
     private buildVector;
     private getSharedVector;
-    private requirePool;
 }