@dbx-tools/appkit-mastra 0.1.5 → 0.1.12

package/src/processors/strip-stale-charts.ts

@@ -0,0 +1,105 @@
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are only meaningful within the assistant turn that
+ * minted them - the writer events backing them are gone after the
+ * stream closes. When the model sees old chartIds in memory recall
+ * (Mastra Memory persists tool results), it's tempted to type
+ * those ids into the new turn's `[[chart:<id>]]` markers, leaving
+ * the chat client's chart slots stuck with no matching event. This
+ * processor removes the temptation by deleting `chartId` keys from
+ * every assistant message's tool results before the prompt is
+ * built. The current turn's tool results don't exist yet at
+ * `processInput` time, so they pass through unmodified.
+ *
+ * The strip is recursive - any nested `chartId` field is removed,
+ * regardless of which tool produced the result. This covers Genie's
+ * `datasets[].chartId` and `render_data`'s top-level `chartId`
+ * uniformly without coupling to specific tool ids.
+ */
+
+import { logUtils } from "@dbx-tools/appkit-shared";
+import type {
+  InputProcessor,
+  ProcessInputArgs,
+} from "@mastra/core/processors";
+
+const log = logUtils.logger("mastra/processor/strip-stale-charts");
+
+/**
+ * Recursively clone `value`, omitting any property whose key is
+ * `chartId`. Arrays are mapped element-wise; primitives are
+ * returned as-is. The result is structurally identical to the
+ * input minus chartIds, so downstream message-shape consumers
+ * keep working.
+ */
+function stripChartIds(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stripChartIds);
+  }
+  if (value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      if (key === "chartId") continue;
+      out[key] = stripChartIds(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Input processor that scrubs `chartId` from every tool-invocation
+ * result in the message list. Wired onto every agent by default
+ * via {@link buildAgents}; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export const stripStaleChartsProcessor: InputProcessor = {
+  id: "strip-stale-charts",
+  description:
+    "Removes chartId fields from prior tool-invocation results so the model can't reuse turn-scoped ids from memory.",
+  processInput(args: ProcessInputArgs) {
+    let stripped = 0;
+    for (const message of args.messages) {
+      if (message.role !== "assistant") continue;
+      const parts = message.content?.parts;
+      if (!Array.isArray(parts)) continue;
+      for (const part of parts) {
+        // Tool-invocation parts hold the persisted tool result.
+        // We don't scrub the input args (`rawInput` / `args`) because
+        // the chartId there is the model's outgoing claim, not
+        // anything it could re-reference; only `result` carries
+        // ids that subsequent turns might copy.
+        if (
+          (part as { type?: unknown }).type !== "tool-invocation"
+        ) {
+          continue;
+        }
+        const inv = (part as { toolInvocation?: { result?: unknown } })
+          .toolInvocation;
+        if (!inv || inv.result === undefined) continue;
+        const before = inv.result;
+        const after = stripChartIds(before);
+        // Cheap structural check via JSON length - the actual
+        // strip writes a fresh object only when chartId keys
+        // existed, so different stringification length is a
+        // reliable signal that something was removed.
+        if (
+          typeof before === "object" &&
+          before !== null &&
+          JSON.stringify(before).length !== JSON.stringify(after).length
+        ) {
+          inv.result = after;
+          stripped += 1;
+        }
+      }
+    }
+    if (stripped > 0) {
+      log.debug("stripped", { results: stripped });
+    }
+    return args.messages;
+  },
+};

package/src/server.ts

@@ -46,6 +46,17 @@ export class MastraServer extends MastraServerExpress {
       this.configureRequestContextUser(requestContext);
       this.configureRequestContextThreadId(req, res, requestContext);
       this.configureRequestContextModelOverride(req, requestContext);
+      this.log.debug("auth:middleware", {
+        method: req.method,
+        path: req.path,
+        threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
+        resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
+        modelOverride: requestContext.get(
+          // imported below; logged so a misrouted request shows
+          // up alongside its model selection in `LOG_LEVEL=debug`.
+          "mastra__model_override",
+        ),
+      });
       next();
     });
   }

package/src/serving.ts

@@ -21,7 +21,7 @@
  */
 
 import { CacheManager, type getExecutionContext } from "@databricks/appkit";
