@dbx-tools/appkit-mastra 0.1.42 → 0.1.56

package/index.ts

@@ -25,4 +25,3 @@ export {
   extractModelOverride,
   type ModelOverrideRequest,
 } from "./src/serving.js";
-export * from "./src/tools/email.js";

package/package.json

@@ -9,14 +9,14 @@
     }
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.42",
+  "version": "0.1.56",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@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",
+    "@dbx-tools/appkit-mastra-shared": "0.1.56",
+    "@dbx-tools/genie": "0.1.56",
+    "@dbx-tools/genie-shared": "0.1.56",
+    "@dbx-tools/model": "0.1.56",
+    "@dbx-tools/shared": "0.1.56",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",
@@ -28,11 +28,6 @@
     "pg": "^8.20.0",
     "zod": "^4.3.6"
   },
-  "devDependencies": {
-    "@types/express": "^5",
-    "@types/pg": "^8",
-    "express": "^5"
-  },
   "module": "index.ts",
   "peerDependencies": {
     "@databricks/appkit": "^0.41",

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, ModelTier } from "./model.js";
+import { buildModel, ModelClass } from "./model.js";
 
 const log = logUtils.logger("mastra/chart");
 
@@ -330,7 +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, { tier: ModelTier.Fast }),
+        buildModel(config, requestContext, { modelClass: ModelClass.ChatFast }),
     });
     plannerAgents.set(config, agent);
   }

package/src/config.ts

