@dbx-tools/appkit-mastra 0.1.40 → 0.1.42

package/dist/src/memory.js

@@ -26,18 +26,46 @@
  * (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, logUtils } from "@dbx-tools/shared";
+import { getUsernameWithApiLookup } from "@databricks/appkit";
+import { logUtils } from "@dbx-tools/shared";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
 import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
 const log = logUtils.logger("mastra/memory");
+/**
+ * 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 async function createServicePrincipalPool(pgConfig) {
+    // `getPgConfig()` resolves the SP username synchronously from
+    // `PGUSER` / `DATABRICKS_CLIENT_ID`; fall back to the async API
+    // lookup (e.g. local dev authenticating via PAT) so the pool always
+    // has an identity to connect with.
+    const user = pgConfig.user ?? (await getUsernameWithApiLookup());
+    return new Pool({ ...pgConfig, user });
+}
 /**
  * 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.
+ * 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 function needsLakebase(config) {
     if (settingNeedsSharedPool(config.storage))
@@ -48,35 +76,26 @@ export function needsLakebase(config) {
     return defs.some((d) => settingNeedsSharedPool(d.storage) || settingNeedsSharedPool(d.memory));
 }
 /**
- * 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.
+ * 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 function resolveLakebasePool(context, caller) {
-    return appkitUtils.require(context, lakebase, caller).exports().pool;
+export function createMemoryBuilder(config, servicePrincipalPool) {
+    return new MemoryBuilder(config, servicePrincipalPool);
 }
 /**
- * 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.
- */
-export function createMemoryBuilder(config, context) {
-    return new MemoryBuilder(config, context);
-}
-/**
- * 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 class MemoryBuilder {
     config;
-    context;
+    servicePrincipalPool;
     sharedVector;
-    pool;
-    constructor(config, context) {
+    constructor(config, servicePrincipalPool) {
         this.config = config;
-        this.context = context;
+        this.servicePrincipalPool = servicePrincipalPool;
     }
     /**
      * Build a `Memory` for `agentId` after the plugin/agent cascade.
@@ -105,7 +124,7 @@ export class MemoryBuilder {
         return new PostgresStore({
             id: "mastra-store__instance",
             schemaName: "mastra_instance",
-            pool: this.requirePool(),
+            pool: this.servicePrincipalPool,
         });
     }
     forAgent(agentId, def) {
@@ -143,7 +162,7 @@ export class MemoryBuilder {
             return new PostgresStore({
                 id: `mastra-store__${agentId}`,
                 schemaName: `mastra_${agentId}`,
-                pool: this.requirePool(),
+                pool: this.servicePrincipalPool,
             });
         }
         // Cast: `withId` guarantees `id` is set, but the distributive
@@ -169,16 +188,10 @@ export class MemoryBuilder {
     }
     getSharedVector() {
         if (!this.sharedVector) {
-            this.sharedVector = buildSharedPgVector(this.requirePool());
+            this.sharedVector = buildSharedPgVector(this.servicePrincipalPool);
         }
         return this.sharedVector;
     }
-    requirePool() {
-        if (!this.pool) {
-            this.pool = resolveLakebasePool(this.context, this.config);
-        }
-        return this.pool;
-    }
 }
 /**
  * Build the shared `PgVector` that backs the default

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

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 / 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 { parseModelTier, 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, modelForTier, modelsForTier, ModelTier, } 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 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 { 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", {
+    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/";