@dbx-tools/appkit-mastra 0.3.20 → 0.3.22

package/README.md

@@ -251,6 +251,25 @@ Agents can return `[chart:<id>]` and `[data:<statement_id>]` markers in prose.
 The embed route resolves them later, which avoids forcing the language model to
 inline large tables or wait for chart planning before continuing its answer.
 
+### Brand The Charts
+
+Pass a `brand` to the plugin to theme every generated chart with your brand's
+palette and font; omit it for the default Echarts look.
+
+```ts
+import { brand } from "@dbx-tools/shared-core";
+
+plugin.mastra({ agents, storage: true, brand: brand.defaultBrandContext });
+```
+
+`brand` is the portable `BrandContext` shared across the UI, email, and
+libraries, so charts, email, and the chat UI theme from one source. The chart
+planner derives an Echarts theme from it: a series color cycle seeded from
+`colors.primary` / `colors.accent` (plus a colorblind-friendly spread so
+many-series charts stay legible) and a base text style from `typography.sans` /
+`colors.foreground`. Charts render to canvas, so this is applied server-side on
+the Echarts option rather than through the browser `[data-brand]` CSS bridge.
+
 ## Model Selection
 
 `model.buildModel()` adapts the generic resolver from

package/package.json

@@ -28,22 +28,22 @@
     "express": "^5.1.0",
     "pg": "^8.22.0",
     "zod": "^4.3.6",
-    "@dbx-tools/appkit": "0.3.20",
-    "@dbx-tools/core": "0.3.20",
-    "@dbx-tools/databricks": "0.3.20",
-    "@dbx-tools/model": "0.3.20",
-    "@dbx-tools/shared-core": "0.3.20",
-    "@dbx-tools/genie": "0.3.20",
-    "@dbx-tools/shared-genie": "0.3.20",
-    "@dbx-tools/shared-mastra": "0.3.20",
-    "@dbx-tools/shared-model": "0.3.20"
+    "@dbx-tools/appkit": "0.3.22",
+    "@dbx-tools/databricks": "0.3.22",
+    "@dbx-tools/genie": "0.3.22",
+    "@dbx-tools/model": "0.3.22",
+    "@dbx-tools/shared-core": "0.3.22",
+    "@dbx-tools/shared-mastra": "0.3.22",
+    "@dbx-tools/shared-genie": "0.3.22",
+    "@dbx-tools/core": "0.3.22",
+    "@dbx-tools/shared-model": "0.3.22"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.20",
+  "version": "0.3.22",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/chart.ts

@@ -37,7 +37,7 @@ import { z } from "zod";
 import type { MastraPluginConfig } from "./config";
 import { buildModel } from "./model";
 import { model } from "@dbx-tools/shared-model";
-import { async, error, hash, log, string } from "@dbx-tools/shared-core";
+import { async, error, hash, log, string, type BrandContext } from "@dbx-tools/shared-core";
 
 const logger = log.logger("mastra/chart");
 
@@ -353,7 +353,7 @@ async function runChartPlanner(
     ...(abortSignal ? { abortSignal } : {}),
   });
   const plan = chartPlanSchema.parse(result.object);
-  const option = planToEchartsOption(plan, title);
+  const option = planToEchartsOption(plan, title, config.brand);
   return { chartType: plan.chartType, option };
 }
 
@@ -551,6 +551,50 @@ export async function fetchChart(
   }
 }
 
