@dbx-tools/appkit-mastra 0.1.12 → 0.1.18

package/dist/src/history.d.ts

@@ -43,6 +43,27 @@ export interface LoadHistoryOptions {
  * without sorting locally.
  */
 export declare function loadHistory(opts: LoadHistoryOptions): Promise<MastraHistoryResponse>;
+/** 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 declare function clearHistory(opts: ClearHistoryOptions): Promise<{
+    cleared: number;
+}>;
 /** Options accepted by {@link historyRoute}. */
 export type HistoryRouteOptions = {
     path: `${string}:agentId${string}`;
@@ -52,8 +73,15 @@ export type HistoryRouteOptions = {
     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
@@ -64,4 +92,4 @@ export type HistoryRouteOptions = {
  * (populated upstream by `MastraServer.registerAuthMiddleware`), so
  * no cookie or user lookups happen here.
  */
-export declare function historyRoute(options: HistoryRouteOptions): import("@mastra/core/server").ApiRoute;
+export declare function historyRoute(options: HistoryRouteOptions): import("@mastra/core/server").ApiRoute[];

package/dist/src/history.js

@@ -15,7 +15,7 @@
  * the handler runs - no cookie or user lookups happen here, and the
  * 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 { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
 import { registerApiRoute } from "@mastra/core/server";
@@ -79,8 +79,79 @@ export async function loadHistory(opts) {
     };
 }
 /**
- * Register a `GET <path>` Mastra custom API route that returns a page
- * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ * 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) {
+    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 };
+}
+/**
+ * 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
@@ -97,34 +168,69 @@ export function historyRoute(options) {
     if (!fixedAgent && !path.includes(":agentId")) {
         throw new Error("historyRoute path must include `:agentId` or `agent` must be passed explicitly");
     }
-    return registerApiRoute(path, {
-        method: "GET",
-        handler: async (c) => {
-            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);
-            if (!threadId) {
-                return c.json({ error: "thread id missing from request context" }, 400);
-            }
-            const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY);
-            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) => {
+        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) };
+        }
+        const agent = mastra.getAgentById(agentId);
+        if (!agent) {
+            return {
+                error: c.json({ error: `Unknown agent "${agentId}"` }, 404),
+            };
+        }
+        const threadId = requestContext.get(MASTRA_THREAD_ID_KEY);
+        if (!threadId) {
+            return {
+                error: c.json({ error: "thread id missing from request context" }, 400),
+            };
+        }
+        const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY);
+        return { agentId, agent, threadId, resourceId };
+    };
+    return [
+        registerApiRoute(path, {
+            method: "GET",
+            handler: async (c) => {
+                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) => {
+                const ctx = resolveContext(c);
+                if ("error" in ctx)
+                    return ctx.error;
+                const { cleared } = await clearHistory({
+                    agent: ctx.agent,
+                    threadId: ctx.threadId,
+                });
+                const payload = {
+                    ok: true,
+                    agentId: ctx.agentId,
+                    threadId: ctx.threadId,
+                    cleared,
+                };
+                return c.json(payload);
+            },
+        }),
+    ];
 }
 /** Coerce / clamp `perPage`; falls back to the page-size default. */
 function clampPerPage(value) {

package/dist/src/memory.d.ts

@@ -14,13 +14,22 @@
  *   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 { pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils } from "@dbx-tools/shared";
 import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
 import type { MastraAgentDefinition } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
 /** Pool handle returned by the AppKit `lakebase` plugin `exports().pool`. */
@@ -38,13 +47,13 @@ export declare function needsLakebase(config: MastraPluginConfig): boolean;
  * `storage` / `memory` without lakebase is a wiring bug, not a runtime
  * condition we can recover from.
  */
-export declare function resolveLakebasePool(context: pluginUtils.PluginContextLike | undefined, caller: MastraPluginConfig): LakebasePool;
+export declare function resolveLakebasePool(context: appkitUtils.PluginContextLike | undefined, caller: MastraPluginConfig): LakebasePool;
 /**
  * Construct a per-agent {@link Memory} factory. Caches the shared
  * `PgVector` singleton (built on first need) and the lazily-resolved
  * Lakebase pool so each agent build is O(1) after the first.
  */
-export declare function createMemoryBuilder(config: MastraPluginConfig, context: pluginUtils.PluginContextLike | undefined): MemoryBuilder;
+export declare function createMemoryBuilder(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): MemoryBuilder;
 /**
  * Builds one `Memory` per agent. Per-instance state keeps the shared
  * `PgVector` and the resolved Lakebase pool alive across calls so
@@ -55,13 +64,25 @@ export declare class MemoryBuilder {
     private readonly context;
     private sharedVector;
     private pool;
-    constructor(config: MastraPluginConfig, context: pluginUtils.PluginContextLike | undefined);
+    constructor(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined);
     /**
      * Build a `Memory` for `agentId` after the plugin/agent cascade.
      * Returns `undefined` when the agent has neither storage nor a
      * 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;
     forAgent(agentId: string, def: MastraAgentDefinition): Memory | undefined;
     private buildStorage;
     /**

package/dist/src/memory.js

@@ -14,12 +14,20 @@
  *   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";
@@ -46,7 +54,7 @@ export function needsLakebase(config) {
  * condition we can recover from.
  */
 export function resolveLakebasePool(context, caller) {
-    return pluginUtils.require(context, lakebase, caller).exports().pool;
+    return appkitUtils.require(context, lakebase, caller).exports().pool;
 }
 /**
  * Construct a per-agent {@link Memory} factory. Caches the shared
@@ -76,6 +84,30 @@ 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() {
+        const setting = this.config.storage;
+        if (!setting)
+            return undefined;
+        if (typeof setting === "object") {
+            return new PostgresStore(withId(setting, "mastra-store__instance"));
+        }
+        return new PostgresStore({
+            id: "mastra-store__instance",
+            schemaName: "mastra_instance",
+            pool: this.requirePool(),
+        });
+    }
     forAgent(agentId, def) {
         const storageSetting = def.storage ?? this.config.storage;
         const memorySetting = def.memory ?? this.config.memory;

package/dist/src/model.js

@@ -24,7 +24,7 @@
  * (network blip, expired token at cache-fill time) we fall back to
  * the input verbatim and let Databricks return the canonical error.
  */
-import { commonUtils, httpUtils, logUtils, stringUtils, } from "@dbx-tools/appkit-shared";
+import { commonUtils, logUtils, netUtils, stringUtils, } from "@dbx-tools/shared";
 import { MASTRA_USER_KEY } from "./config.js";
 import { listServingEndpoints, MASTRA_MODEL_OVERRIDE_KEY, resolveModelId, resolveServingConfig, } from "./serving.js";
 /**
@@ -325,7 +325,7 @@ const setupFetchInterceptor = commonUtils.memoize(() => {
     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) ||
             typeof init?.body !== "string") {

package/dist/src/observability.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { Observability } from "@mastra/observability";
+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 declare function buildObservability(options?: BuildObservabilityOptions): Promise<Observability | undefined>;

package/dist/src/observability.js

@@ -0,0 +1,85 @@
+/**
+ * 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";
+/**
+ * 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) {
+    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/dist/src/plugin.js

@@ -27,17 +27,18 @@
  *   AI SDK transport URL is `/api/mastra/route/chat/<agentId>`.
  */
 import { genie, getExecutionContext, lakebase, Plugin, toPlugin, } 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 { Mastra } from "@mastra/core/mastra";
 import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.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, listServingEndpoints, resolveServingConfig, } 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
  * with optional Lakebase-backed memory and AI SDK chat routes under
@@ -53,6 +54,14 @@ export class MastraPlugin extends Plugin {
         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,
             ],
@@ -98,7 +107,7 @@ export class MastraPlugin extends Plugin {
      * already in the registry by the time this fires.
      */
     applyLakebaseAutoDefaults() {
-        const hasLakebase = pluginUtils.instance(this.context, lakebase) !== undefined;
+        const hasLakebase = appkitUtils.instance(this.context, lakebase) !== undefined;
         if (!hasLakebase)
             return;
         if (this.config.storage === undefined)
@@ -236,7 +245,25 @@ 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();
+        // 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, {
@@ -246,8 +273,11 @@ export class MastraPlugin extends Plugin {
             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();
@@ -255,6 +285,8 @@ export class MastraPlugin extends Plugin {
             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/dist/src/processors/strip-stale-charts.js

@@ -19,7 +19,7 @@
  * `datasets[].chartId` and `render_data`'s top-level `chartId`
  * uniformly without coupling to specific tool ids.
  */
-import { logUtils } from "@dbx-tools/appkit-shared";
+import { logUtils } from "@dbx-tools/shared";
 const log = logUtils.logger("mastra/processor/strip-stale-charts");
 /**
  * Recursively clone `value`, omitting any property whose key is

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;
 }