@dbx-tools/appkit-mastra 0.1.41 → 0.1.48

package/dist/index.d.ts

@@ -11,11 +11,10 @@
  * consumers.
  */
 export * from "@dbx-tools/appkit-mastra-shared";
+export * from "@dbx-tools/model";
 export * from "./src/agents.js";
 export * from "./src/chart.js";
 export * from "./src/config.js";
 export * from "./src/genie.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, ModelTier, modelForTier, modelsForTier, } from "./src/model.js";
 export * from "./src/plugin.js";
-export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, clearServingEndpointsCache, extractModelOverride, listServingEndpoints, resolveModelId, type ResolveModelOptions, type ResolvedModel, type ServingEndpointSummary, } from "./src/serving.js";
-export * from "./src/tools/email.js";
+export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, extractModelOverride, type ModelOverrideRequest, } from "./src/serving.js";

package/dist/index.js

@@ -11,11 +11,10 @@
  * consumers.
  */
 export * from "@dbx-tools/appkit-mastra-shared";
+export * from "@dbx-tools/model";
 export * from "./src/agents.js";
 export * from "./src/chart.js";
 export * from "./src/config.js";
 export * from "./src/genie.js";
-export { FALLBACK_MODEL_IDS, MODEL_CATALOG, ModelTier, modelForTier, modelsForTier, } from "./src/model.js";
 export * from "./src/plugin.js";
-export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, clearServingEndpointsCache, extractModelOverride, listServingEndpoints, resolveModelId, } from "./src/serving.js";
-export * from "./src/tools/email.js";
+export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, extractModelOverride, } from "./src/serving.js";

package/dist/src/agents.d.ts

@@ -10,7 +10,7 @@
  *
  * When no agents are registered the plugin falls back to a single
  * built-in analyst so the bare `mastra()` call still mounts a working
- * `chatRoute` agent for demos.
+ * streamable agent for demos.
  */
 import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
