@dbx-tools/model 0.1.42

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@dbx-tools/model` public surface.
+ *
+ * Bundles the package's Node-side Model Serving access (cached
+ * `/serving-endpoints` listing plus fuzzy name resolution), the
+ * workspace-aware {@link resolveModel} selector, and the server-only
+ * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForTier`)
+ * with a re-export of the pure `@dbx-tools/model-shared` surface
+ * (capability tiers, the score profile, the endpoint descriptor, and
+ * the tier classifier) so a single `from "@dbx-tools/model"` import
+ * serves server-side consumers.
+ *
+ * Browser-side consumers should import `@dbx-tools/model-shared`
+ * directly: the serving driver pulls in `WorkspaceClient` and AppKit's
+ * `CacheManager` and is Node-only, whereas the re-exported surface is
+ * pure (types + sync functions) and safe for any runtime.
+ */
+export * from "@dbx-tools/model-shared";
+export * from "./src/fallback.js";
+export * from "./src/resolve.js";
+export * from "./src/serving.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@dbx-tools/model` public surface.
+ *
+ * Bundles the package's Node-side Model Serving access (cached
+ * `/serving-endpoints` listing plus fuzzy name resolution), the
+ * workspace-aware {@link resolveModel} selector, and the server-only
+ * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForTier`)
+ * with a re-export of the pure `@dbx-tools/model-shared` surface
+ * (capability tiers, the score profile, the endpoint descriptor, and
+ * the tier classifier) so a single `from "@dbx-tools/model"` import
+ * serves server-side consumers.
+ *
+ * Browser-side consumers should import `@dbx-tools/model-shared`
+ * directly: the serving driver pulls in `WorkspaceClient` and AppKit's
+ * `CacheManager` and is Node-only, whereas the re-exported surface is
+ * pure (types + sync functions) and safe for any runtime.
+ */
+export * from "@dbx-tools/model-shared";
+export * from "./src/fallback.js";
+export * from "./src/resolve.js";
+export * from "./src/serving.js";

package/dist/src/fallback.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server-side offline fallback opinion for model selection.
+ *
+ * When the live `/serving-endpoints` catalogue can't be read at all -
+ * no user token, the service principal can't list, or the workspace is
+ * unreachable - the resolver still has to name *some* endpoint. This
+ * module holds that floor: a small, hard-coded set of well-known
+ * Foundation Model API endpoint names, each bucketed into a
+ * {@link ModelTier} by the shared {@link classifyByFamily} heuristic
+ * (no tiers are hard-coded here) and ordered best-first.
+ *
+ * This is deliberately *server-only*. A browser client never talks to
+ * Databricks directly - it always goes through this server - so it has
+ * nothing to fall back to and must not assume a stale, baked-in model
+ * list; it consumes the live `/models` response instead. The pure
+ * classifier ({@link classifyEndpoints}) is what the client shares.
+ */
+import { ModelTier } from "@dbx-tools/model-shared";
+/**
+ * Static fallback model ids for a tier, drawn from the small built-in
+ * {@link FALLBACK_MODEL_NAMES} list and ordered best-first by family
+ * rank. Sync and workspace-independent: this is the *fallback opinion*
+ * used to seed default lists or when the live catalogue is unreachable
+ * - live resolution prefers `classifyEndpoints`.
+ */
+export declare function modelsForTier(tier: ModelTier): readonly string[];
+/** Top static fallback model id for a tier. */
+export declare function modelForTier(tier: ModelTier): string;
+/**
+ * Priority-ordered fallback chain (Thinking -> Balanced -> Fast) over
+ * the small built-in list. The floor walked at resolve time when no
+ * agent / plugin / env / request model is set *and* the live
+ * catalogue yields nothing.
+ */
+export declare const FALLBACK_MODEL_IDS: readonly string[];

package/dist/src/fallback.js

@@ -0,0 +1,65 @@
+/**
+ * Server-side offline fallback opinion for model selection.
+ *
+ * When the live `/serving-endpoints` catalogue can't be read at all -
+ * no user token, the service principal can't list, or the workspace is
+ * unreachable - the resolver still has to name *some* endpoint. This
+ * module holds that floor: a small, hard-coded set of well-known
+ * Foundation Model API endpoint names, each bucketed into a
+ * {@link ModelTier} by the shared {@link classifyByFamily} heuristic
+ * (no tiers are hard-coded here) and ordered best-first.
+ *
+ * This is deliberately *server-only*. A browser client never talks to
+ * Databricks directly - it always goes through this server - so it has
+ * nothing to fall back to and must not assume a stale, baked-in model
+ * list; it consumes the live `/models` response instead. The pure
+ * classifier ({@link classifyEndpoints}) is what the client shares.
+ */
+import { classifyByFamily, ModelTier } from "@dbx-tools/model-shared";
+/**
+ * Small, last-resort set of well-known Foundation Model API endpoint
+ * names, ordered best-first within each tier by {@link classifyByFamily}.
+ * Used only as the floor when the live `/serving-endpoints` catalogue
+ * can't be read at resolve time; the live, score-driven classification
+ * supersedes it whenever the workspace listing is available. Tiers are
+ * not hard-coded here - each name is classified by family heuristic.
+ */
+const FALLBACK_MODEL_NAMES = [
+    "databricks-claude-opus-4-8",
+    "databricks-gpt-5-5-pro",
+    "databricks-gemini-3-1-pro",
+    "databricks-claude-sonnet-4-6",
+    "databricks-gpt-5-5",
+    "databricks-meta-llama-3-3-70b-instruct",
+    "databricks-claude-haiku-4-5",
+    "databricks-gpt-5-nano",
+    "databricks-meta-llama-3-1-8b-instruct",
+];
+/**
+ * Static fallback model ids for a tier, drawn from the small built-in
+ * {@link FALLBACK_MODEL_NAMES} list and ordered best-first by family
+ * rank. Sync and workspace-independent: this is the *fallback opinion*
+ * used to seed default lists or when the live catalogue is unreachable
+ * - live resolution prefers `classifyEndpoints`.
+ */
+export function modelsForTier(tier) {
+    return FALLBACK_MODEL_NAMES.map((name) => ({ name, c: classifyByFamily(name) }))
+        .filter((x) => x.c !== null && x.c.tier === tier)
+        .sort((a, b) => b.c.rank - a.c.rank)
+        .map((x) => x.name);
+}
+/** Top static fallback model id for a tier. */
+export function modelForTier(tier) {
+    return modelsForTier(tier)[0];
+}
+/**
+ * Priority-ordered fallback chain (Thinking -> Balanced -> Fast) over
+ * the small built-in list. The floor walked at resolve time when no
+ * agent / plugin / env / request model is set *and* the live
+ * catalogue yields nothing.
+ */
+export const FALLBACK_MODEL_IDS = [
+    ...modelsForTier(ModelTier.Thinking),
+    ...modelsForTier(ModelTier.Balanced),
+    ...modelsForTier(ModelTier.Fast),
+];

package/dist/src/resolve.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Workspace-aware model selection.
+ *
+ * Given a caller's intent (an explicit name, a capability
+ * {@link ModelTier}, or nothing), the resolver returns the endpoint id
+ * to use - always one the workspace actually has, degrading from "best
+ * in tier" down to the static fallback floor. Two entry points:
+ *
+ *   - {@link selectModel} is the high-level, I/O-doing call: hand it a
+ *     `WorkspaceClient` and intent and it lists `/serving-endpoints`
+ *     (cached) and resolves in one step. This is what a non-Mastra
+ *     consumer (e.g. a job that just needs a model name) reaches for.
+ *   - {@link resolveModel} is the pure form over an endpoint list you
+ *     already hold; `selectModel` is a thin wrapper over it.
+ */
+import { ModelTier, type ServingEndpointSummary } from "@dbx-tools/model-shared";
+import { type WorkspaceClientLike } from "./serving.js";
+/** Caller intent passed to {@link resolveModel}. */
+export interface ResolveModelInput {
+    /**
+     * Explicit model id / loose name (per-request override, agent /
+     * plugin default, or env var). When set it wins over `tier` and
+     * `fallbacks`.
+     */
+    explicit?: string;
+    /**
+     * Fuzzy-match an `explicit` name against the live catalogue so loose
+     * names like `"claude sonnet"` resolve. Default `true`. When `false`
+     * the explicit input is returned verbatim (Databricks surfaces the
+     * canonical 404 if it doesn't exist).
+     */
+    fuzzy?: boolean;
+    /** Fuse.js threshold forwarded to {@link resolveModelId}. */
+    threshold?: number;
+    /**
+     * Capability tier to resolve when no `explicit` id is given. The
+     * live catalogue is classified by its Foundation Model API scores
+     * and the top available model in the tier wins, falling back to the
+     * tier's small static list.
+     */
+    tier?: ModelTier;
+    /**
+     * Operator-supplied fallback ids tried *first* in the no-explicit,
+     * no-tier path (e.g. a regulated workspace pinned to an approved
+     * subset), ahead of the auto-classified catalogue.
+     */
+    fallbacks?: readonly string[];
+}
+/** Outcome of {@link resolveModel}: the chosen id plus how it was reached. */
+export interface ResolvedModelSelection {
+    modelId: string;
+    source: "explicit" | "fuzzy-match" | "tier" | "fallback";
+}
+/** Intent + catalogue knobs passed to {@link selectModel}. */
+export interface SelectModelInput extends ResolveModelInput {
+    /** TTL override for the cached `/serving-endpoints` listing, in ms. */
+    ttlMs?: number;
+}
+/**
+ * Resolve a model id for a workspace in one call: list its
+ * `/serving-endpoints` (cached) and run {@link resolveModel} over the
+ * result. This is the entry point for any consumer that holds a
+ * `WorkspaceClient` and just wants a usable model name - a Lakeflow
+ * job, a one-off script, or the Mastra plugin alike.
+ *
+ * Cheap exit: when an `explicit` name is given and `fuzzy` is off, the
+ * catalogue is never fetched - the name is returned verbatim and
+ * Databricks surfaces the canonical 404 if it doesn't exist. Catalogue
+ * fetches otherwise fail loud: network / auth errors propagate so the
+ * caller sees the real SDK message instead of a silent fallback.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()`.
+ */
+export declare function selectModel(client: WorkspaceClientLike, host: string, input?: SelectModelInput): Promise<ResolvedModelSelection>;
+/**
+ * Resolve a model id from the live catalogue and caller intent.
+ *
+ * 1. **Explicit ask**: with `fuzzy` off, returned verbatim; otherwise
+ *    snapped to the closest live endpoint via {@link resolveModelId}.
+ * 2. **Tier intent**: classify the live catalogue and return the top
+ *    available model in that tier, then the tier's static list, then
+ *    the {@link FALLBACK_MODEL_IDS} floor.
+ * 3. **Neither**: walk `fallbacks` first, then the live
+ *    score-classified catalogue (Thinking -> Balanced -> Fast), then
+ *    the static floor, and return the first id actually present.
+ */
+export declare function resolveModel(endpoints: readonly ServingEndpointSummary[], input?: ResolveModelInput): ResolvedModelSelection;

