@dbx-tools/appkit-mastra 0.6.224 → 0.6.225

package/src/agents.ts

@@ -24,7 +24,6 @@ import type {
   ToolProvider,
 } from "@databricks/appkit/beta";
 import { plugin } from "@dbx-tools/appkit";
-import { fallback } from "@dbx-tools/model";
 import { log, object, string } from "@dbx-tools/shared-core";
 import type {
   AgentConfig,
@@ -368,18 +367,21 @@ export type MastraMemoryConfigOverride = DistributiveOmit<PgVectorConfig, "id">
   id?: string;
 };
 
+/** How an agent's unpinned model is resolved. */
+export type AgentDefaultModel =
+  { kind: "auto" } | { kind: "configured"; model: string } | { kind: "dynamic" };
+
 /** Output of {@link buildAgents}: resolved agents plus the default id. */
 export interface BuiltAgents {
   agents: Record<string, Agent>;
   defaultAgentId: string;
   /**
-   * Static default serving-endpoint id per agent id, as resolved by
-   * {@link describeAgentDefaultModel}. `"<dynamic>"` when the model is a
-   * function decided at call time. Consumed by the plugin's
-   * `GET /default-model` route handler so the client's model picker can label
-   * its default option with the real endpoint's humanized name.
+   * Default model intent per agent id. An unconfigured agent is `"auto"` and
+   * resolves the highest-ranked live endpoint; a string is `"configured"`; a
+   * custom function is `"dynamic"`. Consumed by the plugin's
+   * `GET /default-model` route.
    */
-  defaultModels: Record<string, string>;
+  defaultModels: Record<string, AgentDefaultModel>;
   /**
    * Ambient tools shared across every agent (the built-in system tools
    * spread with `config.tools`). Surfaced so the optional MCP server
@@ -559,7 +561,7 @@ export async function buildAgents(opts: {
     ...(config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor]),
   ];
   const agents: Record<string, Agent> = {};
-  const defaultModels: Record<string, string> = {};
+  const defaultModels: Record<string, AgentDefaultModel> = {};
   const approvalGatedByAgent: Array<{ agentId: string; toolIds: string[] }> = [];
 
   for (const [id, def] of Object.entries(definitions)) {
@@ -613,7 +615,8 @@ export async function buildAgents(opts: {
     log.info("agent registered", {
       id,
       name: def.name ?? id,
-      defaultModel,
+      defaultModel:
+        defaultModel.kind === "configured" ? defaultModel.model : `<${defaultModel.kind}>`,
       tools: Object.keys(tools),
     });
   }
@@ -682,34 +685,28 @@ function assertApprovalGatedToolsHaveStorage(
 }
 
 /**
- * Best-effort description of the *static* default model an agent will
- * resolve to at call time. Walks the same precedence ladder as
- * {@link resolveModel} / {@link buildModel}:
+ * Describe how an agent resolves its unpinned model:
  *
- *   1. Per-agent `def.model` (string sugar -> the literal id;
- *      function / `DynamicArgument` -> `"<dynamic>"` because the
- *      resolver decides at call time).
+ *   1. Per-agent `def.model` (string sugar is configured; a function is
+ *      dynamic).
  *   2. Plugin-level `config.defaultModel` (same rules).
  *   3. `DATABRICKS_SERVING_ENDPOINT_NAME` env var.
- *   4. First entry of `config.defaultModelFallbacks ?? fallback.FALLBACK_MODEL_IDS`.
+ *   4. Automatic live-catalogue ranking when none is set.
  *
  * Used for the startup `agent registered` log so operators can see
- * which endpoint each agent points at by default. Per-request
- * overrides (`X-Mastra-Model` etc.) and the workspace-catalogue
- * fuzzy match are still applied at runtime.
+ * `defaultModelFallbacks` remains an operator-pinned candidate list inside the
+ * automatic live lookup; it is not advertised as a model until availability is
+ * checked.
  */
 function describeAgentDefaultModel(
   config: MastraPluginConfig,
   def: AnyMastraAgentDefinition,
-): string {
+): AgentDefaultModel {
   const effective = def.model ?? config.defaultModel;
-  if (typeof effective === "string") return effective;
-  if (effective !== undefined) return "<dynamic>";
-  return (
-    process.env.DATABRICKS_SERVING_ENDPOINT_NAME ??
-    config.defaultModelFallbacks?.[0] ??
-    fallback.FALLBACK_MODEL_IDS[0]!
-  );
+  if (typeof effective === "string") return { kind: "configured", model: effective };
+  if (effective !== undefined) return { kind: "dynamic" };
+  const environment = process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
+  return environment ? { kind: "configured", model: environment } : { kind: "auto" };
 }
 
 /**

package/src/config.ts

@@ -327,11 +327,10 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * When unset, resolution is driven by the live Foundation Model API
    * `quality` / `speed` / `cost` scores: endpoints are classified into
    * chat classes (`classifyEndpoints`) and walked best-first
-   * (ChatThinking -> ChatBalanced -> ChatFast), 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.
+   * (ChatThinking -> ChatBalanced -> ChatFast). The automatic default is
+   * live-only and fails when no matching endpoint is currently available.
+   * 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[];
   /**
@@ -654,7 +653,7 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     defaultModel: {
       type: "string",
       description:
-        "Serving endpoint applied to every agent that omits its own model. Falls back to DATABRICKS_SERVING_ENDPOINT_NAME, then the auto-resolved catalogue.",
+        "Serving endpoint applied to every agent that omits its own model. Falls back to DATABRICKS_SERVING_ENDPOINT_NAME, then the highest-ranked currently available catalogue endpoint.",
     },
     defaultModelFallbacks: {
       type: "array",

package/src/model.ts

@@ -27,7 +27,7 @@ import { getExecutionContext } from "@databricks/appkit";
 import { classes, invoke, resolve } from "@dbx-tools/model";
 import { ModelServingApi, modelServingApi } from "@dbx-tools/model-rs";
 import { functionModule, json, log, net } from "@dbx-tools/shared-core";
-import { model } from "@dbx-tools/shared-model";
+import { model, type ServingEndpointSummary } from "@dbx-tools/shared-model";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
 
@@ -74,6 +74,43 @@ export interface BuildModelOverrides {
   modelClass?: ModelClass;
 }
 
+function selectionInput(
+  config: MastraPluginConfig,
+  requested: string | undefined,
+  defaultClass: ModelClass | undefined,
+  serving = resolveServingConfig(config),
+) {
+  const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
+  const explicit = requestedClass === null ? requested : undefined;
+  const modelClass = requestedClass ?? defaultClass;
+  return {
+    ...(explicit !== undefined ? { explicit } : {}),
+    fuzzy: serving.fuzzy,
+    threshold: serving.threshold,
+    ...(modelClass !== undefined ? { modelClass } : {}),
+    fallbacks: serving.fallbacks,
+    liveOnly: requested === undefined,
+    ttlMs: serving.ttlMs,
+  };
+}
+
+/**
+ * Resolve an agent's unpinned default against an already-loaded live catalogue.
+ *
+ * With no configured id/class/fallback, the generic model ranker selects the
+ * highest-ranked currently available GPT, then falls back to the highest-ranked
+ * live chat endpoint when the workspace has no GPT.
+ */
+export function resolveDefaultModelId(
+  config: MastraPluginConfig,
+  endpoints: readonly ServingEndpointSummary[],
+  overrides: BuildModelOverrides = {},
+): string {
+  const requested = overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
+  return resolve.resolveModel(endpoints, selectionInput(config, requested, overrides.modelClass))
+    .modelId;
+}
+
 /**
  * Resolve a `MastraModelConfig` for the current agent step. Runs
  * while `agent.stream` is inside the `asUser(req)` scope so tokens
@@ -122,18 +159,12 @@ export async function buildModel(
   // internal `overrides.modelClass` (e.g. the chart planner) is the
   // floor when nothing was requested.
   const requested = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
-  const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
-  const explicit = requestedClass === null ? requested : undefined;
-  const modelClass = requestedClass ?? overrides.modelClass;
 
-  const { modelId, source } = await selectModel(executionContext.client, host, {
-    ...(explicit !== undefined ? { explicit } : {}),
-    fuzzy: serving.fuzzy,
-    threshold: serving.threshold,
-    ...(modelClass !== undefined ? { modelClass } : {}),
-    fallbacks: serving.fallbacks,
-    ttlMs: serving.ttlMs,
-  });
+  const { modelId, source } = await selectModel(
+    executionContext.client,
+    host,
+    selectionInput(config, requested, overrides.modelClass, serving),
+  );
   logger.debug("model selected", { modelId, source, requested });
 
   return {

package/src/plugin.ts

@@ -95,6 +95,7 @@ import {
 import { buildMcpServer, type ResolvedMcp } from "./mcp.ts";
 import { createMemoryBuilder, createServicePrincipalPool, needsLakebase } from "./memory.ts";
 import { logFeedback, resolveFeedbackEnabled } from "./mlflow.ts";
+import { resolveDefaultModelId } from "./model.ts";
 import { buildObservability } from "./observability.ts";
 import { provisionRemoteSkills } from "./remote-skills.ts";
 import {
@@ -506,16 +507,12 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       },
     });
 
-    // `GET /default-model` (and `/default-model/:agentId`) reports the static
-    // serving-endpoint an agent falls back to when the client pins no model,
-    // so the picker can label its default option with the model's humanized
-    // name. Agent-scoped via the optional `/:agentId` suffix (URL symmetry
-    // with the history / threads / suggestions routes), defaulting to the
-    // default agent. `model` / `displayName` are null when the agent has no
-    // static default (a dynamic, call-time model); an unknown agent id is a
-    // 404, matching the history / threads routes. Reads only in-memory build
-    // state, so it needs no OBO scoping. Registered before the catch-all,
-    // same as `/models`.
+    // `GET /default-model` (and `/default-model/:agentId`) reports what an
+    // unpinned turn will use. A configured string is returned directly; an
+    // automatic default resolves the highest-ranked currently available GPT
+    // (or general chat fallback) from the same OBO-scoped live catalogue as
+    // `/models`; a custom dynamic resolver remains null because it is call-time
+    // application code.
     const handleDefaultModel = async (
       req: express.Request,
       res: express.Response,
@@ -526,11 +523,20 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         return;
       }
       const agentId = requested ?? this.built?.defaultAgentId ?? FALLBACK_AGENT_ID;
-      const raw = this.built?.defaultModels[agentId];
-      // `"<dynamic>"` (a call-time function) has no fixed id to advertise.
-      const model = raw && raw !== "<dynamic>" ? raw : null;
-      // Return the humanized label too, so the picker shows a friendly name on
-      // load without waiting on the `/models` catalogue (no raw-id flash).
+      const intent = this.built?.defaultModels[agentId];
+      let model: string | null = null;
+      if (intent?.kind === "configured") {
+        model = intent.model;
+      } else if (intent?.kind === "auto") {
+        const result = await this.scopedSelf(req).listModelsResult();
+        if (!result.ok) {
+          this.sendFailure(res, result, "default-model", MODEL_CATALOGUE_FAILED_MESSAGE);
+          return;
+        }
+        if (result.data.length > 0) {
+          model = resolveDefaultModelId(this.config, result.data);
+        }
+      }
       res.json({
         agentId,
         model,