@dbx-tools/appkit-mastra 0.1.5 → 0.1.13

package/dist/src/observability.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
+ * sibling plugin.
+ *
+ * Mastra's `Observability` registry accepts any
+ * `@mastra/observability` `BaseExporter`. We use `OtelExporter` from
+ * `@mastra/otel-exporter` (Mastra's first-party OTLP shim) with the
+ * `custom` provider pointed at Phoenix's local collector URL. No
+ * Arize-specific wrapper is needed - Phoenix is a vanilla
+ * OpenInference-compatible OTLP/HTTP receiver.
+ *
+ * Discovery is structural so this module doesn't depend on
+ * `@dbx-tools/appkit-phoenix` at compile time: we look up the
+ * registered plugin by its registered name (`"phoenix"`) and read its
+ * `exports().collectorEndpoint()` if it is shaped like the phoenix
+ * plugin. The phoenix package is therefore an *optional* sibling -
+ * apps that don't install it just get an undefined observability
+ * config and Mastra runs without OTLP export.
+ */
+import type { pluginUtils } from "@dbx-tools/appkit-shared";
+import { Observability } from "@mastra/observability";
+/**
+ * If the sibling `phoenix` plugin is registered AND has booted with a
+ * usable collector URL, return a Mastra `Observability` configured to
+ * stream traces + logs there. Otherwise return `undefined` so the
+ * caller can omit the field on the `new Mastra({...})` constructor.
+ *
+ * The exporter uses `provider.custom` with `http/protobuf`, which is
+ * what Phoenix's `/v1/traces` endpoint speaks natively. Switching
+ * Phoenix to gRPC would be a one-line `protocol: "grpc"` change and
+ * a different exported URL.
+ */
+export declare function buildPhoenixObservability(context: pluginUtils.PluginContextLike | undefined, serviceName: string): Observability | undefined;

package/dist/src/observability.js

@@ -0,0 +1,71 @@
+/**
+ * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
+ * sibling plugin.
+ *
+ * Mastra's `Observability` registry accepts any
+ * `@mastra/observability` `BaseExporter`. We use `OtelExporter` from
+ * `@mastra/otel-exporter` (Mastra's first-party OTLP shim) with the
+ * `custom` provider pointed at Phoenix's local collector URL. No
+ * Arize-specific wrapper is needed - Phoenix is a vanilla
+ * OpenInference-compatible OTLP/HTTP receiver.
+ *
+ * Discovery is structural so this module doesn't depend on
+ * `@dbx-tools/appkit-phoenix` at compile time: we look up the
+ * registered plugin by its registered name (`"phoenix"`) and read its
+ * `exports().collectorEndpoint()` if it is shaped like the phoenix
+ * plugin. The phoenix package is therefore an *optional* sibling -
+ * apps that don't install it just get an undefined observability
+ * config and Mastra runs without OTLP export.
+ */
+import { Observability } from "@mastra/observability";
+import { OtelExporter } from "@mastra/otel-exporter";
+/** Plugin name the phoenix plugin registers under (matches `phoenix()`). */
+const PHOENIX_PLUGIN_NAME = "phoenix";
+/**
+ * If the sibling `phoenix` plugin is registered AND has booted with a
+ * usable collector URL, return a Mastra `Observability` configured to
+ * stream traces + logs there. Otherwise return `undefined` so the
+ * caller can omit the field on the `new Mastra({...})` constructor.
+ *
+ * The exporter uses `provider.custom` with `http/protobuf`, which is
+ * what Phoenix's `/v1/traces` endpoint speaks natively. Switching
+ * Phoenix to gRPC would be a one-line `protocol: "grpc"` change and
+ * a different exported URL.
+ */
+export function buildPhoenixObservability(context, serviceName) {
+    const endpoint = readPhoenixEndpoint(context);
+    if (!endpoint)
+        return undefined;
+    return new Observability({
+        configs: {
+            phoenix: {
+                serviceName,
+                exporters: [
+                    new OtelExporter({
+                        provider: {
+                            custom: {
+                                endpoint,
+                                protocol: "http/protobuf",
+                            },
+                        },
+                    }),
+                ],
+            },
+        },
+    });
+}
+/**
+ * Pull the OTLP collector URL out of the registered `phoenix` plugin.
+ * Tolerant of the plugin being absent (returns `undefined`) and of a
+ * future shape change in its exports (anything that's not a string
+ * is ignored). The lookup is keyed off the registered plugin *name*
+ * so this file does not depend on `@dbx-tools/appkit-phoenix`.
+ */
+function readPhoenixEndpoint(context) {
+    if (!context)
+        return undefined;
+    const plugin = context.getPlugins().get(PHOENIX_PLUGIN_NAME);
+    const exports_ = plugin?.exports?.();
+    const url = exports_?.collectorEndpoint?.();
+    return typeof url === "string" ? url : undefined;
+}

package/dist/src/plugin.d.ts

@@ -88,7 +88,7 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
          */
         getDefault: () => Agent | null;
         /** Underlying Mastra instance for advanced use (custom routes etc.). */
-        getMastra: () => Mastra<Record<string, Agent<any, import("@mastra/core/agent").ToolsInput, undefined, unknown>>, Record<string, import("@mastra/core/workflows").AnyWorkflow>, Record<string, import("@mastra/core/vector").MastraVector<any>>, Record<string, import("@mastra/core/tts").MastraTTS>, import("@mastra/core/logger").IMastraLogger, Record<string, import("@mastra/core/mcp").MCPServerBase<any>>, Record<string, import("@mastra/core/evals").MastraScorer<any, any, any, any>>, Record<string, import("@mastra/core/tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, import("@mastra/core/processors").Processor<any, unknown>>, Record<string, import("@mastra/core/memory").MastraMemory>, Record<string, import("@mastra/core/channels").ChannelProvider>> | null;
+        getMastra: () => Mastra<Record<string, Agent<any, import("@mastra/core/agent").ToolsInput, undefined, unknown, import("@mastra/core/agent").AgentEditorConfig | undefined>>, Record<string, import("@mastra/core/workflows").AnyWorkflow>, Record<string, import("@mastra/core/vector").MastraVector<any>>, Record<string, import("@mastra/core/tts").MastraTTS>, import("@mastra/core/logger").IMastraLogger, Record<string, import("@mastra/core/mcp").MCPServerBase<any>>, Record<string, import("@mastra/core/evals").MastraScorer<any, any, any, any>>, Record<string, import("@mastra/core/tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, import("@mastra/core/processors").Processor<any, unknown>>, Record<string, import("@mastra/core/memory").MastraMemory>, Record<string, import("@mastra/core/channels").ChannelProvider>> | null;
         /** Express subapp Mastra is mounted on; mostly for tests. */
         getMastraServer: () => MastraServer | null;
         /**

package/dist/src/plugin.js

@@ -33,8 +33,8 @@ import { Mastra } from "@mastra/core/mastra";
 import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.js";
 import { historyRoute } from "./history.js";
-import { renderChartRoute } from "./render-chart-route.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
+import { buildPhoenixObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
 const GENIE_MANIFEST = pluginUtils.data(genie).plugin.manifest;
@@ -163,7 +163,6 @@ export class MastraPlugin extends Plugin {
             modelsPath: `${basePath}/models`,
             historyPath: `${basePath}/route/history`,
             historyPathTemplate: `${basePath}/route/history/:agentId`,
-            renderChartPath: `${basePath}/route/render-chart`,
             defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
             agents: Object.keys(this.built?.agents ?? {}),
         };
@@ -218,6 +217,10 @@ export class MastraPlugin extends Plugin {
         const memoryBuilder = needsLakebase(this.config)
             ? createMemoryBuilder(this.config, this.context)
             : undefined;
+        this.log.debug("build:start", {
+            lakebase: memoryBuilder !== undefined,
+            stripStaleCharts: this.config.stripStaleCharts !== false,
+        });
         // Build every agent declared in `config.agents` (or the built-in
         // fallback when none are declared). Each agent's `model` resolves
         // workspace URL + bearer at call time so concurrent requests get
@@ -234,7 +237,26 @@ export class MastraPlugin extends Plugin {
         // dev server. Since we're hosting Mastra inside our own Express
         // subapp via `@mastra/express`, custom routes must be passed to
         // the `MastraServer` constructor directly.
-        this.mastra = new Mastra({ agents: this.built.agents });
+        //
+        // `storage` here is *Mastra-instance-level* and persists workflow
+        // snapshots (where suspended `requireApproval` tool calls live).
+        // It's separate from each agent's `Memory.storage`, which only
+        // covers thread / message history. Without it,
+        // `agent.resumeStream()` errors with "could not find a suspended
+        // run" and the approval UI hangs after the user clicks Approve.
+        const instanceStorage = memoryBuilder?.instanceStorage();
+        // Auto-wire OTLP trace export to the sibling `phoenix` plugin if
+        // it's registered. Returns undefined when phoenix isn't around so
+        // the field stays off the constructor and Mastra keeps its noop
+        // observability default. The serviceName is the plugin's bound
+        // name so multiple mastra instances in one process stay
+        // distinguishable in Phoenix.
+        const observability = buildPhoenixObservability(this.context, this.name);
+        this.mastra = new Mastra({
+            agents: this.built.agents,
+            ...(instanceStorage ? { storage: instanceStorage } : {}),
+            ...(observability ? { observability } : {}),
+        });
         this.mastraApp = express();
         attachRoutePatchMiddleware(this.mastraApp);
         this.mastraServer = new MastraServer(this.config, {
@@ -246,10 +268,16 @@ export class MastraPlugin extends Plugin {
                 chatRoute({ path: "/route/chat/:agentId" }),
                 historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
                 historyRoute({ path: "/route/history/:agentId" }),
-                renderChartRoute({ path: "/route/render-chart", config: this.config }),
             ],
         });
         await this.mastraServer.init();
+        this.log.debug("build:done", {
+            agents: Object.keys(this.built.agents),
+            defaultAgent: this.built.defaultAgentId,
+            routes: ["/route/chat", "/route/history", "/models"],
+            instanceStorage: instanceStorage !== undefined,
+            observability: observability !== undefined ? "phoenix" : "off",
+        });
     }
 }
 export const mastra = toPlugin(MastraPlugin);

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

@@ -0,0 +1,29 @@
+/**
+ * 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 type { InputProcessor } from "@mastra/core/processors";
+/**
+ * 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 declare const stripStaleChartsProcessor: InputProcessor;

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 };
+        },
+    });
+}