@dbx-tools/appkit-mastra 0.1.41 → 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/model.d.ts

@@ -7,148 +7,41 @@
  * 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 } from "@dbx-tools/model";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
 import { type MastraPluginConfig } from "./config.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 declare 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 declare const MODEL_CATALOG: {
-    readonly thinking: {
-        readonly claude: readonly ["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"];
-        readonly gpt: readonly ["databricks-gpt-5-5-pro"];
-        readonly gemini: readonly ["databricks-gemini-3-1-pro", "databricks-gemini-3-pro", "databricks-gemini-2-5-pro"];
-        readonly openSource: readonly ["databricks-llama-4-maverick", "databricks-gpt-oss-120b", "databricks-meta-llama-3-1-405b-instruct"];
-    };
-    readonly balanced: {
-        readonly claude: readonly ["databricks-claude-sonnet-4-6", "databricks-claude-sonnet-4-5", "databricks-claude-sonnet-4"];
-        readonly gpt: readonly ["databricks-gpt-5-5", "databricks-gpt-5-4", "databricks-gpt-5-2", "databricks-gpt-5-1", "databricks-gpt-5"];
-        readonly gemini: readonly ["databricks-gemini-3-5-flash", "databricks-gemini-3-flash", "databricks-gemini-2-5-flash"];
-        readonly openSource: readonly ["databricks-meta-llama-3-3-70b-instruct", "databricks-qwen3-next-80b-a3b-instruct", "databricks-qwen35-122b-a10b"];
-    };
-    readonly fast: {
-        readonly claude: readonly ["databricks-claude-haiku-4-5"];
-        readonly gpt: readonly ["databricks-gpt-5-4-mini", "databricks-gpt-5-4-nano", "databricks-gpt-5-mini", "databricks-gpt-5-nano"];
-        readonly gemini: readonly ["databricks-gemini-3-1-flash-lite"];
-        readonly openSource: readonly ["databricks-gpt-oss-20b", "databricks-gemma-3-12b", "databricks-meta-llama-3-1-8b-instruct"];
-    };
-};
-/**
- * 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 declare function modelsForTier(tier: ModelTier): readonly string[];
-/**
- * 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 declare function modelForTier(tier: ModelTier): string;
-/**
- * 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 declare const FALLBACK_MODEL_IDS: readonly string[];
+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;
 }
 /**
  * Resolve a `MastraModelConfig` for the current agent step. Runs