@dbx-tools/appkit-mastra 0.1.12 → 0.1.13

package/README.md

@@ -582,10 +582,10 @@ the moment the `lakebase` plugin is registered. Bare `mastra()` next to
 zero extra config required.
 
 
-| Knob      | Default when `lakebase()` is registered                                                                           | What it backs                                              |
-| --------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `storage` | **Per-agent** `PostgresStore` namespaced by `schemaName: "mastra_<agentId>"` so threads + messages stay isolated. | Mastra threads, messages, working memory.                  |
-| `memory`  | **Shared singleton** `PgVector` across every agent (cross-agent semantic recall on one index).                    | RAG-style recall over past messages via FastEmbed vectors. |
+| Knob      | Default when `lakebase()` is registered                                                                           | What it backs                                                                                  |
+| --------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `storage` | **Per-agent** `PostgresStore` namespaced by `schemaName: "mastra_<agentId>"` so threads + messages stay isolated, plus a Mastra-instance-level `PostgresStore` in schema `mastra_instance`. | Mastra threads, messages, working memory; Mastra-instance-level workflow snapshots (`requireApproval` / `agent.resumeStream()`). |
+| `memory`  | **Shared singleton** `PgVector` across every agent (cross-agent semantic recall on one index).                    | RAG-style recall over past messages via FastEmbed vectors.                                     |
 
 
 Override either at the plugin level, the agent level, or both. The agent
@@ -635,8 +635,15 @@ mastra({
 Notes:
 
 - `PostgresStore` runs `CREATE SCHEMA IF NOT EXISTS` on `init()`, so
-per-agent schemas spring into existence the first time an agent saves
-a message. No bundle / migration step required.
+per-agent schemas (and the shared `mastra_instance` schema) spring
+into existence the first time the agent saves anything. No bundle /
+migration step required.
+- The `mastra_instance` schema exists so that Mastra-instance-level
+artifacts (workflow snapshots used by `agent.resumeStream()`,
+`requireApproval` flows, etc.) live in their own namespace and never
+collide with per-agent thread / message tables. Disable the instance
+store by setting `storage: false` at plugin level - approval-gated
+tool calls will then error on resume.
 - Disabling `lakebase()` from your plugin list while leaving `storage` /
 `memory` truthy fails fast at setup with a clear "lakebase plugin not
 registered" error.

package/dist/src/memory.d.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.
@@ -21,6 +29,7 @@
 import { lakebase } from "@databricks/appkit";
 import { pluginUtils } from "@dbx-tools/appkit-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`. */
@@ -62,6 +71,18 @@ export declare 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;
     forAgent(agentId: string, def: MastraAgentDefinition): Memory | undefined;
     private buildStorage;
     /**

package/dist/src/memory.js

@@ -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.
@@ -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/observability.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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";
+/**
+ * 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 declare function buildPhoenixObservability(context: pluginUtils.PluginContextLike | undefined, serviceName: string): Observability | undefined;

package/dist/src/observability.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { Observability } from "@mastra/observability";
+import { OtelExporter } from "@mastra/otel-exporter";
+/** Plugin name the phoenix plugin registers under (matches `phoenix()`). */
+const PHOENIX_PLUGIN_NAME = "phoenix";
+/**
+ * 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, serviceName) {
+    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) {
+    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

@@ -34,6 +34,7 @@ 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 { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
 const GENIE_MANIFEST = pluginUtils.data(genie).plugin.manifest;
@@ -236,7 +237,26 @@ 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();
+        // 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, {
@@ -255,6 +275,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 ? "phoenix" : "off",
         });
     }
 }