@dbx-tools/appkit-mastra 0.1.3 → 0.1.5

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/src/agents.d.ts

@@ -284,7 +284,7 @@ export declare const FALLBACK_AGENT_ID = "default";
  * Override globally via {@link MastraPluginConfig.styleInstructions}
  * (pass `false` to disable entirely, or a string to replace).
  */
-export declare const DEFAULT_STYLE_INSTRUCTIONS = "Output style:\n\n- Plain prose. Use hyphens (-) only. Never use em dashes (\u2014) or en dashes (\u2013).\n- Never use emojis.\n- Skip openers like \"Great question\", \"Absolutely\", \"I'd be happy to help\".\n- Skip closers like \"Let me know if you have any questions\".\n- Skip self-disclaimers (\"I should mention\", \"It's important to note\").\n- Answer directly. No preamble before the actual answer.\n- Use lists and headers only when they clarify a multi-part answer; not for short replies.\n- Quote numbers, code, identifiers, and tool output verbatim. Never paraphrase them.";
+export declare const DEFAULT_STYLE_INSTRUCTIONS: string;
 /**
  * Resolve every entry in `config.agents` into a Mastra `Agent`
  * instance. When `config.agents` is omitted the plugin registers a

package/dist/src/agents.js

@@ -16,6 +16,7 @@ import { genie } from "@databricks/appkit";
 import { logUtils, pluginUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
+import { buildRenderDataTool } from "./chart.js";
 import { buildGenieProvider } from "./genie.js";
 import { buildModel } from "./model.js";
 /** Re-export of Mastra's native `createTool` for full-feature access. */
@@ -110,16 +111,21 @@ Rules:
  * Override globally via {@link MastraPluginConfig.styleInstructions}
  * (pass `false` to disable entirely, or a string to replace).
  */
