@dbx-tools/appkit-mastra 0.1.41 → 0.1.42

package/index.ts

@@ -11,29 +11,18 @@
  * 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,
+  type ModelOverrideRequest,
 } from "./src/serving.js";
 export * from "./src/tools/email.js";

package/package.json

@@ -9,13 +9,14 @@
     }
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@dbx-tools/appkit-mastra-shared": "0.1.41",
-    "@dbx-tools/genie": "0.1.41",
-    "@dbx-tools/genie-shared": "0.1.41",
-    "@dbx-tools/shared": "0.1.41",
+    "@dbx-tools/appkit-mastra-shared": "0.1.42",
+    "@dbx-tools/genie": "0.1.42",
+    "@dbx-tools/genie-shared": "0.1.42",
+    "@dbx-tools/model": "0.1.42",
+    "@dbx-tools/shared": "0.1.42",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",
@@ -24,7 +25,6 @@
     "@mastra/observability": "^1",
     "@mastra/otel-bridge": "^1",
     "@mastra/pg": "^1",
-    "fuse.js": "^7.0.0",
     "pg": "^8.20.0",
     "zod": "^4.3.6"
   },

package/src/agents.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, stringUtils } from "@dbx-tools/shared";
@@ -226,8 +226,8 @@ export type MastraToolsFn = (
 /**
  * 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/src/chart.ts

@@ -39,7 +39,7 @@ import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
 import type { MastraPluginConfig } from "./config.js";
-import { buildModel, modelForTier, ModelTier } from "./model.js";
+import { buildModel, ModelTier } from "./model.js";
 
 const log = logUtils.logger("mastra/chart");
 
@@ -330,9 +330,7 @@ function getPlannerAgent(config: MastraPluginConfig): Agent {
       description: "Picks chart type and axis encodings for a dataset.",
       instructions: CHART_PLANNER_INSTRUCTIONS,
       model: ({ requestContext }) =>
-        buildModel(config, requestContext, {
-          modelId: modelForTier(ModelTier.Fast),
-        }),
+        buildModel(config, requestContext, { tier: ModelTier.Fast }),
     });
     plannerAgents.set(config, agent);
   }
@@ -361,7 +359,7 @@ async function runChartPlanner(
     ...(requestContext ? { requestContext } : {}),
     ...(abortSignal ? { abortSignal } : {}),
   });
-  const plan = result.object as ChartPlan;
+  const plan = chartPlanSchema.parse(result.object);
   const option = planToEchartsOption(plan, title);
   return { chartType: plan.chartType, option };
 }

package/src/config.ts

@@ -150,7 +150,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.
@@ -198,17 +199,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/src/genie.ts

@@ -38,11 +38,11 @@ import { CacheManager, genie } from "@databricks/appkit";
 import { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
 import {
   ChartSchema,
-  type MinimalWriter,
+  type MastraWriter,
   type StartedEvent,
 } from "@dbx-tools/appkit-mastra-shared";
 import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
-import { type GenieMessage } from "@dbx-tools/genie-shared";
+import { GenieMessageSchema, type GenieMessage } from "@dbx-tools/genie-shared";
 import { appkitUtils, commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import type { RequestContext } from "@mastra/core/request-context";
 import { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
@@ -93,7 +93,7 @@ export type GenieSpacesConfig = Record<string, GenieSpaceConfig | string>;
 type ToolExecuteCtx =
   | {
       requestContext?: RequestContext;
-      writer?: MinimalWriter;
+      writer?: MastraWriter;
       abortSignal?: AbortSignal;
     }
   | undefined;
@@ -421,7 +421,7 @@ function buildAskGenieTool(opts: { spaceId: string; alias: string; hint?: string
       question: z.string().min(1, "question is required"),
     }),
     outputSchema: z.object({
-      message: z.custom<GenieMessage>(),
+      message: GenieMessageSchema,
     }),
     execute: async ({ question }, ctxRaw) => {
       const ctx = ctxRaw as ToolExecuteCtx;
@@ -1033,24 +1033,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: MastraPluginConfig,
-  context: appkitUtils.PluginContextLike | undefined,
-): boolean {
-  return Object.keys(resolveGenieSpaces(config, context)).length > 0;
-}
-
 /* --------------------------- starter suggestions --------------------------- */
 
 /**

package/src/history.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`.
@@ -197,10 +197,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/src/model.ts

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