@@ -5,7 +5,8 @@
  * `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 {
   MASTRA_RESOURCE_ID_KEY,
@@ -71,7 +72,7 @@ export 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. */
@@ -207,9 +208,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
-   * 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
+   * 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.
    */

package/src/model.ts

@@ -9,19 +9,19 @@
  *
  * 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
+ * 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 / tier / fallback knobs through, and wrap
+ * 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 ModelTier, parseModelTier, selectModel } from "@dbx-tools/model";
+import { type ModelClass, parseModelClass, 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";
@@ -32,9 +32,9 @@ import { MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig } from "./serving.js";
 export {
   classifyEndpoints,
   FALLBACK_MODEL_IDS,
-  modelForTier,
-  modelsForTier,
-  ModelTier,
+  ModelClass,
+  modelForClass,
+  modelsForClass,
 } from "@dbx-tools/model";
 
 /** Optional overrides accepted by {@link buildModel}. */
@@ -42,18 +42,18 @@ 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 / tier / fallback.
+   * override but wins over env / class / 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
+   * 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 tier is chosen, falling back to the
-   * tier's static list when the workspace has none.
+   * available model in the class is chosen, falling back to the
+   * class's static list when the workspace has none.
    */
-  tier?: ModelTier;
+  modelClass?: ModelClass;
 }
 
 /**
@@ -85,23 +85,23 @@ export async function buildModel(
     : undefined;
 
   // 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.
+  // endpoint name or a model class slug ("chat-thinking" /
+  // "chat-balanced" / "chat-fast"). A class slug becomes a class 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.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 requestedTier = requested !== undefined ? parseModelTier(requested) : null;
-  const explicit = requestedTier === null ? requested : undefined;
-  const tier = requestedTier ?? overrides.tier;
+  const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
+  const explicit = requestedClass === null ? requested : undefined;
+  const modelClass = requestedClass ?? overrides.modelClass;
 
   const { modelId, source } = await selectModel(user.executionContext.client, host, {
     ...(explicit !== undefined ? { explicit } : {}),
     fuzzy: serving.fuzzy,
     threshold: serving.threshold,
-    ...(tier !== undefined ? { tier } : {}),
+    ...(modelClass !== undefined ? { modelClass } : {}),
     fallbacks: serving.fallbacks,
     ttlMs: serving.ttlMs,
   });

package/src/serving.ts

@@ -2,7 +2,7 @@
  * Mastra-specific glue over the generic `@dbx-tools/model` toolkit.
  *
  * The live `/serving-endpoints` catalogue access, fuzzy name
- * resolution, and tier/fallback selection all live in
+ * resolution, and class/fallback selection all live in
  * `@dbx-tools/model`; this module only adds what is specific to the
  * Mastra plugin: pulling a per-request model override off an HTTP
  * request (header / query / body) and projecting the plugin config

package/dist/src/tools/email.d.ts

@@ -1,83 +0,0 @@
-/**
- * Mastra tool: `send_email`. Gated behind {@link requireApproval}
- * so the model can call it freely but execution is paused until a
- * human approves via the chat UI.
- *
- * The execute body is a stub - it logs the would-be email to the
- * server console (via `logUtils.logger`) and returns success. Swap
- * in a real SMTP / SES / Resend / Workspace Mail call later by
- * editing the `execute` body; the tool surface and approval gate
- * stay the same.
- *
- * Approval flow (Mastra + AI SDK V5):
- *
- * 1. Model calls the tool with `{ to, subject, body, ... }`.
- * 2. Mastra evaluates `requireApproval` (here always `true`),
- *    pauses the agent loop, and emits a `tool-call-approval`
- *    chunk on the response stream.
- * 3. The chat client renders an approve/deny prompt against the
- *    `state: 'approval-requested'` tool part. On approve, it sends
- *    a `MastraToolApproval` response back; on deny, the tool call
- *    is rejected and the model sees an error.
- * 4. On approve, this `execute` runs and logs the email.
- *
- * The tool is intentionally NOT auto-installed on every agent -
- * email is domain-specific, not infrastructure. Spread it into the
- * specific agents that should be able to draft emails.
- */
-import { z } from "zod";
-declare const emailInputSchema: z.ZodObject<{
-    to: z.ZodString;
-    subject: z.ZodString;
-    body: z.ZodString;
-    cc: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    bcc: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-/** Options accepted by {@link buildEmailTool}. */
-export interface BuildEmailToolOptions {
-    /**
-     * Override the tool id. Defaults to `"send_email"`. Useful if a
-     * caller wants `send_internal_email` / `send_external_email`
-     * variants.
-     */
-    id?: string;
-    /**
-     * Replace the default execute body with a real provider call.
-     * Receives the validated input and must return `{sent, recipient}`.
-     * The console-log default is meant for demos / dev; production
-     * deployments should wire SMTP / SES / Resend / Workspace Mail
-     * here.
-     */
-    send?: (input: z.infer<typeof emailInputSchema>) => Promise<void> | void;
-}
-/**
- * Build the `send_email` tool. Approval-gated by default; the
- * execute body either calls the supplied {@link send} hook or
- * logs the email to the server console as a demo stub.
- *
- * @example
- * ```ts
- * import { buildEmailTool, createAgent, mastra } from "@dbx-tools/appkit-mastra";
- *
- * const support = createAgent({
- *   instructions: "...",
- *   tools(plugins) {
- *     return {
- *       ...(plugins.genie?.toolkit() ?? {}),
- *       send_email: buildEmailTool(),
- *     };
- *   },
- * });
- * ```
- */
-export declare function buildEmailTool(opts?: BuildEmailToolOptions): import("@mastra/core/tools").Tool<{
-    to: string;
-    subject: string;
-    body: string;
-    cc?: string[] | undefined;
-    bcc?: string[] | undefined;
-}, {
-    sent: boolean;
-    recipient: string;
-}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
-export {};

package/dist/src/tools/email.js

@@ -1,121 +0,0 @@
-/**
- * Mastra tool: `send_email`. Gated behind {@link requireApproval}
- * so the model can call it freely but execution is paused until a
- * human approves via the chat UI.
- *
- * The execute body is a stub - it logs the would-be email to the
- * server console (via `logUtils.logger`) and returns success. Swap
- * in a real SMTP / SES / Resend / Workspace Mail call later by
- * editing the `execute` body; the tool surface and approval gate
- * stay the same.
- *
- * Approval flow (Mastra + AI SDK V5):
- *
- * 1. Model calls the tool with `{ to, subject, body, ... }`.
- * 2. Mastra evaluates `requireApproval` (here always `true`),
- *    pauses the agent loop, and emits a `tool-call-approval`
- *    chunk on the response stream.
- * 3. The chat client renders an approve/deny prompt against the
- *    `state: 'approval-requested'` tool part. On approve, it sends
- *    a `MastraToolApproval` response back; on deny, the tool call
- *    is rejected and the model sees an error.
- * 4. On approve, this `execute` runs and logs the email.
- *
- * The tool is intentionally NOT auto-installed on every agent -
- * email is domain-specific, not infrastructure. Spread it into the
- * specific agents that should be able to draft emails.
- */
-import { logUtils, stringUtils } from "@dbx-tools/shared";
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-const log = logUtils.logger("mastra/tool/send-email");
-const emailInputSchema = z.object({
-    to: z.string().describe(stringUtils.toDescription(`
-    Single recipient email address (e.g. "alice@example.com"). For
-    multiple recipients, comma-separate them yourself.
-  `)),
-    subject: z.string().describe(stringUtils.toDescription(`
-    Subject line.
-  `)),
-    body: z.string().describe(stringUtils.toDescription(`
-    Email body. Plain text or markdown; the renderer downstream decides
-    which to honour. Be specific - the recipient may not have any
-    context the model has from prior chat turns.
-  `)),
-    cc: z
-        .array(z.string())
-        .optional()
-        .describe(stringUtils.toDescription(`
-      Optional CC recipients.
-    `)),
-    bcc: z
-        .array(z.string())
-        .optional()
-        .describe(stringUtils.toDescription(`
-      Optional BCC recipients.
-    `)),
-});
-const emailOutputSchema = z.object({
-    sent: z.boolean().describe(stringUtils.toDescription(`
-    True when the email was dispatched. The current implementation
-    always returns true after console-logging the would-be email; swap
-    in a real provider to make this meaningful.
-  `)),
-    recipient: z.string().describe(stringUtils.toDescription(`
-    Echo of the \`to\` field for confirmation.
-  `)),
-});
-/**
- * Build the `send_email` tool. Approval-gated by default; the
- * execute body either calls the supplied {@link send} hook or
- * logs the email to the server console as a demo stub.
- *
- * @example
- * ```ts
- * import { buildEmailTool, createAgent, mastra } from "@dbx-tools/appkit-mastra";
- *
- * const support = createAgent({
- *   instructions: "...",
- *   tools(plugins) {
- *     return {
- *       ...(plugins.genie?.toolkit() ?? {}),
- *       send_email: buildEmailTool(),
- *     };
- *   },
- * });
- * ```
- */
-export function buildEmailTool(opts = {}) {
-    return createTool({
-        id: opts.id ?? "send_email",
-        description: stringUtils.toDescription(`
-      Send an email on the user's behalf. Pass a recipient address,
-      subject, and body; the user will be prompted to approve the send
-      before it goes out (the tool is approval-gated). Use this when
-      the user explicitly asks to send / forward / share something via
-      email - never autonomously. Keep subjects short and bodies
-      focused; the recipient may not have any of the chat context.
-    `),
-        inputSchema: emailInputSchema,
-        outputSchema: emailOutputSchema,
-        requireApproval: true,
-        execute: async (input) => {
-            const { to, subject, body, cc, bcc } = input;
-            // Default behaviour: dump the email to the server console so
-            // demos can see the gate fire end-to-end without a real
-            // provider. Replace by passing `opts.send`.
-            log.info("send", {
-                to,
-                ...(cc && cc.length > 0 ? { cc } : {}),
-                ...(bcc && bcc.length > 0 ? { bcc } : {}),
-                subject,
-                bodyLength: body.length,
-                body,
-            });
-            if (opts.send) {
-                await opts.send(input);
-            }
-            return { sent: true, recipient: to };
-        },
-    });
-}