-export const DEFAULT_STYLE_INSTRUCTIONS = `Output style:
-
-- Plain prose. Use hyphens (-) only. Never use em dashes (—) or en dashes (–).
-- Never use emojis.
-- Skip openers like "Great question", "Absolutely", "I'd be happy to help".
-- Skip closers like "Let me know if you have any questions".
-- Skip self-disclaimers ("I should mention", "It's important to note").
-- Answer directly. No preamble before the actual answer.
-- Use lists and headers only when they clarify a multi-part answer; not for short replies.
-- Quote numbers, code, identifiers, and tool output verbatim. Never paraphrase them.`;
+export const DEFAULT_STYLE_INSTRUCTIONS = [
+    "Output style:",
+    "",
+    "Use markdown formatting, including headings, lists, and code blocks.",
+    "Avoid lists and headers for short replies.",
+    "Plain prose.",
+    "Use hyphens (-) only. Never use em dashes or en dashes.",
+    "Never use emojis.",
+    "Skip openers like 'Great question', 'Absolutely', and 'I'd be happy to help'.",
+    "Skip closers like 'Let me know if you have any questions'.",
+    "Skip self-disclaimers like 'I should mention' and 'It's important to note'.",
+    "Answer directly.",
+    "Do not include a preamble before the actual answer.",
+    "Use lists and headers only when they clarify a multi-part answer.",
+].join("\n");
 /**
  * Resolve the style block to append to every agent's instructions.
  * Returns `null` when the caller opted out (`styleInstructions: false`).
@@ -160,7 +166,15 @@ export async function buildAgents(opts) {
     const ids = Object.keys(definitions);
     const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
     const plugins = buildPluginsMap(context);
-    const ambientTools = config.tools ?? {};
+    // System-default ambient tools every agent gets out of the box.
+    // Currently just `render_data` for inline visualizations; the
+    // user can shadow it by including a same-named tool in their own
+    // `config.tools` or per-agent `tools`. Order in {@link resolveTools}
+    // is `system -> user-ambient -> per-agent`, last write wins.
+    const systemTools = {
+        render_data: buildRenderDataTool(config),
+    };
+    const ambientTools = { ...systemTools, ...(config.tools ?? {}) };
     const style = resolveStyleInstructions(config);
     const agents = {};
     for (const [id, def] of Object.entries(definitions)) {

package/dist/src/chart.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Chart-rendering primitives.
+ *
+ * Two surfaces, one shared brain:
+ *
+ * - {@link buildRenderDataTool}: a Mastra tool the model calls
+ *   ("here is a dataset, render it as a chart"). The tool is
+ *   fire-and-forget by design - it generates a short `chartId`,
+ *   pushes a single `kind: "chart"` event onto `ctx.writer` carrying
+ *   the raw rows, and returns the id to the model immediately. No
+ *   chart planning happens inside the agentic loop, so the model
+ *   never blocks on a downstream LLM call to get its identifier.
+ *
+ * - {@link runChartPlanner}: the chart-planner Agent + ECOption
+ *   expansion as a plain async function. The HTTP route in
+ *   {@link ./render-chart-route.ts} calls this when the client
+ *   POSTs the dataset back; the result is an `EChartsOption` JSON
+ *   the React `<ChartSlot>` renders inline. Decoupling the planner
+ *   from the tool means the planning latency lives entirely
+ *   client-side: the model can finish writing its report while
+ *   the client is still rendering the charts.
+ *
+ * The model wires the chart into its reply by emitting the marker
+ * `[[chart:<chartId>]]` on its own line in markdown. The chat
+ * client splits the assistant text on these markers and drops a
+ * `<ChartSlot>` in at the position the model placed it; the slot
+ * then fires the render-chart endpoint on mount and shows a
+ * skeleton until the option lands.
+ */
+import type { RequestContext } from "@mastra/core/request-context";
+import { z } from "zod";
+import type { MastraPluginConfig } from "./config.js";
+/**
+ * Compact, model-friendly representation of an Echarts spec. The
+ * planner agent emits this; {@link planToEchartsOption} expands it
+ * into a real `EChartsOption` JSON. Two layers because letting the
+ * model fill in a fully-typed `EChartsOption` is brittle (hundreds
+ * of optional fields, deep unions, version-dependent shapes). A
+ * small "chart plan" schema is much more reliable for a fast model
+ * and keeps animation / tooltip / styling defaults consistent
+ * across charts.
+ */
+declare const chartPlanSchema: z.ZodObject<{
+    chartType: z.ZodEnum<{
+        bar: "bar";
+        line: "line";
+        area: "area";
+        scatter: "scatter";
+        pie: "pie";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    xAxisLabel: z.ZodOptional<z.ZodString>;
+    yAxisLabel: z.ZodOptional<z.ZodString>;
+    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    series: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        data: z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodNumber;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ChartPlan = z.infer<typeof chartPlanSchema>;
+/** Inputs to {@link runChartPlanner}. */
+export interface RunChartPlannerOptions {
+    config: MastraPluginConfig;
+    requestContext?: RequestContext;
+    title: string;
+    description?: string;
+    data: ReadonlyArray<Record<string, unknown>>;
+}
+/** Output of {@link runChartPlanner}: a fully-formed Echarts spec. */
+export interface RunChartPlannerResult {
+    option: Record<string, unknown>;
+    chartType: ChartPlan["chartType"];
+}
+/**
+ * Run the chart planner against the given dataset and return a
+ * full Echarts `EChartsOption` JSON. Used by the HTTP route the
+ * client hits when it sees a `[[chart:<chartId>]]` marker; the
+ * tool itself does not call this so the model never blocks on
+ * planning latency.
+ */
+export declare function runChartPlanner(opts: RunChartPlannerOptions): Promise<RunChartPlannerResult>;
+/**
+ * Build the `render_data` tool bound to the given plugin config.
+ *
+ * Fire-and-forget by design: the tool returns immediately with a
+ * short `chartId` and emits a single `kind: "chart"` event over
+ * `ctx.writer` carrying the raw dataset for the client. The
+ * client's chart slot then POSTs the data to
+ * `/route/render-chart` to get an `EChartsOption` back from the
+ * planner agent. This keeps the calling LLM unblocked - it can
+ * write the report referencing the chart by id while the client
+ * is still rendering it.
+ */
+export declare function buildRenderDataTool(_config: MastraPluginConfig): import("@mastra/core/tools").Tool<{
+    title: string;
+    data: Record<string, unknown>[];
+    description?: string | undefined;
+}, {
+    chartId: string;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;
+export {};

package/dist/src/chart.js

@@ -0,0 +1,375 @@
+/**
+ * Chart-rendering primitives.
+ *
+ * Two surfaces, one shared brain:
+ *
+ * - {@link buildRenderDataTool}: a Mastra tool the model calls
+ *   ("here is a dataset, render it as a chart"). The tool is
+ *   fire-and-forget by design - it generates a short `chartId`,
+ *   pushes a single `kind: "chart"` event onto `ctx.writer` carrying
+ *   the raw rows, and returns the id to the model immediately. No
+ *   chart planning happens inside the agentic loop, so the model
+ *   never blocks on a downstream LLM call to get its identifier.
+ *
+ * - {@link runChartPlanner}: the chart-planner Agent + ECOption
+ *   expansion as a plain async function. The HTTP route in
+ *   {@link ./render-chart-route.ts} calls this when the client
+ *   POSTs the dataset back; the result is an `EChartsOption` JSON
+ *   the React `<ChartSlot>` renders inline. Decoupling the planner
+ *   from the tool means the planning latency lives entirely
+ *   client-side: the model can finish writing its report while
+ *   the client is still rendering the charts.
+ *
+ * The model wires the chart into its reply by emitting the marker
+ * `[[chart:<chartId>]]` on its own line in markdown. The chat
+ * client splits the assistant text on these markers and drops a
+ * `<ChartSlot>` in at the position the model placed it; the slot
+ * then fires the render-chart endpoint on mount and shows a
+ * skeleton until the option lands.
+ */
+import { randomUUID } from "node:crypto";
+import { stringUtils } from "@dbx-tools/appkit-shared";
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { ModelTier, modelForTier, buildModel } from "./model.js";
+/**
+ * Compact, model-friendly representation of an Echarts spec. The
+ * planner agent emits this; {@link planToEchartsOption} expands it
+ * into a real `EChartsOption` JSON. Two layers because letting the
+ * model fill in a fully-typed `EChartsOption` is brittle (hundreds
+ * of optional fields, deep unions, version-dependent shapes). A
+ * small "chart plan" schema is much more reliable for a fast model
+ * and keeps animation / tooltip / styling defaults consistent
+ * across charts.
+ */
+const chartPlanSchema = z.object({
+    chartType: z
+        .enum(["bar", "line", "area", "scatter", "pie"])
+        .describe(stringUtils.toDescription `
+      The chart shape that best matches the data and intent. Use
+      \`bar\` for category-vs-value comparisons, \`line\` for
+      trends over an ordered axis, \`area\` for stacked-trend
+      emphasis, \`scatter\` for two-numeric-axis correlations,
+      \`pie\` for parts-of-a-whole when categories are few.
+    `),
+    title: z.string().optional().describe(stringUtils.toDescription `
+    Short title shown above the chart. Optional; defaults to the
+    \`title\` argument the caller passed in.
+  `),
+    xAxisLabel: z.string().optional().describe(stringUtils.toDescription `
+    Axis label below the chart. Used for bar / line / area /
+    scatter; ignored for pie.
+  `),
+    yAxisLabel: z.string().optional().describe(stringUtils.toDescription `
+    Axis label to the left of the chart. Used for bar / line /
+    area / scatter; ignored for pie.
+  `),
+    categories: z
+        .array(z.string())
+        .optional()
+        .describe(stringUtils.toDescription `
+      X-axis category labels for \`bar\` / \`line\` / \`area\`
+      charts (one per data point in each series). Omit for
+      \`scatter\` (uses [x, y] tuples) and \`pie\` (each slice
+      carries its own \`name\`).
+    `),
+    series: z
+        .array(z.object({
+        name: z.string().describe(stringUtils.toDescription `
+          Legend name for this series.
+        `),
+        data: z
+            .array(z.union([
+            z.number(),
+            z.tuple([z.number(), z.number()]),
+            z.object({
+                name: z.string(),
+                value: z.number(),
+            }),
+        ]))
+            .describe(stringUtils.toDescription `
+            Data points. For \`bar\` / \`line\` / \`area\`, an
+            array of numbers aligned to \`categories\`. For
+            \`scatter\`, an array of \`[x, y]\` numeric tuples.
+            For \`pie\`, an array of \`{name, value}\` objects.
+          `),
+    }))
+        .min(1)
+        .describe(stringUtils.toDescription `
+      One or more series to plot. Pie charts use exactly one
+      series; bar/line/area can stack multiple series sharing
+      the same \`categories\` axis.
+    `),
+});
+/**
+ * System prompt for the inner chart-planning agent. Tuned for a
+ * fast-tier model (Haiku, GPT-5-mini, Gemini Flash Lite).
+ */
+const CHART_PLANNER_INSTRUCTIONS = stringUtils.toDescription `
+  You design Apache Echarts visualizations. The user gives you a
+  tabular dataset (rows of objects) plus a title and an optional
+  description of the intent. You produce a small chart plan
+  (chart type, axis labels, categories, series) that best
+  conveys the data.
+
+  Decision guide:
+
+  - bar: comparing a numeric value across a small/medium set of
+    discrete categories (top-N, ranking, group-by).
+  - line: ordered-axis trend (time series, sequence).
+  - area: same as line but emphasises magnitude or stacked
+    composition.
+  - scatter: two numeric axes, correlation between fields.
+  - pie: parts of a whole when 2-7 categories sum to a
+    meaningful total.
+
+  When in doubt between bar and line, prefer bar for unordered
+  categories and line for ordered ones (dates, time buckets,
+  ranks). Never pick pie for more than 7 slices.
+
+  For bar / line / area: pick one column as the category axis
+  (usually the only string-valued column) and one or more
+  numeric columns as series. Sort categories by the primary
+  series value descending unless the data is naturally ordered
+  (dates, ranks).
+
+  For pie: pick the category column for slice names and one
+  numeric column for slice values. Emit a single series.
+
+  For scatter: pick two numeric columns and emit \`[x, y]\`
+  tuples in a single series.
+
+  Keep series names human-readable (use the column name; title
+  case it lightly if needed). Keep titles concise; do not
+  repeat the user's title in xAxisLabel / yAxisLabel.
+`;
+/**
+ * Lazily-constructed inner agent shared across all calls in this
+ * process. The agent is stateless (no memory, no tools) so a
+ * single instance per plugin config is safe; model resolution
+ * still happens per-call against the live `requestContext`, so
+ * OBO auth stays user-scoped.
+ */
+function createChartPlannerAgent(config) {
+    return new Agent({
+        id: "render_chart_planner",
+        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),
+        }),
+    });
+}
+/**
+ * Module-level cache: one chart-planner agent per plugin config
+ * instance. Keyed on the config object identity since each plugin
+ * mount provides its own resolver / fallbacks. Re-used across
+ * tool invocations and the render-chart HTTP route.
+ */
+const _plannerByConfig = new WeakMap();
+function getPlannerAgent(config) {
+    let agent = _plannerByConfig.get(config);
+    if (!agent) {
+        agent = createChartPlannerAgent(config);
+        _plannerByConfig.set(config, agent);
+    }
+    return agent;
+}
+/**
+ * Run the chart planner against the given dataset and return a
+ * full Echarts `EChartsOption` JSON. Used by the HTTP route the
+ * client hits when it sees a `[[chart:<chartId>]]` marker; the
+ * tool itself does not call this so the model never blocks on
+ * planning latency.
+ */
+export async function runChartPlanner(opts) {
+    const { config, requestContext, title, description, data } = opts;
+    const planner = getPlannerAgent(config);
+    const prompt = [
+        `Title: ${title}`,
+        description ? `Intent: ${description}` : null,
+        "",
+        "Dataset (JSON, one row per object):",
+        "```json",
+        JSON.stringify(data, null, 2),
+        "```",
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    const result = await planner.generate(prompt, {
+        structuredOutput: { schema: chartPlanSchema },
+        ...(requestContext ? { requestContext } : {}),
+    });
+    const plan = result.object;
+    const option = planToEchartsOption(plan, title);
+    return { option, chartType: plan.chartType };
+}
+const renderDataInputSchema = z.object({
+    title: z.string().describe(stringUtils.toDescription `
+    Title shown above the rendered chart. Use a concise
+    sentence-case label (e.g. "Top 10 SKUs by On-Hand Units").
+  `),
+    description: z.string().optional().describe(stringUtils.toDescription `
+    Optional one-line intent describing what insight the chart
+    should convey (e.g. "highlight the steep drop-off after
+    position 5", "compare quarterly revenue across regions").
+    The chart-planner reads this when picking the chart type and
+    axis encodings; the user does not see it directly.
+  `),
+    data: z
+        .array(z.record(z.string(), z.unknown()))
+        .min(1)
+        .describe(stringUtils.toDescription `
+      Tabular dataset to chart. One object per row, keyed by
+      column name. Values may be strings, numbers, booleans, or
+      null. The chart-planner decides which columns are
+      categories vs. numeric series. Cap at a few hundred rows
+      for legibility; sample / aggregate larger datasets first.
+    `),
+});
+const renderDataOutputSchema = z.object({
+    chartId: z.string().describe(stringUtils.toDescription `
+    Identifier of the queued chart. The tool returned
+    immediately - actual chart planning happens client-side
+    asynchronously. To position the chart in your reply, embed
+    the marker \`[[chart:<chartId>]]\` on its own line (with
+    blank lines above and below) where the chart should appear.
+    The client renders a skeleton there until the chart is
+    ready, then swaps in the visualization in place. You can
+    keep writing prose around the marker; the agent does not
+    need to wait for the chart to render.
+  `),
+});
+/**
+ * Build the `render_data` tool bound to the given plugin config.
+ *
+ * Fire-and-forget by design: the tool returns immediately with a
+ * short `chartId` and emits a single `kind: "chart"` event over
+ * `ctx.writer` carrying the raw dataset for the client. The
+ * client's chart slot then POSTs the data to
+ * `/route/render-chart` to get an `EChartsOption` back from the
+ * planner agent. This keeps the calling LLM unblocked - it can
+ * write the report referencing the chart by id while the client
+ * is still rendering it.
+ */
+export function buildRenderDataTool(_config) {
+    return createTool({
+        id: "render_data",
+        description: stringUtils.toDescription `
+      Submit a tabular dataset for inline rendering as a chart in
+      the user's view. Pass a title, the raw rows (array of
+      objects keyed by column name), and an optional one-line
+      description of the insight to highlight. Returns a short
+      \`chartId\` immediately - chart planning happens
+      asynchronously in the client, not in this turn, so the tool
+      does not block your prose.
+
+      Placement contract: embed \`[[chart:<chartId>]]\` on its own
+      line (blank lines above and below) wherever you want the
+      chart to appear in your reply. The client shows a skeleton
+      at that spot until the chart is ready, then swaps in the
+      rendered Echarts visualization. You can call
+      \`render_data\` multiple times in the same turn (the tool
+      is parallel-safe) and interleave the markers with prose so
+      each chart sits next to its commentary. A chart whose
+      marker is omitted falls through to the end of your reply
+      as a fallback - safe but less polished.
+
+      Use whenever a SQL row set, API response, or hand-built
+      dataset would land better as a picture than as a list or
+      table. Cap input at a few hundred rows; sample or
+      aggregate larger datasets first.
+    `,
+        inputSchema: renderDataInputSchema,
+        outputSchema: renderDataOutputSchema,
+        execute: async (input, ctx) => {
+            const { title, description, data } = input;
+            // Short, marker-friendly id. The LLM has to type this
+            // verbatim into the `[[chart:<id>]]` marker; an 8-hex-char
+            // prefix is unique within a single assistant turn (collision
+            // odds ~1 in 4 billion) and much less error-prone for the
+            // model to reproduce.
+            const chartId = randomUUID().replace(/-/g, "").slice(0, 8);
+            const writer = ctx
+                ?.writer;
+            try {
+                await writer?.write({
+                    kind: "chart",
+                    chartId,
+                    title,
+                    ...(description ? { description } : {}),
+                    data,
+                });
+            }
+            catch {
+                // Ignore: the parent stream may have closed downstream.
+            }
+            return { chartId };
+        },
+    });
+}
+/**
+ * Expand a {@link ChartPlan} into a full Echarts `EChartsOption`
+ * JSON. Centralized here so the planner agent only fills in the
+ * compact plan shape; tooltip / animation / color / grid defaults
+ * stay consistent across charts and are easy to tune without
+ * retraining model behaviour.
+ */
+function planToEchartsOption(plan, fallbackTitle) {
+    const baseTitle = plan.title ?? fallbackTitle;
+    const grid = { left: 48, right: 24, top: 56, bottom: 48, containLabel: true };
+    if (plan.chartType === "pie") {
+        return {
+            title: { text: baseTitle, left: "center" },
+            tooltip: { trigger: "item" },
+            legend: { bottom: 0 },
+            series: [
+                {
+                    name: plan.series[0]?.name ?? baseTitle,
+                    type: "pie",
+                    radius: ["35%", "65%"],
+                    data: plan.series[0]?.data ?? [],
+                },
+            ],
+        };
+    }
+    if (plan.chartType === "scatter") {
+        return {
+            title: { text: baseTitle, left: "center" },
+            tooltip: { trigger: "item" },
+            legend: { bottom: 0 },
+            grid,
+            xAxis: { type: "value", name: plan.xAxisLabel },
+            yAxis: { type: "value", name: plan.yAxisLabel },
+            series: plan.series.map((s) => ({
+                name: s.name,
+                type: "scatter",
+                data: s.data,
+            })),
+        };
+    }
+    // bar / line / area share the same axis layout.
+    const isArea = plan.chartType === "area";
+    const seriesType = plan.chartType === "bar" ? "bar" : "line";
+    return {
+        title: { text: baseTitle, left: "center" },
+        tooltip: { trigger: "axis" },
+        legend: { bottom: 0 },
+        grid,
+        xAxis: {
+            type: "category",
+            data: plan.categories ?? [],
+            name: plan.xAxisLabel,
+        },
+        yAxis: { type: "value", name: plan.yAxisLabel },
+        series: plan.series.map((s) => ({
+            name: s.name,
+            type: seriesType,
+            data: s.data,
+            smooth: seriesType === "line",
+            ...(isArea ? { areaStyle: {} } : {}),
+        })),
+    };
+}

package/dist/src/genie.d.ts

@@ -11,12 +11,13 @@
  * upstream change in `@databricks/appkit` flows in automatically.
  *
  * As Genie streams its long-running events (`FETCHING_METADATA` →
- * `ASKING_AI` → `EXECUTING_QUERY` → `COMPLETED`, plus SQL queries and
- * row data in `message_result.attachments` / `query_result`), the tool
- * forwards a normalised {@link GenieProgress} discriminated union out
- * through `ctx.writer` so the client can render incremental feedback
- * (status pill, SQL code block, row count) while the LLM still sees a
- * single clean final payload.
+ * `ASKING_AI` → `EXECUTING_QUERY` → `COMPLETED`, plus SQL text and
+ * follow-ups in `message_result.attachments`), the tool forwards a
+ * normalised {@link GenieProgress} discriminated union out through
+ * `ctx.writer` so the client can render an incremental loading pill.
+ * Row payloads from `query_result` are intentionally discarded - the
+ * LLM never sees rows, and charts come from the separate
+ * `render_data` tool when the model decides one is useful.
  */
 import { genie } from "@databricks/appkit";
 import { createTool } from "@mastra/core/tools";