+/* ----------------------------- echarts theme ----------------------------- */
+
+/**
+ * The slice of an Echarts option that carries brand identity: the series
+ * color cycle and the base text style (font family + foreground color).
+ * Derived from a {@link BrandContext} by {@link brandChartTheme} and merged
+ * into every spec by {@link planToEchartsOption}.
+ */
+interface ChartTheme {
+  color: string[];
+  textStyle: { fontFamily: string; color: string };
+}
+
+/**
+ * Expand two brand hex colors into a legible categorical cycle. Echarts
+ * repeats the `color` array across series / categories, so a good default
+ * needs several distinct hues, not two. We seed with the brand primary and
+ * accent (the identity colors) and follow with a fixed, colorblind-friendly
+ * spread so multi-series / many-slice charts stay readable while the first
+ * one or two marks still land on-brand.
+ */
+function brandColorCycle(primary: string, accent: string): string[] {
+  const spread = ["#5B8FF9", "#F6BD16", "#E86452", "#6DC8EC", "#945FB9", "#FF9845", "#1E9493"];
+  const seen = new Set<string>();
+  return [primary, accent, ...spread].filter((c) => {
+    const key = c.toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Derive an Echarts {@link ChartTheme} from a brand context: the primary +
+ * accent colors seed the series cycle, the sans stack becomes the base font,
+ * and the brand foreground becomes the base text color.
+ */
+function brandChartTheme(brand: BrandContext): ChartTheme {
+  return {
+    color: brandColorCycle(brand.colors.primary, brand.colors.accent),
+    textStyle: { fontFamily: brand.typography.sans, color: brand.colors.foreground },
+  };
+}
+
 /* ----------------------------- echarts expansion ----------------------------- */
 
 /**
@@ -559,10 +603,21 @@ export async function fetchChart(
  * compact plan shape; tooltip / animation / color / grid defaults
  * stay consistent across charts and are easy to tune without
  * retraining model behaviour.
+ *
+ * When `brand` is set, the resolved spec is themed with the brand's series
+ * color cycle and base text style (see {@link brandChartTheme}); otherwise
+ * Echarts' defaults apply.
  */
-function planToEchartsOption(plan: ChartPlan, fallbackTitle: string): Record<string, unknown> {
+function planToEchartsOption(
+  plan: ChartPlan,
+  fallbackTitle: string,
+  brand?: BrandContext,
+): Record<string, unknown> {
   const baseTitle = plan.title ?? fallbackTitle;
   const grid = { left: 48, right: 24, top: 56, bottom: 48, containLabel: true };
+  const theme = brand ? brandChartTheme(brand) : undefined;
+  const themed = (option: Record<string, unknown>): Record<string, unknown> =>
+    theme ? { ...theme, ...option } : option;
 
   if (plan.chartType === "pie") {
     // Echarts crashes on null pie slices - filter them out.
@@ -573,7 +628,7 @@ function planToEchartsOption(plan: ChartPlan, fallbackTitle: string): Record<str
       (d): d is { name: string; value: number } =>
         d !== null && typeof d === "object" && !Array.isArray(d),
     );
-    return {
+    return themed({
       title: { text: baseTitle, left: "center" },
       tooltip: { trigger: "item" },
       legend: { bottom: 0 },
@@ -585,14 +640,14 @@ function planToEchartsOption(plan: ChartPlan, fallbackTitle: string): Record<str
           data: slices,
         },
       ],
-    };
+    });
   }
 
   if (plan.chartType === "scatter") {
     // Echarts crashes on null scatter points - keep only valid
     // `[x, y]` tuples. Bare numbers / objects / nulls from a
     // mismatched plan get dropped silently.
-    return {
+    return themed({
       title: { text: baseTitle, left: "center" },
       tooltip: { trigger: "item" },
       legend: { bottom: 0 },
@@ -604,13 +659,13 @@ function planToEchartsOption(plan: ChartPlan, fallbackTitle: string): Record<str
         type: "scatter",
         data: s.data.filter((d): d is [number, number] => Array.isArray(d) && d.length === 2),
       })),
-    };
+    });
   }
 
   // bar / line / area share the same axis layout.
   const isArea = plan.chartType === "area";
   const seriesType = plan.chartType === "bar" ? "bar" : "line";
-  return {
+  return themed({
     title: { text: baseTitle, left: "center" },
     tooltip: { trigger: "axis" },
     legend: { bottom: 0 },
@@ -628,7 +683,7 @@ function planToEchartsOption(plan: ChartPlan, fallbackTitle: string): Record<str
       smooth: seriesType === "line",
       ...(isArea ? { areaStyle: {} } : {}),
     })),
-  };
+  });
 }
 
 /* ----------------------------- render_data tool ----------------------------- */

package/src/config.ts

@@ -8,6 +8,7 @@
  */
 
 import type { BasePluginConfig } from "@databricks/appkit";
+import type { BrandContext } from "@dbx-tools/shared-core";
 import type { AgentConfig } from "@mastra/core/agent";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
@@ -442,4 +443,19 @@ export interface MastraPluginConfig extends BasePluginConfig {
    *   surface.
    */
   apiAccess?: "scoped" | "full";
+  /**
+   * Optional brand context applied to charts produced by the built-in
+   * `render_data` / `prepare_chart` tools. When set, the chart planner's
+   * Echarts output is themed with the brand's palette (series colors derived
+   * from `colors.primary` / `colors.accent`) and sans font
+   * (`typography.sans`) instead of Echarts' defaults. Omit for the default
+   * Echarts look.
+   *
+   * Pass the portable {@link BrandContext} shared across the UI and
+   * libraries (e.g. `brand.defaultBrandContext` from `@dbx-tools/shared-core`,
+   * or a customer brand) - the same object the email add-on and the UI
+   * `BrandProvider` consume, so a host themes charts, email, and UI from one
+   * source.
+   */
+  brand?: BrandContext;
 }