package/dist/src/resolve.js

@@ -0,0 +1,117 @@
+/**
+ * Workspace-aware model selection.
+ *
+ * Given a caller's intent (an explicit name, a capability
+ * {@link ModelTier}, or nothing), the resolver returns the endpoint id
+ * to use - always one the workspace actually has, degrading from "best
+ * in tier" down to the static fallback floor. Two entry points:
+ *
+ *   - {@link selectModel} is the high-level, I/O-doing call: hand it a
+ *     `WorkspaceClient` and intent and it lists `/serving-endpoints`
+ *     (cached) and resolves in one step. This is what a non-Mastra
+ *     consumer (e.g. a job that just needs a model name) reaches for.
+ *   - {@link resolveModel} is the pure form over an endpoint list you
+ *     already hold; `selectModel` is a thin wrapper over it.
+ */
+import { classifyEndpoints, ModelTier, } from "@dbx-tools/model-shared";
+import { FALLBACK_MODEL_IDS, modelsForTier } from "./fallback.js";
+import { listServingEndpoints, resolveModelId, } from "./serving.js";
+/**
+ * Resolve a model id for a workspace in one call: list its
+ * `/serving-endpoints` (cached) and run {@link resolveModel} over the
+ * result. This is the entry point for any consumer that holds a
+ * `WorkspaceClient` and just wants a usable model name - a Lakeflow
+ * job, a one-off script, or the Mastra plugin alike.
+ *
+ * Cheap exit: when an `explicit` name is given and `fuzzy` is off, the
+ * catalogue is never fetched - the name is returned verbatim and
+ * Databricks surfaces the canonical 404 if it doesn't exist. Catalogue
+ * fetches otherwise fail loud: network / auth errors propagate so the
+ * caller sees the real SDK message instead of a silent fallback.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()`.
+ */
+export async function selectModel(client, host, input = {}) {
+    if (input.explicit !== undefined && input.fuzzy === false) {
+        return { modelId: input.explicit, source: "explicit" };
+    }
+    const endpoints = await listServingEndpoints(client, host, {
+        ...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}),
+    });
+    return resolveModel(endpoints, input);
+}
+/**
+ * Resolve a model id from the live catalogue and caller intent.
+ *
+ * 1. **Explicit ask**: with `fuzzy` off, returned verbatim; otherwise
+ *    snapped to the closest live endpoint via {@link resolveModelId}.
+ * 2. **Tier intent**: classify the live catalogue and return the top
+ *    available model in that tier, then the tier's static list, then
+ *    the {@link FALLBACK_MODEL_IDS} floor.
+ * 3. **Neither**: walk `fallbacks` first, then the live
+ *    score-classified catalogue (Thinking -> Balanced -> Fast), then
+ *    the static floor, and return the first id actually present.
+ */
+export function resolveModel(endpoints, input = {}) {
+    if (input.explicit !== undefined) {
+        if (input.fuzzy === false) {
+            return { modelId: input.explicit, source: "explicit" };
+        }
+        const { modelId } = resolveModelId(input.explicit, endpoints, {
+            threshold: input.threshold,
+        });
+        return { modelId, source: "fuzzy-match" };
+    }
+    const classified = classifyEndpoints(endpoints);
+    const chain = input.tier !== undefined
+        ? tierChain(classified, input.tier)
+        : defaultChain(classified, input.fallbacks);
+    return {
+        modelId: pickFirstAvailable(chain, endpoints),
+        source: input.tier !== undefined ? "tier" : "fallback",
+    };
+}
+/**
+ * Candidate chain for an explicit {@link ModelTier} ask: live models
+ * classified into that tier (best-first), then the tier's small static
+ * list, then the full fallback floor as a last resort.
+ */
+function tierChain(classified, tier) {
+    return dedupe([
+        ...classified[tier].map((e) => e.name),
+        ...modelsForTier(tier),
+        ...FALLBACK_MODEL_IDS,
+    ]);
+}
+/**
+ * Candidate chain for the no-explicit default: any operator-supplied
+ * `fallbacks` first, then the live score-classified catalogue in
+ * descending tier order, then the static fallback floor.
+ */
+function defaultChain(classified, fallbacks) {
+    const live = [
+        ...classified[ModelTier.Thinking],
+        ...classified[ModelTier.Balanced],
+        ...classified[ModelTier.Fast],
+    ].map((e) => e.name);
+    return dedupe([...(fallbacks ?? []), ...live, ...FALLBACK_MODEL_IDS]);
+}
+/** Drop duplicate ids while preserving first-seen order. */
+function dedupe(ids) {
+    return [...new Set(ids)];
+}
+/**
+ * Find the first id in `candidates` whose endpoint is present in
+ * `endpoints`. Returns the top candidate when the workspace has none
+ * of them so callers always get a string; an offline workspace then
+ * receives a clean 404 from Databricks instead of a malformed config.
+ */
+function pickFirstAvailable(candidates, endpoints) {
+    const present = new Set(endpoints.map((e) => e.name));
+    for (const candidate of candidates) {
+        if (present.has(candidate))
+            return candidate;
+    }
+    return candidates[0] ?? FALLBACK_MODEL_IDS[0];
+}

