@dbx-tools/appkit-mastra 0.1.5 → 0.1.12

package/index.ts

@@ -15,6 +15,7 @@ export * from "./src/config.js";
 export * from "./src/agents.js";
 export * from "./src/chart.js";
 export * from "./src/genie.js";
+export * from "./src/tools/email.js";
 export {
   clearServingEndpointsCache,
   extractModelOverride,

package/package.json

@@ -1,6 +1,6 @@
 {
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "source": "./index.ts",
@@ -8,32 +8,13 @@
       "default": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "index.ts",
-    "src"
-  ],
-  "license": "Apache-2.0",
-  "homepage": "https://github.com/reggie-db/dbx-tools-appkit#readme",
-  "bugs": {
-    "url": "https://github.com/reggie-db/dbx-tools-appkit/issues"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/reggie-db/dbx-tools-appkit.git",
-    "directory": "packages/mastra"
-  },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.5",
-  "module": "index.ts",
+  "version": "0.1.12",
   "type": "module",
+  "module": "index.ts",
   "dependencies": {
-    "@dbx-tools/appkit-mastra-shared": "0.1.5",
-    "@dbx-tools/appkit-shared": "0.1.5",
+    "@dbx-tools/appkit-mastra-shared": "0.1.12",
+    "@dbx-tools/appkit-shared": "0.1.12",
     "@mastra/ai-sdk": "^1.3",
     "@mastra/core": "^1.32",
     "@mastra/express": "^1.3",
@@ -51,5 +32,20 @@
     "@types/express": "^5",
     "@types/pg": "^8",
     "express": "^5"
+  },
+  "files": [
+    "dist",
+    "index*.ts",
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/reggie-db/dbx-tools-appkit#readme",
+  "bugs": {
+    "url": "https://github.com/reggie-db/dbx-tools-appkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools-appkit.git",
+    "directory": "packages/mastra"
   }
 }

package/src/agents.ts

@@ -26,6 +26,7 @@ import type { MastraPluginConfig } from "./config.js";
 import { buildGenieProvider } from "./genie.js";
 import type { MemoryBuilder } from "./memory.js";
 import { buildModel } from "./model.js";
+import { stripStaleChartsProcessor } from "./processors/strip-stale-charts.js";
 
 /**
  * Tool record accepted by every Mastra `Agent.tools` field and by the
@@ -122,8 +123,8 @@ export interface AppKitToolOptions {
 /**
  * Build a deterministic Mastra tool id from a description.
  * Delegates to {@link stringUtils.toUniqueSlug}: slug + always-on
- * SHA-1 suffix so two tools with the same leading words don't
- * collide in traces. Stable across runs.
+ * 6-char FNV-1a base-32 suffix so two tools with the same leading
+ * words don't collide in traces. Stable across runs.
  */
 function deriveToolId(description: string): string {
   return stringUtils.toUniqueSlug(description, { fallbackPrefix: "tool" });
@@ -407,7 +408,7 @@ export async function buildAgents(opts: {
   const ids = Object.keys(definitions);
   const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
 
-  const plugins = buildPluginsMap(context);
+  const plugins = buildPluginsMap(config, context);
   // 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
@@ -418,6 +419,12 @@ export async function buildAgents(opts: {
   };
   const ambientTools = { ...systemTools, ...(config.tools ?? {}) };
   const style = resolveStyleInstructions(config);
+  // Default-on protection against the model copying turn-scoped
+  // chartIds from prior assistant tool results into the new
+  // turn's `[[chart:<id>]]` markers. Opt out per-plugin via
+  // `config.stripStaleCharts: false`.
+  const inputProcessors =
+    config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor];
   const agents: Record<string, Agent> = {};
 
   for (const [id, def] of Object.entries(definitions)) {
@@ -431,6 +438,7 @@ export async function buildAgents(opts: {
       model: resolveModel(config, def.model),
       tools,
       ...(memory ? { memory } : {}),
+      ...(inputProcessors.length > 0 ? { inputProcessors } : {}),
     });
   }
 
@@ -581,6 +589,7 @@ async function resolveTools(
  * time instead of staring at a spinner for the full Genie round-trip.
  */
 function buildPluginsMap(
+  config: MastraPluginConfig,
   context: pluginUtils.PluginContextLike | undefined,
 ): MastraPlugins {
   const cache = new Map<string, MastraPluginToolkitProvider | null>();
@@ -588,7 +597,7 @@ function buildPluginsMap(
     get(_target, propName) {
       if (typeof propName !== "string") return undefined;
       if (cache.has(propName)) return cache.get(propName) ?? undefined;
-      const provider = resolveProvider(context, propName);
+      const provider = resolveProvider(config, context, propName);
       cache.set(propName, provider);
       return provider ?? undefined;
     },
@@ -599,16 +608,20 @@ function buildPluginsMap(
  * Pick the right {@link MastraPluginToolkitProvider} for a sibling
  * plugin lookup. Returns the streaming-aware Genie adapter when the
  * caller asks for `genie`; falls back to the generic AppKit
- * `ToolProvider` adapter for every other plugin name.
+ * `ToolProvider` adapter for every other plugin name. `config` is
+ * threaded through so Genie's tool can run the chart planner
+ * inline against the same model resolver / fallback ladder the
+ * agents use.
  */
 function resolveProvider(
+  config: MastraPluginConfig,
   context: pluginUtils.PluginContextLike | undefined,
   propName: string,
 ): MastraPluginToolkitProvider | null {
   if (propName === "genie") {
     const geniePlugin = pluginUtils.instance(context, genie);
     if (!geniePlugin) return null;
-    return buildGenieProvider(geniePlugin) as MastraPluginToolkitProvider;
+    return buildGenieProvider(geniePlugin, { config }) as MastraPluginToolkitProvider;
   }
   const plugin = context?.getPlugins().get(propName);
   return adaptPluginToolkit(plugin);

package/src/chart.ts

@@ -1,36 +1,42 @@
 /**
  * Chart-rendering primitives.
  *
- * Two surfaces, one shared brain:
+ * Three 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.
+ *   ("here is a dataset, render it as a chart"). The tool's
+ *   `execute` emits a `kind: "chart"` event with the raw rows to
+ *   `ctx.writer` synchronously, kicks off the chart-planner agent,
+ *   and `await`s the planner promise before returning so the
+ *   planner's latency is attributed to this tool's trace span.
+ *   The LLM-bound output is just `{ chartId }`, so its context
+ *   stays flat regardless of dataset size.
+ *
+ * - {@link emitChartWithPlanning}: the underlying helper that both
+ *   `render_data` and Genie's `drainGenieStream` call. Mints the
+ *   `chartId`, fires the dataset event immediately, runs the
+ *   planner in the background, and returns `{ chartId,
+ *   plannerPromise }` so callers can choose to await for trace
+ *   shape or fire-and-forget.
  *
  * - {@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.
+ *   expansion as a plain async function. Used internally by
+ *   {@link emitChartWithPlanning}; producers shouldn't reach for
+ *   it directly so chart events keep a single wire-format
+ *   contract.
  *
  * 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.
+ * shows a skeleton until the second `kind: "chart"` event (with
+ * the resolved `EChartsOption`) arrives, then swaps in the
+ * rendered Echarts visualisation.
  */
 
 import { randomUUID } from "node:crypto";
 
-import { stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import { Agent } from "@mastra/core/agent";
 import type { RequestContext } from "@mastra/core/request-context";
 import { createTool } from "@mastra/core/tools";
@@ -39,6 +45,15 @@ import { z } from "zod";
 import type { MastraPluginConfig } from "./config.js";
 import { ModelTier, modelForTier, buildModel } from "./model.js";
 
+/**
+ * Module-level logger tagged `[mastra/chart]`. Uses the shared
+ * {@link logUtils.logger} so calls below `LOG_LEVEL` are
+ * discarded for free. Default `LOG_LEVEL` is `info`; flip to
+ * `debug` to see the per-chart timeline (`emit:start` →
+ * `write:ok(data)` → `planner:done` → `write:ok(option)`).
+ */
+const log = logUtils.logger("mastra/chart");
+
 /**
  * Compact, model-friendly representation of an Echarts spec. The
  * planner agent emits this; {@link planToEchartsOption} expands it
@@ -211,10 +226,10 @@ function getPlannerAgent(config: MastraPluginConfig): 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.
+ * full Echarts `EChartsOption` JSON. Used by
+ * {@link emitChartWithPlanning}; tools and producers shouldn't
+ * call this directly (use the helper instead so chart events
+ * follow the same wire-format contract everywhere).
  */
 export async function runChartPlanner(
   opts: RunChartPlannerOptions,
@@ -243,6 +258,170 @@ export async function runChartPlanner(
   return { option, chartType: plan.chartType };
 }
 
+/**
+ * Minimal `ToolStream`-shaped writer surface. Defined locally so
+ * helpers can take any object with a `.write` method without
+ * importing Mastra's full `ToolStream` (which would also drag in
+ * agent / tool types this module doesn't otherwise need).
+ */
+interface MinimalWriter {
+  write: (chunk: unknown) => unknown;
+}
+
+/** Inputs to {@link emitChartWithPlanning}. */
+export interface EmitChartWithPlanningOptions {
+  /** Mastra `ctx.writer`; missing or closed writers are tolerated. */
+  writer?: MinimalWriter;
+  /** Plugin config; used to resolve the planner's model. */
+  config: MastraPluginConfig;
+  /** Per-request context (OBO auth). */
+  requestContext?: RequestContext;
+  /** Title shown above the rendered chart. Required. */
+  title: string;
+  /** Optional one-line intent biasing the planner. */
+  description?: string;
+  /** Tabular dataset to chart (one object per row). */
+  data: ReadonlyArray<Record<string, unknown>>;
+}
+
+/** Output of {@link emitChartWithPlanning}. */
+export interface EmitChartWithPlanningResult {
+  /** Short id matching the marker `[[chart:<chartId>]]`. */
+  chartId: string;
+  /**
+   * Promise that resolves once the planner has finished and the
+   * `kind: "chart"` event with the option has been emitted (or
+   * once the planner has failed silently). Callers that want
+   * trace observability should `await` this before returning
+   * from their tool's `execute`; callers that want pure
+   * fire-and-forget can ignore it.
+   */
+  plannerPromise: Promise<void>;
+}
+
+/**
+ * Shared chart-emission primitive used by both the `render_data`
+ * tool and Genie's `drainGenieStream`. Keeps both producers on
+ * one wire-format contract so the chat client only ever has to
+ * understand a single chart event shape.
+ *
+ * Behaviour:
+ *
+ * 1. Generates a short `chartId` (8 hex chars).
+ * 2. Immediately emits `{ kind: "chart", chartId, title,
+ *    description?, data }` via the writer so the chat client can
+ *    mount its `<ChartSlot>` with the rows in hand.
+ * 3. Kicks off the chart-planner agent in the background. On
+ *    success, emits a second `{ kind: "chart", chartId, option }`
+ *    event - same `chartId`, just the spec - so the client merges
+ *    the two into one rendered chart. On failure, no follow-up
+ *    event fires; the client falls back to whatever it can do
+ *    with the dataset alone (typically a "render failed" frame
+ *    after the parent tool finishes).
+ *
+ * Returns `chartId` synchronously so the caller can include it in
+ * the tool result (model uses it in `[[chart:<chartId>]]`
+ * markers), and `plannerPromise` so the caller can choose
+ * trace-spanning vs. snappy-return semantics.
+ */
+export async function emitChartWithPlanning(
+  opts: EmitChartWithPlanningOptions,
+): Promise<EmitChartWithPlanningResult> {
+  const { writer, config, requestContext, title, description, data } = opts;
+
+  // Short, marker-friendly id. The LLM types this verbatim into
+  // `[[chart:<id>]]`; 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);
+
+  log.debug("emit:start", {
+    chartId,
+    title,
+    rows: data.length,
+    columns: data[0] ? Object.keys(data[0]) : [],
+    hasWriter: writer !== undefined,
+  });
+
+  // Initial event: rows + metadata, no option yet. The client
+  // mounts a chart slot that shows a skeleton until the option
+  // event arrives (or until the parent tool finishes without
+  // one, in which case it falls back).
+  await safeWrite(writer, chartId, "data", {
+    kind: "chart",
+    chartId,
+    title,
+    ...(description ? { description } : {}),
+    data,
+  });
+
+  // Background planner. Awaitable for trace observability via the
+  // returned `plannerPromise`; safe to ignore for pure
+  // fire-and-forget. Failures are intentionally swallowed (only
+  // logged): the dataset event already landed, so the client has
+  // enough to surface a fallback.
+  const plannerPromise = (async () => {
+    const startedAt = Date.now();
+    try {
+      const { option, chartType } = await runChartPlanner({
+        config,
+        ...(requestContext ? { requestContext } : {}),
+        title,
+        ...(description ? { description } : {}),
+        data,
+      });
+      log.debug("planner:done", {
+        chartId,
+        chartType,
+        elapsedMs: Date.now() - startedAt,
+      });
+      await safeWrite(writer, chartId, "option", { kind: "chart", chartId, option });
+    } catch (err) {
+      // No follow-up event on failure. The client treats a
+      // dataset-only chart slot as "render failed" once the
+      // parent tool's status flips to done. Surface as a `warn`
+      // so the failure is visible at the default log level
+      // without being mistaken for a fatal error.
+      log.warn("planner:error", {
+        chartId,
+        elapsedMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  })();
+
+  return { chartId, plannerPromise };
+}
+
+/**
+ * Best-effort writer.write. Failures are logged at `warn` (a
+ * persistently-closed writer is the most likely culprit when
+ * chart events go missing client-side) but swallowed so a closed
+ * downstream stream (cancelled request, client navigated away)
+ * can't take a tool down.
+ */
+async function safeWrite(
+  writer: MinimalWriter | undefined,
+  chartId: string,
+  phase: "data" | "option",
+  chunk: unknown,
+): Promise<void> {
+  if (!writer) {
+    log.debug("write:no-writer", { chartId, phase });
+    return;
+  }
+  try {
+    await writer.write(chunk);
+    log.debug("write:ok", { chartId, phase });
+  } catch (err) {
+    log.warn("write:error", {
+      chartId,
+      phase,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
 const renderDataInputSchema = z.object({
   title: z.string().describe(stringUtils.toDescription`
     Title shown above the rendered chart. Use a concise
@@ -269,31 +448,28 @@ const renderDataInputSchema = z.object({
 
 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.
+    Identifier of the queued chart. To position the chart in
+    your reply, embed the marker \`[[chart:<chartId>]]\` on its
+    own line where the chart should appear; the client renders
+    it inline.
   `),
 });
 
 /**
  * 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.
+ * The tool is a thin wrapper around {@link emitChartWithPlanning}:
+ * a single `kind: "chart"` writer event ships the raw rows to
+ * the client immediately, the chart-planner agent runs alongside
+ * (so the calling LLM stays unblocked while the planner thinks),
+ * and a follow-up `kind: "chart"` event with the resolved
+ * `EChartsOption` lands when it's ready. The tool's `execute`
+ * awaits the planner promise so the planner work shows up under
+ * the tool's trace span; the LLM still gets back just
+ * `{ chartId }`, so its context stays small regardless of dataset
+ * size.
  */
-export function buildRenderDataTool(_config: MastraPluginConfig) {
+export function buildRenderDataTool(config: MastraPluginConfig) {
   return createTool({
     id: "render_data",
     description: stringUtils.toDescription`
@@ -301,9 +477,8 @@ export function buildRenderDataTool(_config: MastraPluginConfig) {
       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.
+      \`chartId\`; the chart renders inline at the position you
+      embed the matching \`[[chart:<chartId>]]\` marker.
 
       Placement contract: embed \`[[chart:<chartId>]]\` on its own
       line (blank lines above and below) wherever you want the
@@ -327,28 +502,21 @@ export function buildRenderDataTool(_config: MastraPluginConfig) {
       const { title, description, data } = input as z.infer<
         typeof renderDataInputSchema
       >;
-
-      // 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 as { writer?: { write: (e: unknown) => unknown } } | undefined)
-        ?.writer;
-      try {
-        await writer?.write({
-          kind: "chart",
-          chartId,
-          title,
-          ...(description ? { description } : {}),
-          data,
-        });
-      } catch {
-        // Ignore: the parent stream may have closed downstream.
-      }
-
+      const writer = (ctx as { writer?: MinimalWriter } | undefined)?.writer;
+      const requestContext = (ctx as { requestContext?: RequestContext } | undefined)
+        ?.requestContext;
+      const { chartId, plannerPromise } = await emitChartWithPlanning({
+        ...(writer ? { writer } : {}),
+        config,
+        ...(requestContext ? { requestContext } : {}),
+        title,
+        ...(description ? { description } : {}),
+        data,
+      });
+      // Await the planner so its latency is attributed to this
+      // tool's trace span. The promise itself swallows planner
+      // failures, so this never throws.
+      await plannerPromise;
       return { chartId };
     },
   });

package/src/config.ts

@@ -161,6 +161,19 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * or to add custom endpoints in front of the public catalogue.
    */
   defaultModelFallbacks?: readonly string[];
+  /**
+   * When `true` (default), every agent gets a built-in input
+   * processor that strips `chartId` fields from prior assistant
+   * tool-invocation results before they reach the model. This
+   * prevents the model from reusing turn-scoped chartIds it sees
+   * in memory recall (which would leave `[[chart:<id>]]` markers
+   * pointing at writer events that no longer exist).
+   *
+   * Set to `false` to opt out - useful if a non-default agent
+   * needs full visibility into prior chartIds (e.g. an audit
+   * agent reasoning about chart lineage).
+   */
+  stripStaleCharts?: boolean;
   /**
    * Style guardrails appended to every agent's `instructions` to curb
    * common LLM-isms (em dashes, emojis, sycophantic openers, throwaway