package/src/plugin.ts

@@ -51,11 +51,9 @@ import {
   type PluginManifest,
   type ResourceRequirement,
 } from "@databricks/appkit";
-import type { Agent } from "@mastra/core/agent";
-import { Mastra } from "@mastra/core/mastra";
-import express from "express";
-import type { Pool } from "pg";
-
+import { plugin } from "@dbx-tools/appkit";
+import { serving as nodeServing } from "@dbx-tools/model";
+import { error, log, string } from "@dbx-tools/shared-core";
 import {
   feedback,
   routes,
@@ -63,8 +61,12 @@ import {
   type MastraFeedbackRequest,
   type StatementData,
 } from "@dbx-tools/shared-mastra";
-import { serving as nodeServing } from "@dbx-tools/model";
 import { display, type ServingEndpointSummary } from "@dbx-tools/shared-model";
+import type { Agent } from "@mastra/core/agent";
+import { Mastra } from "@mastra/core/mastra";
+import express from "express";
+import type { Pool } from "pg";
+
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents";
 import { fetchChart } from "./chart";
 import type { MastraPluginConfig } from "./config";
@@ -78,8 +80,6 @@ import { attachRoutePatchMiddleware, isMastraRequestAllowed, MastraServer } from
 import { resolveServingConfig } from "./serving";
 import { fetchStatementData, STATEMENT_ROW_CAP } from "./statement";
 import { threadsRoute } from "./threads";
-import { error, log, string } from "@dbx-tools/shared-core";
-import { plugin } from "@dbx-tools/appkit";
 
 const GENIE_MANIFEST = plugin.data(genie).plugin.manifest;
 const LAKEBASE_MANIFEST = plugin.data(lakebase).plugin.manifest;
@@ -330,7 +330,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // Reads only in-memory build state, so it's synchronous and needs no OBO
     // scoping. Registered before the catch-all, same as `/models`.
     const handleDefaultModel = (req: express.Request, res: express.Response): void => {
-      const requested = string.firstNonEmpty(req.params["agentId"]);
+      const requested = string.firstNonEmpty(req.params.agentId);
       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.
@@ -378,14 +378,14 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // clean 404; thrown errors bubble through `next(err)`.
     const embedResolvers: Record<string, EmbedResolver> = {
       chart: (req, id, signal) => {
-        const timeoutMs = parseTimeoutMs(req.query["timeoutMs"]);
+        const timeoutMs = parseTimeoutMs(req.query.timeoutMs);
         return fetchChart(id, {
           ...(timeoutMs !== undefined ? { timeoutMs } : {}),
           signal,
         });
       },
       data: (req, id, signal) => {
-        const limit = parseStatementLimit(req.query["limit"]);
+        const limit = parseStatementLimit(req.query.limit);
         return this.userScopedSelf(req).fetchStatement(id, {
           ...(limit !== undefined ? { limit } : {}),
           signal,
@@ -394,8 +394,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     };
 
     router.get(`${routes.MASTRA_ROUTES.embed}/:type/:id`, (req, res, next) => {
-      const type = req.params["type"] ?? "";
-      const id = req.params["id"];
+      const type = req.params.type ?? "";
+      const id = req.params.id;
       const resolve = embedResolvers[type];
       if (!resolve) {
         res.status(404).json({ error: `unsupported embed type: ${type}` });

package/src/server.ts

@@ -7,7 +7,9 @@
  * @module
  */
 
+import { randomUUID } from "node:crypto";
 import { getExecutionContext } from "@databricks/appkit";
+import { http, log, object, string, token } from "@dbx-tools/shared-core";
 import { feedback, thread } from "@dbx-tools/shared-mastra";
 import {
   MASTRA_RESOURCE_ID_KEY,
@@ -17,9 +19,6 @@ import {
 import { MastraServer as MastraServerExpress } from "@mastra/express";
 import { trace } from "@opentelemetry/api";
 import type express from "express";
-import { randomUUID } from "node:crypto";
-
-import { resolveFeedbackEnabled } from "./mlflow";
 
 import {
   MASTRA_REQUEST_ID_KEY,
@@ -30,7 +29,8 @@ import {
   type MastraPluginConfig,
   type User,
 } from "./config";
-import { http, log, object, string, token } from "@dbx-tools/shared-core";
+import { resolveFeedbackEnabled } from "./mlflow";
+
 import { extractModelOverride, MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig } from "./serving";
 /**
  * OpenTelemetry's sentinel for "no valid trace" - 32 zero hex chars.
@@ -154,10 +154,7 @@ export class MastraServer extends MastraServerExpress {
   configureRequestContextScopes(req: express.Request, requestContext: RequestContext) {
     const scopes = [
       ...object
-        .sequence(
-          token.getAccessTokenScopes(req),
-          token.getAccessTokenScopes(req, "authorization"),
-        )
+        .sequence(token.getAccessTokenScopes(req), token.getAccessTokenScopes(req, "authorization"))
         .distinct(),
     ];
     requestContext.set(MASTRA_SCOPES_KEY, scopes);

package/src/serving-sanitize.ts

@@ -1,4 +1,5 @@
 import { string } from "@dbx-tools/shared-core";
+import { type ChatMessage, type ChatRole, openaiChat } from "@dbx-tools/shared-model";
 /**
  * Repairs Mastra / AI SDK message replays sent to Databricks Model
  * Serving before they hit the OpenAI-compatible `/chat/completions`
@@ -6,43 +7,46 @@ import { string } from "@dbx-tools/shared-core";
  */
 
 /**
- * OpenAI-flavoured chat message shape we need to mutate. We do not
- * import the OpenAI / AI SDK types because both packages keep these
- * fields under internal namespaces; the wire payload is the contract
- * here and it's stable enough to inline.
+ * A chat message as it arrives on the serving wire, plus the extended-thinking
+ * fields Databricks-hosted Claude adds. The OpenAI-standard part of the shape
+ * is {@link ChatMessage} from `@dbx-tools/shared-model`; only the provider
+ * extensions this module strips are declared here.
  */
-export interface ServingChatMessage {
-  role: "system" | "user" | "assistant" | "tool" | "reasoning";
-  content?: string | ServingContentPart[];
-  tool_calls?: Array<{ id: string; type: string; function: unknown }>;
-  tool_call_id?: string;
+export interface ServingChatMessage extends ChatMessage {
+  /** Narrowed to the roles this repair pass reasons about, plus Claude's `reasoning` turn. */
+  role: ChatRole | "reasoning";
   reasoning?: unknown;
   reasoning_content?: unknown;
 }
 
-type ServingContentPart = {
-  type?: string;
-  text?: string;
-  [key: string]: unknown;
-};
-
 const REASONING_PART_TYPES = new Set(["reasoning", "thinking", "redacted_thinking"]);
 
 /**
  * Parse, sanitize, and re-serialize a `/serving-endpoints/...` POST
  * body. Returns the original string verbatim when the body is not
- * JSON, has no `messages`, or no rewrite was needed.
+ * JSON or no rewrite was needed.
  */
 export function rewriteServingBody(body: string): string {
-  let parsed: { messages?: unknown };
+  let parsed: Record<string, unknown>;
   try {
-    parsed = JSON.parse(body);
+    parsed = JSON.parse(body) as Record<string, unknown>;
   } catch {
     return body;
   }
-  if (!Array.isArray(parsed.messages)) return body;
-  const messages = parsed.messages as ServingChatMessage[];
-  const changed = stripReasoningFromServingMessages(messages) || repairAssistantPrefill(messages);
+
+  // Runs regardless of `messages`: Databricks refuses to parse a body carrying
+  // an unknown top-level field, so this failure is not specific to a transcript.
+  let changed = openaiChat.stripUnsupportedChatFields(parsed).length > 0;
+
+  if (Array.isArray(parsed.messages)) {
+    const messages = parsed.messages as ServingChatMessage[];
+    // Evaluated eagerly, not short-circuited: one transcript can need both
+    // reasoning blocks stripped AND a trailing assistant prefill folded back.
+    const stripped = stripReasoningFromServingMessages(messages);
+    const repaired = repairAssistantPrefill(messages);
+    changed = changed || stripped || repaired;
+  }
+
   return changed ? JSON.stringify(parsed) : body;
 }
 
@@ -145,15 +149,19 @@ export function repairAssistantPrefill(messages: ServingChatMessage[]): boolean
   return true;
 }
 
+/**
+ * Flatten content to the prose a human would read: text parts only, separated
+ * by blank lines, since the result is spliced into another turn's message body.
+ */
 function textFromServingContent(content: ServingChatMessage["content"]): string {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .filter((part) => part?.type === "text" && typeof part.text === "string")
-    .map((part) => part.text as string)
-    .join("\n\n");
+  return openaiChat.chatContentToText(content, { separator: "\n\n", types: ["text"] });
 }
 
+/**
+ * Whether a turn carries nothing worth replaying. Deliberately stricter than
+ * "has no text": a part of any other type (an image, a cache marker) counts as
+ * content, so a message holding one is kept even though it has no prose.
+ */
 function isEmptyServingContent(content: ServingChatMessage["content"]): boolean {
   if (content === undefined) return true;
   if (typeof content === "string") return content.trim().length === 0;