-import { stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import Fuse from "fuse.js";
 
 import type { ServingEndpointSummary } from "@dbx-tools/appkit-mastra-shared";
@@ -29,6 +29,8 @@ import type { MastraPluginConfig } from "./config.js";
 
 export type { ServingEndpointSummary };
 
+const log = logUtils.logger("mastra/serving");
+
 /**
  * Structural type for the Databricks workspace client. Derived from
  * AppKit's `ExecutionContext` so this module doesn't take a direct
@@ -111,6 +113,7 @@ export async function listServingEndpoints(
 async function fetchEndpoints(
   client: WorkspaceClientLike,
 ): Promise<ServingEndpointSummary[]> {
+  const startedAt = Date.now();
   const out: ServingEndpointSummary[] = [];
   for await (const ep of client.servingEndpoints.list()) {
     if (!ep.name) continue;
@@ -121,6 +124,7 @@ async function fetchEndpoints(
       ...(ep.description !== undefined ? { description: ep.description } : {}),
     });
   }
+  log.debug("listed", { count: out.length, elapsedMs: Date.now() - startedAt });
   return out;
 }
 
@@ -185,10 +189,12 @@ export function resolveModelId(
   opts: ResolveModelOptions = {},
 ): ResolvedModel {
   if (endpoints.length === 0) {
+    log.debug("resolve:no-endpoints", { input });
     return { modelId: input, matched: false };
   }
   for (const ep of endpoints) {
     if (ep.name === input) {
+      log.debug("resolve:exact", { input });
       return { modelId: ep.name, matched: true, score: 0 };
     }
   }
@@ -208,12 +214,25 @@ export function resolveModelId(
   const query = Array.from(
     stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input),
   ).join(" ");
-  if (!query) return { modelId: input, matched: false };
+  if (!query) {
+    log.debug("resolve:empty-tokens", { input });
+    return { modelId: input, matched: false };
+  }
   const results = fuse.search(query);
   const best = results[0];
   if (best?.item.name && (best.score ?? 0) <= threshold) {
+    log.debug("resolve:fuzzy-match", {
+      input,
+      modelId: best.item.name,
+      score: best.score,
+    });
     return { modelId: best.item.name, matched: true, score: best.score };
   }
+  log.debug("resolve:no-match", {
+    input,
+    bestScore: best?.score,
+    threshold,
+  });
   return { modelId: input, matched: false };
 }
 

package/src/tools/email.ts

@@ -0,0 +1,147 @@
+/**
+ * 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/appkit-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 };
+    },
+  });
+}

package/dist/src/render-chart-route.d.ts

@@ -1,33 +0,0 @@
-/**
- * Chart-render HTTP endpoint for the Mastra plugin.
- *
- * The `render_data` tool returns immediately with a `chartId` and
- * emits the dataset over `ctx.writer`; the client then POSTs that
- * dataset to this endpoint to actually run the chart-planner
- * agent and get back an Echarts `EChartsOption` JSON. Planning
- * happens out-of-band so the calling agent's response stream
- * doesn't sit idle waiting for it - the model can finish the
- * report while the client is still rendering charts.
- *
- * Auth flows through the standard Mastra middleware: the route
- * sits in the same dispatcher pipeline as `chatRoute` /
- * `historyRoute`, so by the time the handler runs the
- * `RequestContext` is populated with the workspace user and
- * the chart-planner's model resolver has the OBO token it
- * needs.
- */
-import type { MastraPluginConfig } from "./config.js";
-/** Options accepted by {@link renderChartRoute}. */
-export interface RenderChartRouteOptions {
-    path: string;
-    config: MastraPluginConfig;
-}
-/**
- * Register a `POST <path>` Mastra custom API route that runs the
- * chart-planner agent against a dataset and returns an Echarts
- * `EChartsOption` JSON.
- *
- * Body shape: {@link RenderChartRequest}; response:
- * {@link RenderChartResponse}.
- */
-export declare function renderChartRoute(options: RenderChartRouteOptions): import("@mastra/core/server").ApiRoute;

package/dist/src/render-chart-route.js

@@ -1,120 +0,0 @@
-/**
- * Chart-render HTTP endpoint for the Mastra plugin.
- *
- * The `render_data` tool returns immediately with a `chartId` and
- * emits the dataset over `ctx.writer`; the client then POSTs that
- * dataset to this endpoint to actually run the chart-planner
- * agent and get back an Echarts `EChartsOption` JSON. Planning
- * happens out-of-band so the calling agent's response stream
- * doesn't sit idle waiting for it - the model can finish the
- * report while the client is still rendering charts.
- *
- * Auth flows through the standard Mastra middleware: the route
- * sits in the same dispatcher pipeline as `chatRoute` /
- * `historyRoute`, so by the time the handler runs the
- * `RequestContext` is populated with the workspace user and
- * the chart-planner's model resolver has the OBO token it
- * needs.
- */
-import { registerApiRoute } from "@mastra/core/server";
-import { runChartPlanner } from "./chart.js";
-/** Hard cap so a misbehaving client can't hand us a million-row payload. */
-const MAX_ROWS = 5_000;
-/**
- * Hard cap on the JSON body the route accepts (in bytes). Mirrors
- * the same intent as {@link MAX_ROWS}: bound the chart-planner's
- * prompt size and protect against accidental denial-of-service
- * from a runaway tool that ships an enormous payload.
- */
-const MAX_BODY_BYTES = 2 * 1024 * 1024;
-/**
- * Register a `POST <path>` Mastra custom API route that runs the
- * chart-planner agent against a dataset and returns an Echarts
- * `EChartsOption` JSON.
- *
- * Body shape: {@link RenderChartRequest}; response:
- * {@link RenderChartResponse}.
- */
-export function renderChartRoute(options) {
-    const { path, config } = options;
-    return registerApiRoute(path, {
-        method: "POST",
-        handler: async (c) => {
-            const requestContext = c.get("requestContext");
-            // Hono parses the body as JSON; we still validate shape /
-            // size since the tool's structured output is a contract,
-            // not a guarantee, and the route is publicly mountable.
-            const raw = (await c.req.json().catch(() => null));
-            const validation = validateBody(raw);
-            if ("error" in validation) {
-                return c.json({ error: validation.error }, 400);
-            }
-            const { title, description, data } = validation.body;
-            try {
-                const result = await runChartPlanner({
-                    config,
-                    ...(requestContext ? { requestContext } : {}),
-                    title,
-                    ...(description ? { description } : {}),
-                    data,
-                });
-                const payload = {
-                    option: result.option,
-                    chartType: result.chartType,
-                };
-                return c.json(payload);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return c.json({ error: message }, 500);
-            }
-        },
-    });
-}
-/**
- * Best-effort body validation. Surfaces a 400 for malformed input
- * instead of letting a downstream `.map` / `.length` blow up
- * inside the planner agent. Field-level shape mirrors
- * {@link RenderChartRequest}.
- */
-function validateBody(raw) {
-    if (!raw || typeof raw !== "object") {
-        return { error: "request body must be a JSON object" };
-    }
-    const r = raw;
-    const title = r.title;
-    if (typeof title !== "string" || title.length === 0) {
-        return { error: "`title` must be a non-empty string" };
-    }
-    if (r.description !== undefined && typeof r.description !== "string") {
-        return { error: "`description` must be a string when provided" };
-    }
-    if (!Array.isArray(r.data)) {
-        return { error: "`data` must be an array of row objects" };
-    }
-    if (r.data.length === 0) {
-        return { error: "`data` must contain at least one row" };
-    }
-    if (r.data.length > MAX_ROWS) {
-        return { error: `\`data\` exceeds the per-request limit of ${MAX_ROWS} rows` };
-    }
-    for (const [i, row] of r.data.entries()) {
-        if (!row || typeof row !== "object" || Array.isArray(row)) {
-            return { error: `data[${i}] must be a plain object` };
-        }
-    }
-    // Approximate body-size check; spares us pulling Buffer in.
-    const approximateBytes = JSON.stringify(r.data).length;
-    if (approximateBytes > MAX_BODY_BYTES) {
-        return {
-            error: `\`data\` exceeds the per-request size limit of ${MAX_BODY_BYTES} bytes`,
-        };
-    }
-    return {
-        body: {
-            title,
-            ...(typeof r.description === "string" ? { description: r.description } : {}),
-            data: r.data,
-        },
-    };
-}

package/src/render-chart-route.ts

@@ -1,141 +0,0 @@
-/**
- * Chart-render HTTP endpoint for the Mastra plugin.
- *
- * The `render_data` tool returns immediately with a `chartId` and
- * emits the dataset over `ctx.writer`; the client then POSTs that
- * dataset to this endpoint to actually run the chart-planner
- * agent and get back an Echarts `EChartsOption` JSON. Planning
- * happens out-of-band so the calling agent's response stream
- * doesn't sit idle waiting for it - the model can finish the
- * report while the client is still rendering charts.
- *
- * Auth flows through the standard Mastra middleware: the route
- * sits in the same dispatcher pipeline as `chatRoute` /
- * `historyRoute`, so by the time the handler runs the
- * `RequestContext` is populated with the workspace user and
- * the chart-planner's model resolver has the OBO token it
- * needs.
- */
-
-import type {
-  RenderChartRequest,
-  RenderChartResponse,
-} from "@dbx-tools/appkit-mastra-shared";
-import { registerApiRoute } from "@mastra/core/server";
-
-import { runChartPlanner } from "./chart.js";
-import type { MastraPluginConfig } from "./config.js";
-
-/** Hard cap so a misbehaving client can't hand us a million-row payload. */
-const MAX_ROWS = 5_000;
-/**
- * Hard cap on the JSON body the route accepts (in bytes). Mirrors
- * the same intent as {@link MAX_ROWS}: bound the chart-planner's
- * prompt size and protect against accidental denial-of-service
- * from a runaway tool that ships an enormous payload.
- */
-const MAX_BODY_BYTES = 2 * 1024 * 1024;
-
-/** Options accepted by {@link renderChartRoute}. */
-export interface RenderChartRouteOptions {
-  path: string;
-  config: MastraPluginConfig;
-}
-
-/**
- * Register a `POST <path>` Mastra custom API route that runs the
- * chart-planner agent against a dataset and returns an Echarts
- * `EChartsOption` JSON.
- *
- * Body shape: {@link RenderChartRequest}; response:
- * {@link RenderChartResponse}.
- */
-export function renderChartRoute(options: RenderChartRouteOptions) {
-  const { path, config } = options;
-  return registerApiRoute(path, {
-    method: "POST",
-    handler: async (c) => {
-      const requestContext = c.get("requestContext");
-
-      // Hono parses the body as JSON; we still validate shape /
-      // size since the tool's structured output is a contract,
-      // not a guarantee, and the route is publicly mountable.
-      const raw = (await c.req.json().catch(() => null)) as unknown;
-      const validation = validateBody(raw);
-      if ("error" in validation) {
-        return c.json({ error: validation.error }, 400);
-      }
-      const { title, description, data } = validation.body;
-
-      try {
-        const result = await runChartPlanner({
-          config,
-          ...(requestContext ? { requestContext } : {}),
-          title,
-          ...(description ? { description } : {}),
-          data,
-        });
-        const payload: RenderChartResponse = {
-          option: result.option,
-          chartType: result.chartType,
-        };
-        return c.json(payload);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return c.json({ error: message }, 500);
-      }
-    },
-  });
-}
-
-type ValidationResult =
-  | { body: RenderChartRequest }
-  | { error: string };
-
-/**
- * Best-effort body validation. Surfaces a 400 for malformed input
- * instead of letting a downstream `.map` / `.length` blow up
- * inside the planner agent. Field-level shape mirrors
- * {@link RenderChartRequest}.
- */
-function validateBody(raw: unknown): ValidationResult {
-  if (!raw || typeof raw !== "object") {
-    return { error: "request body must be a JSON object" };
-  }
-  const r = raw as Record<string, unknown>;
-  const title = r.title;
-  if (typeof title !== "string" || title.length === 0) {
-    return { error: "`title` must be a non-empty string" };
-  }
-  if (r.description !== undefined && typeof r.description !== "string") {
-    return { error: "`description` must be a string when provided" };
-  }
-  if (!Array.isArray(r.data)) {
-    return { error: "`data` must be an array of row objects" };
-  }
-  if (r.data.length === 0) {
-    return { error: "`data` must contain at least one row" };
-  }
-  if (r.data.length > MAX_ROWS) {
-    return { error: `\`data\` exceeds the per-request limit of ${MAX_ROWS} rows` };
-  }
-  for (const [i, row] of r.data.entries()) {
-    if (!row || typeof row !== "object" || Array.isArray(row)) {
-      return { error: `data[${i}] must be a plain object` };
-    }
-  }
-  // Approximate body-size check; spares us pulling Buffer in.
-  const approximateBytes = JSON.stringify(r.data).length;
-  if (approximateBytes > MAX_BODY_BYTES) {
-    return {
-      error: `\`data\` exceeds the per-request size limit of ${MAX_BODY_BYTES} bytes`,
-    };
-  }
-  return {
-    body: {
-      title,
-      ...(typeof r.description === "string" ? { description: r.description } : {}),
-      data: r.data as Array<Record<string, unknown>>,
-    },
-  };
-}