@dbx-tools/appkit-mastra 0.1.13 → 0.1.19

package/dist/src/server.d.ts

@@ -19,6 +19,18 @@ export declare class MastraServer extends MastraServerExpress {
     constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServerExpress>);
     registerAuthMiddleware(): void;
     configureRequestContextUser(requestContext: RequestContext): void;
+    /**
+     * Stamp a per-request id and echo it on the response so an upstream
+     * proxy / curl client / browser-side log line can pair its view of
+     * the request with the matching trace span. Reuses `X-Request-Id`
+     * when the upstream already supplies one so multi-hop traces stay
+     * joined; otherwise mints a UUIDv4.
+     *
+     * The id is surfaced as `mastra__requestId` span metadata via
+     * {@link TRACE_REQUEST_CONTEXT_KEYS} and as the `X-Request-Id`
+     * response header so dev tools can copy it from either side.
+     */
+    configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
     configureRequestContextThreadId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
     configureRequestContextModelOverride(req: express.Request, requestContext: RequestContext): void;
 }

package/dist/src/server.js

@@ -5,11 +5,11 @@
  * point.
  */
 import { getExecutionContext } from "@databricks/appkit";
-import { httpUtils, logUtils, stringUtils } from "@dbx-tools/appkit-shared";
+import { httpUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
 import { MastraServer as MastraServerExpress } from "@mastra/express";
 import { randomUUID } from "node:crypto";
-import { MASTRA_USER_KEY } from "./config.js";
+import { MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, } from "./config.js";
 import { extractModelOverride, MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig, } from "./serving.js";
 /**
  * `@mastra/express` subclass that stamps `RequestContext` with the
@@ -31,11 +31,15 @@ export class MastraServer extends MastraServerExpress {
             this.configureRequestContextUser(requestContext);
             this.configureRequestContextThreadId(req, res, requestContext);
             this.configureRequestContextModelOverride(req, requestContext);
+            this.configureRequestContextRequestId(req, res, requestContext);
             this.log.debug("auth:middleware", {
                 method: req.method,
                 path: req.path,
+                requestId: requestContext.get(MASTRA_REQUEST_ID_KEY),
                 threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
                 resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
+                userName: requestContext.get(MASTRA_USER_NAME_KEY),
+                userEmail: requestContext.get(MASTRA_USER_EMAIL_KEY),
                 modelOverride: requestContext.get(
                 // imported below; logged so a misrouted request shows
                 // up alongside its model selection in `LOG_LEVEL=debug`.
@@ -56,6 +60,38 @@ export class MastraServer extends MastraServerExpress {
         };
         requestContext.set(MASTRA_USER_KEY, user);
         requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+        // AppKit's `UserContext` surfaces display name / email only on
+        // OBO requests. Service-context calls (background tasks, server
+        // start-up) leave these undefined and we skip the stamp so
+        // downstream trace metadata stays absent rather than empty.
+        if ("isUserContext" in executionContext) {
+            if (executionContext.userName) {
+                requestContext.set(MASTRA_USER_NAME_KEY, executionContext.userName);
+            }
+            if (executionContext.userEmail) {
+                requestContext.set(MASTRA_USER_EMAIL_KEY, executionContext.userEmail);
+            }
+        }
+    }
+    /**
+     * Stamp a per-request id and echo it on the response so an upstream
+     * proxy / curl client / browser-side log line can pair its view of
+     * the request with the matching trace span. Reuses `X-Request-Id`
+     * when the upstream already supplies one so multi-hop traces stay
+     * joined; otherwise mints a UUIDv4.
+     *
+     * The id is surfaced as `mastra__requestId` span metadata via
+     * {@link TRACE_REQUEST_CONTEXT_KEYS} and as the `X-Request-Id`
+     * response header so dev tools can copy it from either side.
+     */
+    configureRequestContextRequestId(req, res, requestContext) {
+        if (requestContext.get(MASTRA_REQUEST_ID_KEY))
+            return;
+        const headerValue = req.headers["x-request-id"];
+        const upstream = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+        const requestId = upstream?.trim() || randomUUID();
+        requestContext.set(MASTRA_REQUEST_ID_KEY, requestId);
+        res.setHeader("X-Request-Id", requestId);
     }
     configureRequestContextThreadId(req, res, requestContext) {
         if (requestContext.get(MASTRA_THREAD_ID_KEY))

package/dist/src/serving.js

@@ -20,7 +20,7 @@
  * `plugin.ts` exposes the cached list at `GET /models`.
  */
 import { CacheManager } from "@databricks/appkit";
-import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/shared";
 import Fuse from "fuse.js";
 const log = logUtils.logger("mastra/serving");
 /**

package/dist/src/tools/email.js

@@ -25,7 +25,7 @@
  * 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 { logUtils, stringUtils } from "@dbx-tools/shared";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 const log = logUtils.logger("mastra/tool/send-email");

package/dist/src/writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared helper for publishing events through Mastra's
+ * `ctx.writer`. Centralizes the "the downstream stream may already
+ * be closed, don't take the whole tool down" pattern that the
+ * Genie agent and chart tool both need.
+ *
+ * Failures are logged at `warn` (a persistently-closed writer is
+ * the most likely culprit when events go missing client-side) but
+ * swallowed so a cancelled request or a client that navigated
+ * away can't crash a tool mid-flight.
+ */
+import type { MinimalWriter } from "@dbx-tools/appkit-mastra-shared";
+import { type logUtils } from "@dbx-tools/shared";
+/**
+ * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * caught errors are logged via `log.warn("writer:error", ...)`
+ * along with any caller-supplied `context` fields (e.g. a
+ * `chartId` or `messageId`) so the warning is greppable per
+ * resource.
+ *
+ * Returns when the write resolves or rejects; never throws.
+ */
+export declare function safeWrite(log: logUtils.Logger, writer: MinimalWriter | undefined, chunk: unknown, context?: Record<string, unknown>): Promise<void>;

package/dist/src/writer.js

@@ -0,0 +1,37 @@
+/**
+ * Shared helper for publishing events through Mastra's
+ * `ctx.writer`. Centralizes the "the downstream stream may already
+ * be closed, don't take the whole tool down" pattern that the
+ * Genie agent and chart tool both need.
+ *
+ * Failures are logged at `warn` (a persistently-closed writer is
+ * the most likely culprit when events go missing client-side) but
+ * swallowed so a cancelled request or a client that navigated
+ * away can't crash a tool mid-flight.
+ */
+import { commonUtils } from "@dbx-tools/shared";
+/**
+ * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * caught errors are logged via `log.warn("writer:error", ...)`
+ * along with any caller-supplied `context` fields (e.g. a
+ * `chartId` or `messageId`) so the warning is greppable per
+ * resource.
+ *
+ * Returns when the write resolves or rejects; never throws.
+ */
+export async function safeWrite(log, writer, chunk, context = {}) {
+    if (!writer) {
+        log.debug("writer:no-writer", context);
+        return;
+    }
+    try {
+        await writer.write(chunk);
+        log.debug("writer:ok", context);
+    }
+    catch (err) {
+        log.warn("writer:error", {
+            ...context,
+            error: commonUtils.errorMessage(err),
+        });
+    }
+}