@dbx-tools/appkit-mastra 0.1.12 → 0.1.13

package/package.json

@@ -9,17 +9,19 @@
     }
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "module": "index.ts",
   "dependencies": {
-    "@dbx-tools/appkit-mastra-shared": "0.1.12",
-    "@dbx-tools/appkit-shared": "0.1.12",
+    "@dbx-tools/appkit-mastra-shared": "0.1.13",
+    "@dbx-tools/appkit-shared": "0.1.13",
     "@mastra/ai-sdk": "^1.3",
     "@mastra/core": "^1.32",
     "@mastra/express": "^1.3",
     "@mastra/fastembed": "^1.0",
     "@mastra/memory": "^1.17",
+    "@mastra/observability": "^0.0.0-graph-crash-v3-20260528202217",
+    "@mastra/otel-exporter": "^0.0.0-graph-crash-v3-20260528202217",
     "@mastra/pg": "^1.10",
     "fuse.js": "^7.0.0",
     "zod": "^4.3.6"

package/src/memory.ts

@@ -14,6 +14,14 @@
  *   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.
@@ -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/observability.ts

@@ -0,0 +1,92 @@
+/**
+ * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
+ * sibling plugin.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import type { pluginUtils } from "@dbx-tools/appkit-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";
+
+/** Structural shape of the bits of `phoenix().exports()` we touch. */
+interface PhoenixExportsLike {
+  collectorEndpoint?(): string | undefined;
+}
+
+/** Structural shape of an AppKit plugin instance with `exports()`. */
+interface PluginWithExports {
+  exports?(): unknown;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function buildPhoenixObservability(
+  context: pluginUtils.PluginContextLike | undefined,
+  serviceName: string,
+): Observability | undefined {
+  const endpoint = readPhoenixEndpoint(context);
+  if (!endpoint) return undefined;
+
+  return new Observability({
+    configs: {
+      phoenix: {
+        serviceName,
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint,
+                protocol: "http/protobuf",
+              },
+            },
+          }),
+        ],
+      },
+    },
+  });
+}
+
+/**
+ * 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: pluginUtils.PluginContextLike | undefined,
+): string | undefined {
+  if (!context) return undefined;
+  const plugin = context.getPlugins().get(PHOENIX_PLUGIN_NAME) as
+    | PluginWithExports
+    | undefined;
+  const exports_ = plugin?.exports?.() as PhoenixExportsLike | undefined;
+  const url = exports_?.collectorEndpoint?.();
+  return typeof url === "string" ? url : undefined;
+}

package/src/plugin.ts

@@ -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 { buildPhoenixObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import {
   clearServingEndpointsCache,
@@ -271,7 +272,26 @@ 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();
+    // 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);
+    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, {
@@ -290,6 +310,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 ? "phoenix" : "off",
     });
   }
 }