@@ -185,8 +185,8 @@ export type MastraToolsFn = (plugins: MastraPlugins) => MastraTools | Promise<Ma
 /**
  * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
  * plugin uses for `AgentDefinition`. The registry key under
- * `config.agents` is what `chatRoute` matches on; `name` is purely
- * informational (defaults to the key).
+ * `config.agents` is the `agentId` the client streams against; `name`
+ * is purely informational (defaults to the key).
  */
 export interface MastraAgentDefinition {
     /** Display name used as `Agent.name`. Defaults to the registry key. */

package/dist/src/agents.js

@@ -10,7 +10,7 @@
  *
  * When no agents are registered the plugin falls back to a single
  * built-in analyst so the bare `mastra()` call still mounts a working
- * `chatRoute` agent for demos.
+ * streamable agent for demos.
  */
 import { appkitUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";

package/dist/src/chart.d.ts

@@ -144,4 +144,10 @@ export declare function fetchChart(chartId: string, options?: FetchChartOptions)
  * `prepare_chart` tool, which accepts a `statement_id` and
  * resolves the rows lazily.
  */
-export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "render_data", unknown>;
+export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<{
+    title: string;
+    data: readonly Record<string, unknown>[];
+    description?: string | undefined;
+}, {
+    chartId: string;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;

package/dist/src/chart.js

@@ -30,7 +30,7 @@ import { commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
-import { buildModel, modelForTier, ModelTier } from "./model.js";
+import { buildModel, ModelClass } from "./model.js";
 const log = logUtils.logger("mastra/chart");
 /* ------------------------------ constants ------------------------------ */
 /**
@@ -276,9 +276,7 @@ function getPlannerAgent(config) {
             name: "Chart Planner",
             description: "Picks chart type and axis encodings for a dataset.",
             instructions: CHART_PLANNER_INSTRUCTIONS,
-            model: ({ requestContext }) => buildModel(config, requestContext, {
-                modelId: modelForTier(ModelTier.Fast),
-            }),
+            model: ({ requestContext }) => buildModel(config, requestContext, { modelClass: ModelClass.ChatFast }),
         });
         plannerAgents.set(config, agent);
     }
@@ -302,7 +300,7 @@ async function runChartPlanner(config, request, options = {}) {
         ...(requestContext ? { requestContext } : {}),
         ...(abortSignal ? { abortSignal } : {}),
     });
-    const plan = result.object;
+    const plan = chartPlanSchema.parse(result.object);
     const option = planToEchartsOption(plan, title);
     return { chartType: plan.chartType, option };
 }

package/dist/src/config.d.ts

@@ -4,7 +4,8 @@
  * Kept in a leaf module so `plugin.ts`, `server.ts`, `model.ts`, and
  * `memory.ts` can import them without creating a cycle.
  */
-import type { BasePluginConfig, getExecutionContext } from "@databricks/appkit";
+import type { BasePluginConfig } from "@databricks/appkit";
+import type { appkitUtils } from "@dbx-tools/shared";
 import type { AgentConfig } from "@mastra/core/agent";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 import type { MastraAgentDefinition, MastraTools } from "./agents.js";
@@ -51,7 +52,7 @@ export declare const TRACE_REQUEST_CONTEXT_KEYS: readonly string[];
 /** AppKit execution context plus the canonical user id. */
 export interface User {
     id: string;
-    executionContext: ReturnType<typeof getExecutionContext>;
+    executionContext: appkitUtils.ExecutionContextLike;
 }
 /** PgVector config with an optional Mastra store id. */
 export type MastraMemoryConfig = PgVectorConfig & {
@@ -125,7 +126,8 @@ export interface MastraPluginConfig extends BasePluginConfig {
      */
     tools?: MastraTools;
     /**
-     * Agent id used by `chatRoute` when the client doesn't specify one.
+     * Agent id used when the client doesn't specify one (the bare,
+     * un-suffixed history / suggestions routes resolve to it).
      * Defaults to the first key in `agents` (or `"default"` when
      * `agents` is omitted). Must match an id in `agents` when both are
      * set; a mismatch throws at setup with the available candidates.
@@ -173,17 +175,20 @@ 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
+     * 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.
      */
     defaultModelFallbacks?: readonly string[];
     /**

package/dist/src/genie.d.ts

@@ -142,18 +142,6 @@ export declare function buildGenieToolkitProvider(opts: {
 }): {
     toolkit(opts?: unknown): MastraTools;
 };
-/**
- * Returns `true` when at least one Genie space is reachable
- * through {@link resolveGenieSpaces} - either via
- * {@link MastraPluginConfig.genieSpaces}, the AppKit `genie()`
- * plugin instance, or the `DATABRICKS_GENIE_SPACE_ID` env var.
- *
- * Cheap to call from `resolveProvider` to short-circuit `genie`
- * lookups when nothing is wired, so the `plugins.genie` lookup
- * still resolves to `undefined` (matching AppKit's
- * absent-plugin semantics) when neither source is configured.
- */
-export declare function hasAnyGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): boolean;
 /**
  * Collect the curated starter questions across every resolved Genie
  * space, deduped and capped. Each space's `sample_questions` are

package/dist/src/genie.js

@@ -37,7 +37,7 @@ import { CacheManager, genie } from "@databricks/appkit";
 import { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
 import { ChartSchema, } from "@dbx-tools/appkit-mastra-shared";
 import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
-import {} from "@dbx-tools/genie-shared";
+import { GenieMessageSchema } from "@dbx-tools/genie-shared";
 import { appkitUtils, commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import { createTool } from "@mastra/core/tools";
@@ -334,7 +334,7 @@ function buildAskGenieTool(opts) {
             question: z.string().min(1, "question is required"),
         }),
         outputSchema: z.object({
-            message: z.custom(),
+            message: GenieMessageSchema,
         }),
         execute: async ({ question }, ctxRaw) => {
             const ctx = ctxRaw;
@@ -891,20 +891,6 @@ export function buildGenieToolkitProvider(opts) {
         },
     };
 }
-/**
- * Returns `true` when at least one Genie space is reachable
- * through {@link resolveGenieSpaces} - either via
- * {@link MastraPluginConfig.genieSpaces}, the AppKit `genie()`
- * plugin instance, or the `DATABRICKS_GENIE_SPACE_ID` env var.
- *
- * Cheap to call from `resolveProvider` to short-circuit `genie`
- * lookups when nothing is wired, so the `plugins.genie` lookup
- * still resolves to `undefined` (matching AppKit's
- * absent-plugin semantics) when neither source is configured.
- */
-export function hasAnyGenieSpaces(config, context) {
-    return Object.keys(resolveGenieSpaces(config, context)).length > 0;
-}
 /* --------------------------- starter suggestions --------------------------- */
 /**
  * Default cap on starter suggestions surfaced to the chat empty

package/dist/src/history.d.ts

@@ -9,8 +9,8 @@
  *
  * The route is registered through {@link historyRoute} as a Mastra
  * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * `chatRoute`. That means the `MastraServer` auth middleware (in
- * `./server.ts`) has already populated `RequestContext` with
+ * the standard agent routes. That means the `MastraServer` auth
+ * middleware (in `./server.ts`) has already populated `RequestContext` with
  * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
@@ -83,10 +83,10 @@ export type HistoryRouteOptions = {
  *     anchors the thread id is left alone so the user keeps the
  *     same thread - only the contents go away.
  *
- * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
- * fixed-agent mount, or include `:agentId` in the path for dynamic
- * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
- * layout (`/route/chat` + `/route/chat/:agentId`).
+ * Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
+ * binding: pass `agent` for a fixed-agent mount, or include
+ * `:agentId` in the path for dynamic routing. The plugin registers
+ * both `/route/history` (default agent) and `/route/history/:agentId`.
  *
  * The handler reads `threadId` and `resourceId` from `RequestContext`
  * (populated upstream by `MastraServer.registerAuthMiddleware`), so

package/dist/src/history.js

@@ -9,8 +9,8 @@
  *
  * The route is registered through {@link historyRoute} as a Mastra
  * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * `chatRoute`. That means the `MastraServer` auth middleware (in
- * `./server.ts`) has already populated `RequestContext` with
+ * the standard agent routes. That means the `MastraServer` auth
+ * middleware (in `./server.ts`) has already populated `RequestContext` with
  * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
@@ -153,10 +153,10 @@ export async function clearHistory(opts) {
  *     anchors the thread id is left alone so the user keeps the
  *     same thread - only the contents go away.
  *
- * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
- * fixed-agent mount, or include `:agentId` in the path for dynamic
- * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
- * layout (`/route/chat` + `/route/chat/:agentId`).
+ * Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
+ * binding: pass `agent` for a fixed-agent mount, or include
+ * `:agentId` in the path for dynamic routing. The plugin registers
+ * both `/route/history` (default agent) and `/route/history/:agentId`.
  *
  * The handler reads `threadId` and `resourceId` from `RequestContext`
  * (populated upstream by `MastraServer.registerAuthMiddleware`), so

package/dist/src/model.d.ts

@@ -7,148 +7,41 @@
  * fresh bearer header, then point Mastra's OpenAI-compatible provider
  * at `/serving-endpoints` on that host.
  *
- * Model id resolution walks three sources before falling back to the
- * hard-coded default, **in this priority order**:
- *
- *   1. Per-request override stashed by the auth middleware under
- *      {@link MASTRA_MODEL_OVERRIDE_KEY} (header / query / body).
- *   2. The static `modelId` passed in by the agent / plugin (string
- *      sugar on `def.model` or `config.defaultModel`).
- *   3. `DATABRICKS_SERVING_ENDPOINT_NAME` env var.
- *   4. {@link FALLBACK_MODEL_ID}.
- *
- * Whatever wins is then fuzzy-matched against the live
- * `/serving-endpoints` list ({@link listServingEndpoints}) so loose
- * names like `"claude sonnet"` resolve to the real endpoint name.
- * Fuzzy matching is best-effort: when the workspace client throws
- * (network blip, expired token at cache-fill time) we fall back to
- * the input verbatim and let Databricks return the canonical error.
+ * This module only adds the Mastra-specific glue. The actual model
+ * selection - listing the workspace catalogue and resolving an
+ * explicit name / class / 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 / class / 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 ModelClass } 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, ModelClass, modelForClass, modelsForClass, } 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 / class / fallback.
      */
     modelId?: string;
+    /**
+     * Chat capability class to resolve when no explicit model id is
+     * supplied. Used by internal agents (e.g. the chart planner asks for
+     * {@link ModelClass.ChatFast}) to express intent without pinning an
+     * endpoint name; the live catalogue is classified and the top
+     * available model in the class is chosen, falling back to the
+     * class's static list when the workspace has none.
+     */
+    modelClass?: ModelClass;
 }
 /**
  * Resolve a `MastraModelConfig` for the current agent step. Runs