@dbx-tools/appkit-mastra 0.1.4 → 0.1.12

package/dist/src/server.js

@@ -27,55 +27,69 @@ export class MastraServer extends MastraServerExpress {
     registerAuthMiddleware() {
         super.registerAuthMiddleware();
         this.app.use((req, res, next) => {
-            const executionContext = getExecutionContext();
-            const user = {
-                id: "userId" in executionContext
-                    ? executionContext.userId
-                    : executionContext.serviceUserId,
-                executionContext,
-            };
             const requestContext = res.locals.requestContext;
-            requestContext.set(MASTRA_USER_KEY, user);
-            if (!requestContext.get(MASTRA_RESOURCE_ID_KEY)) {
-                this.log.debug(`Setting resource id: ${user.id}`);
-                requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
-            }
-            const cookies = httpUtils.parseCookies(req.headers.cookie);
-            const cookieName = stringUtils.toIdentifierWithOptions({ delimiter: "_", distinct: true }, "appkit", this.config.name, "sessionId");
-            let sessionId = cookies[cookieName];
-            if (!sessionId) {
-                sessionId = randomUUID();
-                res.cookie(cookieName, sessionId, {
-                    httpOnly: true,
-                    sameSite: "lax",
-                    secure: req.secure,
-                    path: "/",
-                });
-            }
-            res.locals.sessionId = sessionId;
-            if (!requestContext.get(MASTRA_THREAD_ID_KEY)) {
-                this.log.debug(`Setting thread id: ${sessionId}`);
-                requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
-            }
-            // Per-request model override: only honored when the plugin
-            // opts in (default). Sources, in priority order, are
-            // `X-Mastra-Model` header, `?model=` query, and `model` /
-            // `modelId` body field; see `serving.ts`.
-            const serving = resolveServingConfig(this.config);
-            if (serving.allowOverride) {
-                const override = extractModelOverride({
-                    headers: req.headers,
-                    query: req.query,
-                    body: req.body,
-                });
-                if (override) {
-                    this.log.debug(`Model override: ${override}`);
-                    requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
-                }
-            }
+            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();
         });
     }
+    configureRequestContextUser(requestContext) {
+        if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key)))
+            return;
+        const executionContext = getExecutionContext();
+        const user = {
+            id: "userId" in executionContext
+                ? executionContext.userId
+                : executionContext.serviceUserId,
+            executionContext,
+        };
+        requestContext.set(MASTRA_USER_KEY, user);
+        requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+    }
+    configureRequestContextThreadId(req, res, requestContext) {
+        if (requestContext.get(MASTRA_THREAD_ID_KEY))
+            return;
+        const cookies = httpUtils.parseCookies(req.headers.cookie);
+        const cookieName = stringUtils.toIdentifierWithOptions({ delimiter: "_", distinct: true }, "appkit", this.config.name, "sessionId");
+        let sessionId = cookies[cookieName];
+        if (!sessionId) {
+            sessionId = randomUUID();
+            res.cookie(cookieName, sessionId, {
+                httpOnly: true,
+                sameSite: "lax",
+                secure: req.secure,
+                path: "/",
+            });
+        }
+        requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
+    }
+    configureRequestContextModelOverride(req, requestContext) {
+        // Per-request model override: only honored when the plugin
+        // opts in (default). Sources, in priority order, are
+        // `X-Mastra-Model` header, `?model=` query, and `model` /
+        // `modelId` body field; see `serving.ts`.
+        const serving = resolveServingConfig(this.config);
+        if (serving.allowOverride) {
+            const override = extractModelOverride({
+                headers: req.headers,
+                query: req.query,
+                body: req.body,
+            });
+            if (override)
+                requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
+        }
+    }
 }
 /**
  * Patches around `@mastra/express`'s custom-route dispatcher so

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