@dbx-tools/appkit-mastra 0.1.5 → 0.1.12

package/dist/src/processors/strip-stale-charts.js

@@ -0,0 +1,96 @@
+/**
+ * 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";
+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) {
+    if (Array.isArray(value)) {
+        return value.map(stripChartIds);
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const out = {};
+        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 = {
+    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) {
+        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.type !== "tool-invocation") {
+                    continue;
+                }
+                const inv = part
+                    .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/dist/src/server.js

@@ -31,6 +31,16 @@ 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/dist/src/serving.js

@@ -20,8 +20,9 @@
  * `plugin.ts` exposes the cached list at `GET /models`.
  */
 import { CacheManager } from "@databricks/appkit";
-import { stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import Fuse from "fuse.js";
+const log = logUtils.logger("mastra/serving");
 /**
  * `RequestContext` key under which {@link MastraServer} stores the
  * per-request model override (header / query / body). `model.ts`
@@ -76,6 +77,7 @@ export async function listServingEndpoints(client, host, opts = {}) {
     return CacheManager.getInstanceSync().getOrExecute([CACHE_KEY_NAMESPACE, host], () => fetchEndpoints(client), SHARED_USER_KEY, { ttl: ttlSec });
 }
 async function fetchEndpoints(client) {
+    const startedAt = Date.now();
     const out = [];
     for await (const ep of client.servingEndpoints.list()) {
         if (!ep.name)
@@ -87,6 +89,7 @@ async function fetchEndpoints(client) {
             ...(ep.description !== undefined ? { description: ep.description } : {}),
         });
     }
+    log.debug("listed", { count: out.length, elapsedMs: Date.now() - startedAt });
     return out;
 }
 /**
@@ -127,10 +130,12 @@ export async function clearServingEndpointsCache(host) {
  */
 export function resolveModelId(input, endpoints, opts = {}) {
     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 };
         }
     }
@@ -148,13 +153,25 @@ export function resolveModelId(input, endpoints, opts = {}) {
     // lean on the shared tokenizer so the splitting rules stay
     // consistent with the rest of the toolkit.
     const query = Array.from(stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input)).join(" ");
-    if (!query)
+    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/dist/src/tools/email.d.ts

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

package/dist/src/tools/email.js

@@ -0,0 +1,122 @@
+/**
+ * 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.
+  `),
+});
+/**
+ * Build the `send_email` tool. Approval-gated by default; the
+ * execute body either calls the supplied {@link send} hook or
+ * logs the email to the server console as a demo stub.
+ *
+ * @example
+ * ```ts
+ * import { buildEmailTool, createAgent, mastra } from "@dbx-tools/appkit-mastra";
+ *
+ * const support = createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       ...(plugins.genie?.toolkit() ?? {}),
+ *       send_email: buildEmailTool(),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export function buildEmailTool(opts = {}) {
+    return createTool({
+        id: opts.id ?? "send_email",
+        description: stringUtils.toDescription `
+      Send an email on the user's behalf. Pass a recipient
+      address, subject, and body; the user will be prompted to
+      approve the send before it goes out (the tool is
+      approval-gated). Use this when the user explicitly asks
+      to send / forward / share something via email - never
+      autonomously. Keep subjects short and bodies focused; the
+      recipient may not have any of the chat context.
+    `,
+        inputSchema: emailInputSchema,
+        outputSchema: emailOutputSchema,
+        requireApproval: true,
+        execute: async (input) => {
+            const { to, subject, body, cc, bcc } = input;
+            // Default behaviour: dump the email to the server console so
+            // demos can see the gate fire end-to-end without a real
+            // provider. Replace by passing `opts.send`.
+            log.info("send", {
+                to,
+                ...(cc && cc.length > 0 ? { cc } : {}),
+                ...(bcc && bcc.length > 0 ? { bcc } : {}),
+                subject,
+                bodyLength: body.length,
+                body,
+            });
+            if (opts.send) {
+                await opts.send(input);
+            }
+            return { sent: true, recipient: to };
+        },
+    });
+}