package/src/tools/email.ts

@@ -1,158 +0,0 @@
-/**
- * Mastra tool: `send_email`. Gated behind {@link requireApproval}
- * so the model can call it freely but execution is paused until a
- * human approves via the chat UI.
- *
- * The execute body is a stub - it logs the would-be email to the
- * server console (via `logUtils.logger`) and returns success. Swap
- * in a real SMTP / SES / Resend / Workspace Mail call later by
- * editing the `execute` body; the tool surface and approval gate
- * stay the same.
- *
- * Approval flow (Mastra + AI SDK V5):
- *
- * 1. Model calls the tool with `{ to, subject, body, ... }`.
- * 2. Mastra evaluates `requireApproval` (here always `true`),
- *    pauses the agent loop, and emits a `tool-call-approval`
- *    chunk on the response stream.
- * 3. The chat client renders an approve/deny prompt against the
- *    `state: 'approval-requested'` tool part. On approve, it sends
- *    a `MastraToolApproval` response back; on deny, the tool call
- *    is rejected and the model sees an error.
- * 4. On approve, this `execute` runs and logs the email.
- *
- * The tool is intentionally NOT auto-installed on every agent -
- * email is domain-specific, not infrastructure. Spread it into the
- * specific agents that should be able to draft emails.
- */
-
-import { logUtils, stringUtils } from "@dbx-tools/shared";
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-const log = logUtils.logger("mastra/tool/send-email");
-
-const emailInputSchema = z.object({
-  to: z.string().describe(
-    stringUtils.toDescription(`
-    Single recipient email address (e.g. "alice@example.com"). For
-    multiple recipients, comma-separate them yourself.
-  `),
-  ),
-  subject: z.string().describe(
-    stringUtils.toDescription(`
-    Subject line.
-  `),
-  ),
-  body: z.string().describe(
-    stringUtils.toDescription(`
-    Email body. Plain text or markdown; the renderer downstream decides
-    which to honour. Be specific - the recipient may not have any
-    context the model has from prior chat turns.
-  `),
-  ),
-  cc: z
-    .array(z.string())
-    .optional()
-    .describe(
-      stringUtils.toDescription(`
-      Optional CC recipients.
-    `),
-    ),
-  bcc: z
-    .array(z.string())
-    .optional()
-    .describe(
-      stringUtils.toDescription(`
-      Optional BCC recipients.
-    `),
-    ),
-});
-
-const emailOutputSchema = z.object({
-  sent: z.boolean().describe(
-    stringUtils.toDescription(`
-    True when the email was dispatched. The current implementation
-    always returns true after console-logging the would-be email; swap
-    in a real provider to make this meaningful.
-  `),
-  ),
-  recipient: z.string().describe(
-    stringUtils.toDescription(`
-    Echo of the \`to\` field for confirmation.
-  `),
-  ),
-});
-
-/** Options accepted by {@link buildEmailTool}. */
-export interface BuildEmailToolOptions {
-  /**
-   * Override the tool id. Defaults to `"send_email"`. Useful if a
-   * caller wants `send_internal_email` / `send_external_email`
-   * variants.
-   */
-  id?: string;
-  /**
-   * Replace the default execute body with a real provider call.
-   * Receives the validated input and must return `{sent, recipient}`.
-   * The console-log default is meant for demos / dev; production
-   * deployments should wire SMTP / SES / Resend / Workspace Mail
-   * here.
-   */
-  send?: (input: z.infer<typeof emailInputSchema>) => Promise<void> | void;
-}
-
-/**
- * Build the `send_email` tool. Approval-gated by default; the
- * execute body either calls the supplied {@link send} hook or
- * logs the email to the server console as a demo stub.
- *
- * @example
- * ```ts
- * import { buildEmailTool, createAgent, mastra } from "@dbx-tools/appkit-mastra";
- *
- * const support = createAgent({
- *   instructions: "...",
- *   tools(plugins) {
- *     return {
- *       ...(plugins.genie?.toolkit() ?? {}),
- *       send_email: buildEmailTool(),
- *     };
- *   },
- * });
- * ```
- */
-export function buildEmailTool(opts: BuildEmailToolOptions = {}) {
-  return createTool({
-    id: opts.id ?? "send_email",
-    description: stringUtils.toDescription(`
-      Send an email on the user's behalf. Pass a recipient address,
-      subject, and body; the user will be prompted to approve the send
-      before it goes out (the tool is approval-gated). Use this when
-      the user explicitly asks to send / forward / share something via
-      email - never autonomously. Keep subjects short and bodies
-      focused; the recipient may not have any of the chat context.
-    `),
-    inputSchema: emailInputSchema,
-    outputSchema: emailOutputSchema,
-    requireApproval: true,
-    execute: async (input) => {
-      const { to, subject, body, cc, bcc } = input as z.infer<typeof emailInputSchema>;
-      // Default behaviour: dump the email to the server console so
-      // demos can see the gate fire end-to-end without a real
-      // provider. Replace by passing `opts.send`.
-      log.info("send", {
-        to,
-        ...(cc && cc.length > 0 ? { cc } : {}),
-        ...(bcc && bcc.length > 0 ? { bcc } : {}),
-        subject,
-        bodyLength: body.length,
-        body,
-      });
-      if (opts.send) {
-        await opts.send(input as z.infer<typeof emailInputSchema>);
-      }
-      return { sent: true, recipient: to };
-    },
-  });
-}