package/dist/src/serving.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Live Databricks Model Serving catalogue access.
+ *
+ * Lists the workspace's `/serving-endpoints` once per host and caches
+ * the result with a TTL via AppKit's `CacheManager`, with concurrent
+ * callers sharing one in-flight promise (the coalescing pattern of
+ * Python's `cachetools-async`). Surfaces each endpoint as a stable
+ * {@link ServingEndpointSummary} - including the Foundation Model API
+ * `quality` / `speed` / `cost` profile when present - and snaps loose,
+ * human-typed names to real endpoint ids through `fuse.js` extended
+ * search so tokens like `"claude sonnet"` resolve to
+ * `databricks-claude-sonnet-4-6`.
+ */
+import { type getExecutionContext } from "@databricks/appkit";
+import type { ServingEndpointSummary } from "@dbx-tools/model-shared";
+/**
+ * Structural type for the Databricks workspace client. Derived from
+ * AppKit's `ExecutionContext` so this module doesn't take a direct
+ * dependency on `@databricks/sdk-experimental`; the dep flows in
+ * transitively through `@databricks/appkit`.
+ */
+export type WorkspaceClientLike = ReturnType<typeof getExecutionContext>["client"];
+/** Default TTL for the in-memory endpoint cache. Matches the Databricks SDK's session lifetime budget. */
+export declare const DEFAULT_MODEL_CACHE_TTL_MS: number;
+/** Default Fuse.js score threshold below which a fuzzy match is accepted. */
+export declare const DEFAULT_FUZZY_THRESHOLD = 0.4;
+/**
+ * List Model Serving endpoints for the workspace owning `client`,
+ * routed through AppKit's `CacheManager`. The manager gives us
+ * everything `cachetools.TTLCache` provides plus what
+ * `cachetools-async` adds on top: per-entry TTL, in-flight request
+ * coalescing (concurrent callers share one fetch via the manager's
+ * internal `inFlightRequests` map), bounded size, telemetry spans
+ * (`cache.getOrExecute`), and optional Lakebase persistence so the
+ * catalogue survives restarts when the lakebase plugin is wired up.
+ *
+ * Returns plain {@link ServingEndpointSummary} objects (a stable
+ * subset of the SDK type) so cache hits never expose stale SDK
+ * internals. Errors from `CacheManager` or the SDK fetch propagate
+ * to the caller - we don't swallow them so users see the real
+ * auth / network issue.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()` so multi-host apps share
+ *   one entry per workspace.
+ * @param opts.ttlMs - Override the default TTL just for this call.
+ *   Forwarded to `CacheManager` as seconds.
+ */
+export declare function listServingEndpoints(client: WorkspaceClientLike, host: string, opts?: {
+    ttlMs?: number;
+}): Promise<ServingEndpointSummary[]>;
+/**
+ * Force-evict cached endpoint listings via AppKit's `CacheManager`.
+ * With a `host` deletes that one workspace's entry; without one
+ * clears every cache entry on the manager (since `CacheManager`
+ * doesn't expose a namespace-scoped clear, this is the brute-force
+ * path - fine for tests, avoid in steady-state code).
+ */
+export declare function clearServingEndpointsCache(host?: string): Promise<void>;
+/**
+ * Result of fuzzy-resolving a user-supplied model name against the
+ * live endpoint list. `score` is Fuse.js's distance (`0` is exact,
+ * `1` is no match); `matched` is `false` when the score exceeds the
+ * configured threshold so callers can fall back to the original
+ * input (Databricks will then return a clean 404).
+ */
+export interface ResolvedModel {
+    modelId: string;
+    matched: boolean;
+    score?: number;
+}
+/** Options accepted by {@link resolveModelId}. */
+export interface ResolveModelOptions {
+    /** Fuse.js threshold (0 = exact, 1 = anything). Default `0.4`. */
+    threshold?: number;
+}
+/**
+ * Snap a user-supplied model name to the closest configured serving
+ * endpoint:
+ *
+ * 1. Exact name match wins immediately (no fuzzy needed).
+ * 2. Otherwise the input is tokenized (dashes / underscores / spaces
+ *    become separators) and fed through Fuse.js extended search,
+ *    which AND-s each token with fuzzy matching enabled. This is the
+ *    "tokenized fuzzy match" the user reaches for when they type
+ *    `"claude sonnet"` instead of the full endpoint name.
+ * 3. If the best Fuse score is above `threshold`, return the input
+ *    unchanged and let the upstream call surface the 404. This keeps
+ *    deliberate model ids (e.g. brand new endpoints) from being
+ *    silently rewritten to a similar-looking neighbour.
+ *
+ * Pass an empty endpoint list to short-circuit fuzzy matching - the
+ * input is returned verbatim. This is what callers do when the
+ * workspace client can't be reached at resolve time.
+ */
+export declare function resolveModelId(input: string, endpoints: readonly ServingEndpointSummary[], opts?: ResolveModelOptions): ResolvedModel;

package/dist/src/serving.js

@@ -0,0 +1,188 @@
+/**
+ * Live Databricks Model Serving catalogue access.
+ *
+ * Lists the workspace's `/serving-endpoints` once per host and caches
+ * the result with a TTL via AppKit's `CacheManager`, with concurrent
+ * callers sharing one in-flight promise (the coalescing pattern of
+ * Python's `cachetools-async`). Surfaces each endpoint as a stable
+ * {@link ServingEndpointSummary} - including the Foundation Model API
+ * `quality` / `speed` / `cost` profile when present - and snaps loose,
+ * human-typed names to real endpoint ids through `fuse.js` extended
+ * search so tokens like `"claude sonnet"` resolve to
+ * `databricks-claude-sonnet-4-6`.
+ */
+import { CacheManager } from "@databricks/appkit";
+import { logUtils, stringUtils } from "@dbx-tools/shared";
+import Fuse from "fuse.js";
+const log = logUtils.logger("model/serving");
+/** Default TTL for the in-memory endpoint cache. Matches the Databricks SDK's session lifetime budget. */
+export const DEFAULT_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Default Fuse.js score threshold below which a fuzzy match is accepted. */
+export const DEFAULT_FUZZY_THRESHOLD = 0.4;
+/** Cache key parts under which endpoint listings are stored. */
+const CACHE_KEY_NAMESPACE = "serving-endpoints";
+/**
+ * Stable `userKey` arg for AppKit's `CacheManager.getOrExecute`.
+ * Endpoint visibility is effectively workspace-scoped (we cache by
+ * host in the key parts), so a single shared key lets every user of
+ * the same workspace share one cached fetch and coalesce on the
+ * in-flight promise. Permissions can differ in theory, but the
+ * Foundation Model API catalogue is the same view for every caller.
+ */
+const SHARED_USER_KEY = "model-shared";
+/**
+ * List Model Serving endpoints for the workspace owning `client`,
+ * routed through AppKit's `CacheManager`. The manager gives us
+ * everything `cachetools.TTLCache` provides plus what
+ * `cachetools-async` adds on top: per-entry TTL, in-flight request
+ * coalescing (concurrent callers share one fetch via the manager's
+ * internal `inFlightRequests` map), bounded size, telemetry spans
+ * (`cache.getOrExecute`), and optional Lakebase persistence so the
+ * catalogue survives restarts when the lakebase plugin is wired up.
+ *
+ * Returns plain {@link ServingEndpointSummary} objects (a stable
+ * subset of the SDK type) so cache hits never expose stale SDK
+ * internals. Errors from `CacheManager` or the SDK fetch propagate
+ * to the caller - we don't swallow them so users see the real
+ * auth / network issue.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()` so multi-host apps share
+ *   one entry per workspace.
+ * @param opts.ttlMs - Override the default TTL just for this call.
+ *   Forwarded to `CacheManager` as seconds.
+ */
+export async function listServingEndpoints(client, host, opts = {}) {
+    const ttlSec = Math.max(1, Math.round((opts.ttlMs ?? DEFAULT_MODEL_CACHE_TTL_MS) / 1000));
+    return CacheManager.getInstanceSync().getOrExecute([CACHE_KEY_NAMESPACE, host], () => fetchEndpoints(client), SHARED_USER_KEY, { ttl: ttlSec });
+}
+async function fetchEndpoints(client) {
+    const startedAt = Date.now();
+    const out = [];
+    for await (const ep of client.servingEndpoints.list()) {
+        if (!ep.name)
+            continue;
+        const profile = extractProfile(ep);
+        out.push({
+            name: ep.name,
+            ...(ep.task !== undefined ? { task: ep.task } : {}),
+            ...(ep.state?.ready !== undefined ? { state: String(ep.state.ready) } : {}),
+            ...(ep.description !== undefined ? { description: ep.description } : {}),
+            ...(profile ? { profile } : {}),
+        });
+    }
+    log.debug("listed", { count: out.length, elapsedMs: Date.now() - startedAt });
+    return out;
+}
+/**
+ * Pull the Foundation Model API `quality` / `speed` / `cost` scores
+ * off a serving-endpoint listing entry. Databricks returns these
+ * under `config.served_entities[].foundation_model.ai_gateway_model_profile`
+ * (snake_case at the wire level, preserved verbatim by the SDK), but
+ * the field is newer than the typed `FoundationModel` interface, so we
+ * read it through a structural cast. Returns `undefined` when no
+ * served entity carries a profile (custom models, embeddings, and
+ * brand-new endpoints that Databricks has not scored yet).
+ */
+function extractProfile(ep) {
+    const entities = ep.config?.served_entities;
+    if (!entities)
+        return undefined;
+    for (const entity of entities) {
+        const raw = entity.foundation_model?.ai_gateway_model_profile;
+        if (!raw)
+            continue;
+        const profile = {};
+        if (Number.isFinite(raw.quality))
+            profile.quality = raw.quality;
+        if (Number.isFinite(raw.speed))
+            profile.speed = raw.speed;
+        if (Number.isFinite(raw.cost))
+            profile.cost = raw.cost;
+        if (Object.keys(profile).length > 0)
+            return profile;
+    }
+    return undefined;
+}
+/**
+ * Force-evict cached endpoint listings via AppKit's `CacheManager`.
+ * With a `host` deletes that one workspace's entry; without one
+ * clears every cache entry on the manager (since `CacheManager`
+ * doesn't expose a namespace-scoped clear, this is the brute-force
+ * path - fine for tests, avoid in steady-state code).
+ */
+export async function clearServingEndpointsCache(host) {
+    const cache = CacheManager.getInstanceSync();
+    if (host) {
+        const key = cache.generateKey([CACHE_KEY_NAMESPACE, host], SHARED_USER_KEY);
+        await cache.delete(key);
+    }
+    else {
+        await cache.clear();
+    }
+}
+/**
+ * Snap a user-supplied model name to the closest configured serving
+ * endpoint:
+ *
+ * 1. Exact name match wins immediately (no fuzzy needed).
+ * 2. Otherwise the input is tokenized (dashes / underscores / spaces
+ *    become separators) and fed through Fuse.js extended search,
+ *    which AND-s each token with fuzzy matching enabled. This is the
+ *    "tokenized fuzzy match" the user reaches for when they type
+ *    `"claude sonnet"` instead of the full endpoint name.
+ * 3. If the best Fuse score is above `threshold`, return the input
+ *    unchanged and let the upstream call surface the 404. This keeps
+ *    deliberate model ids (e.g. brand new endpoints) from being
+ *    silently rewritten to a similar-looking neighbour.
+ *
+ * Pass an empty endpoint list to short-circuit fuzzy matching - the
+ * input is returned verbatim. This is what callers do when the
+ * workspace client can't be reached at resolve time.
+ */
+export function resolveModelId(input, endpoints, opts = {}) {
+    if (endpoints.length === 0) {
+        log.debug("resolve:no-endpoints", { input });
+        return { modelId: input, matched: false };
+    }
+    for (const ep of endpoints) {
+        if (ep.name === input) {
+            log.debug("resolve:exact", { input });
+            return { modelId: ep.name, matched: true, score: 0 };
+        }
+    }
+    const threshold = opts.threshold ?? DEFAULT_FUZZY_THRESHOLD;
+    const fuse = new Fuse(endpoints, {
+        keys: ["name"],
+        threshold,
+        ignoreLocation: true,
+        includeScore: true,
+        useExtendedSearch: true,
+        isCaseSensitive: false,
+    });
+    // Fuse 7.3 has no built-in tokenize hook; in extended search,
+    // space-separated tokens are AND-ed with fuzzy matching enabled. We
+    // lean on the shared tokenizer so the splitting rules stay
+    // consistent with the rest of the toolkit.
+    const query = Array.from(stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input)).join(" ");
+    if (!query) {
+        log.debug("resolve:empty-tokens", { input });
+        return { modelId: input, matched: false };
+    }
+    const results = fuse.search(query);
+    const best = results[0];
+    if (best?.item.name && (best.score ?? 0) <= threshold) {
+        log.debug("resolve:fuzzy-match", {
+            input,
+            modelId: best.item.name,
+            score: best.score,
+        });
+        return { modelId: best.item.name, matched: true, score: best.score };
+    }
+    log.debug("resolve:no-match", {
+        input,
+        bestScore: best?.score,
+        threshold,
+    });
+    return { modelId: input, matched: false };
+}