@dbx-tools/appkit-mastra 0.1.13 → 0.1.19

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 { commonUtils, 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: commonUtils.errorMessage(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: commonUtils.errorMessage(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

@@ -27,7 +27,7 @@
  * 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";
@@ -47,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
@@ -64,7 +64,7 @@ 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

package/dist/src/memory.js

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

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

@@ -1,33 +1,64 @@
 /**
- * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
- * sibling plugin.
+ * Mastra observability wired through the same OTel pipeline AppKit's
+ * built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
  *
- * 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.
+ * How traces flow:
  *
- * 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.
+ * 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 type { pluginUtils } from "@dbx-tools/appkit-shared";
 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[];
+}
 /**
- * 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.
+ * Build a Mastra `Observability` whose spans ride AppKit's global
+ * OTel pipeline via `@mastra/otel-bridge`.
  *
- * 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.
+ * 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 buildPhoenixObservability(context: pluginUtils.PluginContextLike | undefined, serviceName: string): Observability | undefined;
+export declare function buildObservability(options?: BuildObservabilityOptions): Promise<Observability | undefined>;

package/dist/src/observability.js

@@ -1,71 +1,85 @@
 /**
- * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
- * sibling plugin.
+ * Mastra observability wired through the same OTel pipeline AppKit's
+ * built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
  *
- * 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.
+ * How traces flow:
  *
- * 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.
+ * 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 { OtelExporter } from "@mastra/otel-exporter";
-/** Plugin name the phoenix plugin registers under (matches `phoenix()`). */
-const PHOENIX_PLUGIN_NAME = "phoenix";
+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";
 /**
- * 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.
+ * Build a Mastra `Observability` whose spans ride AppKit's global
+ * OTel pipeline via `@mastra/otel-bridge`.
  *
- * 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.
+ * 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 function buildPhoenixObservability(context, serviceName) {
-    const endpoint = readPhoenixEndpoint(context);
-    if (!endpoint)
-        return undefined;
+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: {
-            phoenix: {
+            serviceName: {
                 serviceName,
-                exporters: [
-                    new OtelExporter({
-                        provider: {
-                            custom: {
-                                endpoint,
-                                protocol: "http/protobuf",
-                            },
-                        },
-                    }),
-                ],
+                bridge: new OtelBridge(),
+                requestContextKeys,
             },
         },
     });
 }
-/**
- * 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.js

@@ -27,18 +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 { buildPhoenixObservability } from "./observability.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
@@ -54,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,
             ],
@@ -99,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)
@@ -245,13 +253,12 @@ export class MastraPlugin extends Plugin {
         // `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);
+        // 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 } : {}),
@@ -266,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();
@@ -276,7 +286,7 @@ export class MastraPlugin extends Plugin {
             defaultAgent: this.built.defaultAgentId,
             routes: ["/route/chat", "/route/history", "/models"],
             instanceStorage: instanceStorage !== undefined,
-            observability: observability !== undefined ? "phoenix" : "off",
+            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