@@ -33,10 +34,14 @@ export type GenieStreamEvent = ReturnType<GenieExports["sendMessage"]> extends A
 /** Conversation history returned by `genie.exports().getConversation`. */
 export type GenieConversation = Awaited<ReturnType<GenieExports["getConversation"]>>;
 /**
- * Normalised progress event surfaced to the UI as a Mastra `tool-output`
- * chunk. The discriminator (`kind`) keeps the union open for future
- * Genie features (charts, attachments, retries) without forcing the
- * client to know any Genie wire format.
+ * Normalised progress event surfaced to the UI as a Mastra
+ * `tool-output` chunk. Loading pill events (`started`, `status`,
+ * `sql`, `suggested`, `error`) are pure UI metadata and never reach
+ * the LLM. The `chart` variant carries the rows from a Genie SQL
+ * statement so the host UI's `<ChartSlot>` can render them inline
+ * via the same path as the `render_data` tool; the LLM still only
+ * sees the matching {@link datasetSchema} metadata in
+ * `genieAnswer`'s sibling `datasets[]` field.
  */
 export type GenieProgress = {
     kind: "started";
@@ -54,9 +59,11 @@ export type GenieProgress = {
     description?: string;
     statementId?: string;
 } | {
-    kind: "data";
-    rowCount: number;
-    columns: string[];
+    kind: "chart";
+    chartId: string;
+    title: string;
+    description?: string;
+    data: Array<Record<string, unknown>>;
 } | {
     kind: "text";
     content: string;