@dbx-tools/appkit-mastra 0.1.12 → 0.1.18

package/src/history.ts

@@ -16,7 +16,7 @@
  * session-cookie logic stays the single source of truth in `server.ts`.
  */
 
-import { logUtils } from "@dbx-tools/appkit-shared";
+import { logUtils } from "@dbx-tools/shared";
 import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
 import type { Agent } from "@mastra/core/agent";
 import type { MastraDBMessage } from "@mastra/core/agent/message-list";
@@ -27,6 +27,7 @@ import {
 import { registerApiRoute } from "@mastra/core/server";
 import type { ContextWithMastra } from "@mastra/core/server";
 import type {
+  MastraClearHistoryResponse,
   MastraHistoryResponse,
   MastraHistoryUIMessage,
 } from "@dbx-tools/appkit-mastra-shared";
@@ -108,14 +109,93 @@ export async function loadHistory(
   };
 }
 
+/** Inputs accepted by {@link clearHistory}. */
+export interface ClearHistoryOptions {
+  agent: Agent;
+  threadId: string;
+}
+
+/**
+ * Wipe every persisted message tied to a thread. Returns the count
+ * of messages that were on the thread at delete time so the caller
+ * can render a "cleared N messages" affordance without an
+ * additional round-trip.
+ *
+ * Agents without a configured `Memory` resolve to a no-op (count
+ * 0), matching {@link loadHistory}'s "stateless agents return an
+ * empty page" stance so callers don't have to special-case them.
+ * Threads that don't exist yet are also a successful no-op - the
+ * operation is idempotent so the UI can fire-and-forget without
+ * tracking thread existence.
+ */
+export async function clearHistory(
+  opts: ClearHistoryOptions,
+): Promise<{ cleared: number }> {
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    log.debug("clear:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
+    return { cleared: 0 };
+  }
+  // Mastra's `deleteThread` cascades to the message table, so we
+  // can't ask for a count after the fact. Read it pre-delete with a
+  // one-page recall sized to fit common threads in a single round
+  // trip; the value is for telemetry / UI, not correctness.
+  let cleared = 0;
+  try {
+    const probe = await memory.recall({
+      threadId: opts.threadId,
+      page: 0,
+      perPage: 1,
+    });
+    cleared = probe.total;
+  } catch (err) {
+    // A missing-thread error is the happy-path "nothing to count";
+    // every other error is logged but doesn't block the delete.
+    log.debug("clear:probe-failed", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  const startedAt = Date.now();
+  try {
+    await memory.deleteThread(opts.threadId);
+  } catch (err) {
+    // Mastra's `deleteThread` raises when the thread row was never
+    // created (e.g. clearing an empty session). Surface as a soft
+    // warn and treat as success - the user-facing semantic is
+    // "history is now empty" which is already true.
+    log.warn("clear:delete-soft-failed", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  log.info("clear:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    cleared,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return { cleared };
+}
+
 /** Options accepted by {@link historyRoute}. */
 export type HistoryRouteOptions =
   | { path: `${string}:agentId${string}`; agent?: never }
   | { path: string; agent: string };
 
 /**
- * Register a `GET <path>` Mastra custom API route that returns a page
- * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ * Register the `<path>` Mastra custom API route. Handles two
+ * methods on the same mount:
+ *
+ *   - `GET`: return a page of AI SDK V5 `UIMessage`s for the
+ *     caller's current thread ({@link loadHistory}).
+ *   - `DELETE`: wipe every persisted message on the caller's
+ *     thread ({@link clearHistory}). The session cookie that
+ *     anchors the thread id is left alone so the user keeps the
+ *     same thread - only the contents go away.
  *
  * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
  * fixed-agent mount, or include `:agentId` in the path for dynamic
@@ -134,36 +214,70 @@ export function historyRoute(options: HistoryRouteOptions) {
       "historyRoute path must include `:agentId` or `agent` must be passed explicitly",
     );
   }
-  return registerApiRoute(path, {
-    method: "GET",
-    handler: async (c: ContextWithMastra) => {
-      const mastra = c.get("mastra");
-      const requestContext = c.get("requestContext");
-      const agentId = fixedAgent ?? c.req.param("agentId");
-      if (!agentId) {
-        return c.json({ error: "agentId is required" }, 400);
-      }
-      const agent = mastra.getAgentById(agentId);
-      if (!agent) {
-        return c.json({ error: `Unknown agent "${agentId}"` }, 404);
-      }
-      const threadId = requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
-      if (!threadId) {
-        return c.json({ error: "thread id missing from request context" }, 400);
-      }
-      const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as
-        | string
-        | undefined;
-      const payload = await loadHistory({
-        agent,
-        threadId,
-        ...(resourceId ? { resourceId } : {}),
-        page: parseIntParam(c.req.query("page")),
-        perPage: parseIntParam(c.req.query("perPage")),
-      });
-      return c.json(payload);
-    },
-  });
+  // Tiny resolver shared by GET / DELETE: derive the active agent
+  // and thread id, returning a JSON error response when either is
+  // missing. Keeps both handlers thin and gives them identical
+  // validation behaviour.
+  const resolveContext = (c: ContextWithMastra) => {
+    const mastra = c.get("mastra");
+    const requestContext = c.get("requestContext");
+    const agentId = fixedAgent ?? c.req.param("agentId");
+    if (!agentId) {
+      return { error: c.json({ error: "agentId is required" }, 400) } as const;
+    }
+    const agent = mastra.getAgentById(agentId);
+    if (!agent) {
+      return {
+        error: c.json({ error: `Unknown agent "${agentId}"` }, 404),
+      } as const;
+    }
+    const threadId = requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
+    if (!threadId) {
+      return {
+        error: c.json({ error: "thread id missing from request context" }, 400),
+      } as const;
+    }
+    const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as
+      | string
+      | undefined;
+    return { agentId, agent, threadId, resourceId } as const;
+  };
+
+  return [
+    registerApiRoute(path, {
+      method: "GET",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const payload = await loadHistory({
+          agent: ctx.agent,
+          threadId: ctx.threadId,
+          ...(ctx.resourceId ? { resourceId: ctx.resourceId } : {}),
+          page: parseIntParam(c.req.query("page")),
+          perPage: parseIntParam(c.req.query("perPage")),
+        });
+        return c.json(payload);
+      },
+    }),
+    registerApiRoute(path, {
+      method: "DELETE",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const { cleared } = await clearHistory({
+          agent: ctx.agent,
+          threadId: ctx.threadId,
+        });
+        const payload: MastraClearHistoryResponse = {
+          ok: true,
+          agentId: ctx.agentId,
+          threadId: ctx.threadId,
+          cleared,
+        };
+        return c.json(payload);
+      },
+    }),
+  ];
 }
 
 /** Coerce / clamp `perPage`; falls back to the page-size default. */

package/src/memory.ts

@@ -14,13 +14,21 @@
  *   index is almost always what users want; opt into per-agent recall
  *   by passing a {@link MastraMemoryConfigOverride} on the agent.
  *
+ * Additionally, {@link MemoryBuilder.instanceStorage} returns a
+ * **Mastra-instance-level** `PostgresStore` (schema `mastra_instance`)
+ * used for workflow snapshots - the persistence layer
+ * `agent.resumeStream()` reads from when waking a suspended
+ * `requireApproval` tool call. Per-agent stores are not enough for
+ * this: workflow runs are scoped to the Mastra instance, not an
+ * individual agent's `Memory`.
+ *
  * Plugin-level `config.storage` / `config.memory` act as the baseline
  * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
  * is registered); per-agent settings cascade on top of that.
  */
 
 import { lakebase } from "@databricks/appkit";
-import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
@@ -67,10 +75,10 @@ export function needsLakebase(config: MastraPluginConfig): boolean {
  * condition we can recover from.
  */
 export function resolveLakebasePool(
-  context: pluginUtils.PluginContextLike | undefined,
+  context: appkitUtils.PluginContextLike | undefined,
   caller: MastraPluginConfig,
 ): LakebasePool {
-  return pluginUtils.require(context, lakebase, caller).exports().pool;
+  return appkitUtils.require(context, lakebase, caller).exports().pool;
 }
 
 /**
@@ -80,7 +88,7 @@ export function resolveLakebasePool(
  */
 export function createMemoryBuilder(
   config: MastraPluginConfig,
-  context: pluginUtils.PluginContextLike | undefined,
+  context: appkitUtils.PluginContextLike | undefined,
 ): MemoryBuilder {
   return new MemoryBuilder(config, context);
 }
@@ -96,7 +104,7 @@ export class MemoryBuilder {
 
   constructor(
     private readonly config: MastraPluginConfig,
-    private readonly context: pluginUtils.PluginContextLike | undefined,
+    private readonly context: appkitUtils.PluginContextLike | undefined,
   ) {}
 
   /**
@@ -105,6 +113,34 @@ export class MemoryBuilder {
    * vector store enabled - Mastra accepts a missing `memory` field
    * and treats the agent as stateless.
    */
+  /**
+   * Build the Mastra-instance-level storage used for workflow
+   * snapshots. Returns `undefined` when plugin-level `storage` is
+   * disabled, in which case `agent.resumeStream()` (and therefore
+   * the `requireApproval` flow) will not be available.
+   *
+   * The store lives in a dedicated `mastra_instance` schema so it
+   * never collides with per-agent `mastra_<agentId>` namespaces.
+   * Workflow snapshots are not per-agent state; they belong to the
+   * `Mastra` instance that owns the workflow execution.
+   */
+  instanceStorage(): PostgresStore | undefined {
+    const setting = this.config.storage;
+    if (!setting) return undefined;
+    if (typeof setting === "object") {
+      return new PostgresStore(
+        withId(setting, "mastra-store__instance") as ConstructorParameters<
+          typeof PostgresStore
+        >[0],
+      );
+    }
+    return new PostgresStore({
+      id: "mastra-store__instance",
+      schemaName: "mastra_instance",
+      pool: this.requirePool() as Pool,
+    });
+  }
+
   forAgent(agentId: string, def: MastraAgentDefinition): Memory | undefined {
     const storageSetting = def.storage ?? this.config.storage;
     const memorySetting = def.memory ?? this.config.memory;

package/src/model.ts

@@ -27,10 +27,10 @@
 
 import {
   commonUtils,
-  httpUtils,
   logUtils,
+  netUtils,
   stringUtils,
-} from "@dbx-tools/appkit-shared";
+} from "@dbx-tools/shared";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
 
@@ -390,7 +390,7 @@ const setupFetchInterceptor = commonUtils.memoize((): void => {
   const log = logUtils.logger("mastra/llm");
   const original = globalThis.fetch.bind(globalThis);
   globalThis.fetch = (async (input, init) => {
-    const url = httpUtils.toURL(input);
+    const url = netUtils.parseUrl(input);
     if (
       !url ||
       !url.pathname.startsWith(SERVING_ENDPOINTS_PATH_PREFIX) ||

package/src/observability.ts

@@ -0,0 +1,116 @@
+/**
+ * Mastra observability wired through the same OTel pipeline AppKit's
+ * built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
+ *
+ * How traces flow:
+ *
+ * 1. `@databricks/appkit` boots a global `NodeSDK` in
+ *    `TelemetryManager.initialize()` (during `createApp`) when
+ *    `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the process env.
+ * 2. Every AppKit plugin span (e.g. the `agents` plugin's
+ *    `executeStream`) is created via the global OTel tracer
+ *    (`trace.getTracer(<plugin>)`), so it lands on that NodeSDK and
+ *    is shipped through its OTLP exporter.
+ * 3. The Mastra `OtelBridge` ALSO creates real OTel spans on the same
+ *    global tracer for every Mastra operation (agent runs, model
+ *    calls, tool invocations, workflow steps). They inherit the
+ *    ambient OTel context, so when Mastra is invoked from inside an
+ *    AppKit HTTP span the trace stays connected.
+ *
+ * Net effect: Mastra spans get exactly the treatment AppKit's
+ * `agents` plugin gets. No custom OTLP pipeline lives in this
+ * package; the OTLP endpoint, headers, and resource attributes are
+ * driven by the standard OTel env vars
+ * (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, ...) and consumed
+ * by AppKit's `TelemetryManager`. Set those once and both AppKit and
+ * Mastra spans end up at the same backend.
+ *
+ * When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the bridge's spans go
+ * to the global noop tracer, mirroring how the `agents` plugin
+ * silently no-ops in the same situation.
+ */
+
+import { logUtils, projectUtils } from "@dbx-tools/shared";
+import { Observability } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+
+import { TRACE_REQUEST_CONTEXT_KEYS } from "./config.js";
+
+const log = logUtils.logger("mastra/observability");
+
+const DEFAULT_SERVICE_NAME = "mastra";
+
+export interface BuildObservabilityOptions {
+  /**
+   * Service name attached to the Mastra `Observability` config. Used
+   * as the tracer scope name on bridged OTel spans (the `service.name`
+   * resource attribute is owned by AppKit's `TelemetryManager` instead
+   * - it reads `OTEL_SERVICE_NAME` / `DATABRICKS_APP_NAME` at
+   * `createApp` time).
+   *
+   * Defaults to project name then `"mastra"`.
+   */
+  serviceName?: string;
+  /**
+   * `RequestContext` keys to extract as span metadata on every Mastra
+   * trace. Defaults to {@link TRACE_REQUEST_CONTEXT_KEYS} (user id,
+   * thread id, request id, environment, model override, ...).
+   *
+   * Supports dot notation for nested values per the Mastra docs.
+   */
+  requestContextKeys?: readonly string[];
+}
+
+/**
+ * Build a Mastra `Observability` whose spans ride AppKit's global
+ * OTel pipeline via `@mastra/otel-bridge`.
+ *
+ * Returns `undefined` only if someone explicitly opts out in the
+ * future; today it always returns an `Observability` because the
+ * bridge degrades gracefully (no-op tracer) when no global OTel SDK
+ * is registered. Callers can spread `...(observability ? { observability } : {})`
+ * either way to stay forward-compatible.
+ */
+export async function buildObservability(
+  options?: BuildObservabilityOptions,
+): Promise<Observability | undefined> {
+  const serviceName =
+    options?.serviceName ??
+    (await projectUtils.name()) ??
+    DEFAULT_SERVICE_NAME;
+  const requestContextKeys = [
+    ...(options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS),
+  ];
+
+  // The OTel HTTP exporter treats `OTEL_EXPORTER_OTLP_ENDPOINT` as a
+  // *base* URL and appends the signal path itself (e.g.
+  // `http://localhost:6006` -> `http://localhost:6006/v1/traces`). Log
+  // the resolved POST URL so misconfigurations (e.g. accidentally
+  // setting the base var to a `/v1/traces`-suffixed URL, which makes
+  // the SDK POST to `.../v1/traces/v1/traces` and Phoenix 404s) are
+  // obvious in startup output.
+  const otelBase = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  const otelTracesOverride = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+  const resolvedTracesUrl = otelTracesOverride
+    ? otelTracesOverride
+    : otelBase
+      ? `${otelBase.replace(/\/+$/, "")}/v1/traces`
+      : undefined;
+  log.info("Mastra observability wired through OTel bridge", {
+    serviceName,
+    requestContextKeys,
+    otelBase: otelBase ?? "<unset>",
+    resolvedTracesUrl: resolvedTracesUrl ?? "<noop; OTLP endpoint unset>",
+  });
+
+  return new Observability({
+    configs: {
+      serviceName: {
+        serviceName,
+        bridge: new OtelBridge(),
+        requestContextKeys,
+      },
+    },
+  });
+}

package/src/plugin.ts

@@ -37,7 +37,7 @@ import {
   type PluginManifest,
   type ResourceRequirement,
 } from "@databricks/appkit";
-import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import { chatRoute } from "@mastra/ai-sdk";
 import type { Agent } from "@mastra/core/agent";
 import { Mastra } from "@mastra/core/mastra";
@@ -48,6 +48,7 @@ import type { MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
 import type { MastraPluginConfig } from "./config.js";
 import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
+import { buildObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import {
   clearServingEndpointsCache,
@@ -56,8 +57,8 @@ import {
   type ServingEndpointSummary,
 } from "./serving.js";
 
-const GENIE_MANIFEST = pluginUtils.data(genie).plugin.manifest;
-const LAKEBASE_MANIFEST = pluginUtils.data(lakebase).plugin.manifest;
+const GENIE_MANIFEST = appkitUtils.data(genie).plugin.manifest;
+const LAKEBASE_MANIFEST = appkitUtils.data(lakebase).plugin.manifest;
 
 /**
  * AppKit plugin (registered name: `mastra`) that hosts Mastra agents
@@ -75,6 +76,14 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     resources: {
       required: [],
       optional: [
+        // Surface the Genie resource binding (space id) declared by
+        // AppKit's `genie` plugin manifest. The Mastra plugin no
+        // longer uses the genie plugin's tools at runtime - the
+        // built-in Genie agent talks to Genie directly via
+        // `@dbx-tools/genie` - but reusing the manifest keeps the
+        // resource-binding shape identical to AppKit's so existing
+        // `app.yaml` configs and `genie({ spaces })` wiring keep
+        // working without change.
         ...GENIE_MANIFEST.resources.required,
         ...LAKEBASE_MANIFEST.resources.required,
       ],
@@ -125,7 +134,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
    * already in the registry by the time this fires.
    */
   private applyLakebaseAutoDefaults(): void {
-    const hasLakebase = pluginUtils.instance(this.context, lakebase) !== undefined;
+    const hasLakebase = appkitUtils.instance(this.context, lakebase) !== undefined;
     if (!hasLakebase) return;
     if (this.config.storage === undefined) this.config.storage = true;
     if (this.config.memory === undefined) this.config.memory = true;
@@ -271,7 +280,25 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // 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();
+    // Wire Mastra's tracer into AppKit's global OTel pipeline via
+    // `@mastra/otel-bridge`. Mastra spans become native OTel spans on
+    // whatever tracer provider `TelemetryManager` registered during
+    // `createApp`, so the OTLP endpoint / headers / sampling are
+    // env-driven and shared with every other AppKit plugin.
+    const observability = await buildObservability({ serviceName: 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, {
@@ -281,8 +308,11 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       customApiRoutes: [
         chatRoute({ path: "/route/chat", agent: this.built.defaultAgentId }),
         chatRoute({ path: "/route/chat/:agentId" }),
-        historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
-        historyRoute({ path: "/route/history/:agentId" }),
+        // `historyRoute` registers both GET (load) and DELETE
+        // (clear) on the same path, so it returns an array we
+        // splice in.
+        ...historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
+        ...historyRoute({ path: "/route/history/:agentId" }),
       ],
     });
     await this.mastraServer.init();
@@ -290,6 +320,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       agents: Object.keys(this.built.agents),
       defaultAgent: this.built.defaultAgentId,
       routes: ["/route/chat", "/route/history", "/models"],
+      instanceStorage: instanceStorage !== undefined,
+      observability: observability !== undefined ? "mlflow" : "off",
     });
   }
 }

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

@@ -20,7 +20,7 @@
  * uniformly without coupling to specific tool ids.
  */
 
-import { logUtils } from "@dbx-tools/appkit-shared";
+import { logUtils } from "@dbx-tools/shared";
 import type {
   InputProcessor,
   ProcessInputArgs,

package/src/server.ts

@@ -6,7 +6,7 @@
  */
 
 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,
@@ -16,7 +16,14 @@ import { MastraServer as MastraServerExpress } from "@mastra/express";
 import type express from "express";
 import { randomUUID } from "node:crypto";
 
-import { MASTRA_USER_KEY, type MastraPluginConfig, type User } from "./config.js";
+import {
+  MASTRA_REQUEST_ID_KEY,
+  MASTRA_USER_EMAIL_KEY,
+  MASTRA_USER_KEY,
+  MASTRA_USER_NAME_KEY,
+  type MastraPluginConfig,
+  type User,
+} from "./config.js";
 import {
   extractModelOverride,
   MASTRA_MODEL_OVERRIDE_KEY,
@@ -46,11 +53,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`.
@@ -76,6 +87,42 @@ 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: express.Request,
+    res: express.Response,
+    requestContext: 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(

package/src/serving.ts

@@ -21,7 +21,7 @@
  */
 
 import { CacheManager, type getExecutionContext } from "@databricks/appkit";
-import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/shared";
 import Fuse from "fuse.js";
 
 import type { ServingEndpointSummary } from "@dbx-tools/appkit-mastra-shared";

package/src/tools/email.ts

@@ -26,7 +26,7 @@
  * 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";