@dbx-tools/appkit-mastra 0.1.82 → 0.1.83

package/dist/index.d.ts

@@ -474,6 +474,19 @@ interface MastraPluginConfig extends BasePluginConfig {
    * to drill deep into a dataset within a single turn.
    */
   agentMaxSteps?: number;
+  /**
+   * Wire Mastra spans into AppKit's global OTel pipeline via
+   * `@mastra/otel-bridge`.
+   *
+   * - `undefined` (default, auto): on only when
+   *   `OTEL_EXPORTER_OTLP_ENDPOINT` or
+   *   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set. When unset, the
+   *   bridge is skipped so Mastra does not log
+   *   `[OtelBridge] No OTEL span found` on the noop tracer.
+   * - `true`: force on even without an OTLP endpoint.
+   * - `false`: force off.
+   */
+  observability?: boolean;
   /**
    * Log user feedback (thumbs up/down + freeform comments) to MLflow as
    * trace assessments, and surface the feedback controls in the chat UI.
@@ -889,6 +902,11 @@ declare function buildAgents(opts: {
   memoryBuilder?: MemoryBuilder;
   log: logUtils.Logger;
 }): Promise<BuiltAgents>;
+/**
+ * Tool ids on `tools` that are approval-gated (`requireApproval: true`).
+ * Keys are used as a fallback when a tool omits an explicit `id`.
+ */
+declare function approvalGatedToolIds(tools: MastraTools): string[];
 //#endregion
 //#region packages/appkit-mastra/src/chart.d.ts
 /**
@@ -1386,4 +1404,4 @@ declare function buildSummarizeTool(config: MastraPluginConfig): _mastra_core_to
   maxWords?: number | undefined;
 }, unknown, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "summarize", unknown>;
 //#endregion
-export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraAgentDefinition, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, type SummarizeOptions, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };
+export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraAgentDefinition, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, type SummarizeOptions, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, approvalGatedToolIds, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };

package/dist/index.js

@@ -2188,8 +2188,14 @@ async function buildAgents(opts) {
 	const outputProcessors = [new ResultProcessor()];
 	const inputProcessors = [...config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor]];
 	const agents = {};
+	const approvalGatedByAgent = [];
 	for (const [id, def] of Object.entries(definitions)) {
 		const tools = await resolveTools(def.tools, plugins, ambientTools);
+		const gated = approvalGatedToolIds(tools);
+		if (gated.length > 0) approvalGatedByAgent.push({
+			agentId: id,
+			toolIds: gated
+		});
 		const memory = memoryBuilder?.forAgent(id, def);
 		agents[id] = new Agent({
 			id,
@@ -2211,6 +2217,7 @@ async function buildAgents(opts) {
 		});
 	}
 	if (!agents[defaultAgentId]) throw new Error(`mastra: defaultAgent "${defaultAgentId}" not found in registered agents (${ids.join(", ") || "none"})`);
+	assertApprovalGatedToolsHaveStorage(approvalGatedByAgent, memoryBuilder);
 	log.info("agents ready", {
 		ids,
 		defaultAgentId
@@ -2222,6 +2229,40 @@ async function buildAgents(opts) {
 	};
 }
 /**
+* Tool ids on `tools` that are approval-gated (`requireApproval: true`).
+* Keys are used as a fallback when a tool omits an explicit `id`.
+*/
+function approvalGatedToolIds(tools) {
+	if (!tools || typeof tools !== "object") return [];
+	const ids = [];
+	for (const [key, tool] of Object.entries(tools)) {
+		if (!isApprovalGatedTool(tool)) continue;
+		ids.push(resolveToolId(tool, key));
+	}
+	return ids;
+}
+/** True when a Mastra / AI SDK tool pauses for human approval before execute. */
+function isApprovalGatedTool(tool) {
+	if (!tool || typeof tool !== "object") return false;
+	return tool.requireApproval === true;
+}
+function resolveToolId(tool, fallbackKey) {
+	if (tool && typeof tool === "object" && typeof tool.id === "string") return tool.id;
+	return fallbackKey;
+}
+/**
+* Approval-gated tools suspend the agent loop until a human approves.
+* Mastra persists those suspended runs in Mastra-instance-level storage
+* (`memoryBuilder.instanceStorage()`), not per-agent memory - so boot
+* must fail fast when such a tool is registered without storage.
+*/
+function assertApprovalGatedToolsHaveStorage(gated, memoryBuilder) {
+	if (gated.length === 0) return;
+	if (memoryBuilder?.instanceStorage()) return;
+	const detail = gated.map(({ agentId, toolIds }) => `${agentId}: ${toolIds.join(", ")}`).join("; ");
+	throw new Error(`mastra: approval-gated tools require plugin storage (PostgresStore) to persist suspended runs. Affected agents/tools: ${detail}. Register lakebase() before mastra() so storage auto-enables, or pass storage: true explicitly.`);
+}
+/**
 * Best-effort description of the *static* default model an agent will
 * resolve to at call time. Walks the same precedence ladder as
 * {@link resolveModel} / {@link buildModel}:
@@ -3129,33 +3170,42 @@ async function logFeedback(client, params) {
 * 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.
+* When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the bridge is not
+* registered at all (unless `observability: true` forces it on), so
+* Mastra does not emit `[OtelBridge] No OTEL span found` warnings.
 */
 const log$1 = logUtils.logger("mastra/observability");
 const DEFAULT_SERVICE_NAME = "mastra";
+/** True when AppKit's global OTel pipeline is configured to export traces. */
+function isOtlpTracingConfigured() {
+	return Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT);
+}
 /**
 * 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.
+* Returns `undefined` when tracing is off: either the caller passed
+* `enabled: false`, or auto mode finds no OTLP endpoint (the default).
+* Skipping the bridge in that case avoids `[OtelBridge] No OTEL span
+* found` log spam from Mastra spans that have no parent on the noop
+* tracer.
 */
 async function buildObservability(options) {
-	const serviceName = options?.serviceName ?? await projectUtils.name() ?? DEFAULT_SERVICE_NAME;
-	const requestContextKeys = [...options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS];
 	const otelBase = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
 	const otelTracesOverride = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+	const otlpConfigured = isOtlpTracingConfigured();
+	if (options?.enabled === false || options?.enabled !== true && !otlpConfigured) {
+		log$1.info("Mastra observability off", { reason: options?.enabled === false ? "disabled in plugin config" : "OTEL_EXPORTER_OTLP_ENDPOINT unset" });
+		return;
+	}
+	const serviceName = options?.serviceName ?? await projectUtils.name() ?? DEFAULT_SERVICE_NAME;
+	const requestContextKeys = [...options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS];
 	const resolvedTracesUrl = otelTracesOverride ? otelTracesOverride : otelBase ? `${otelBase.replace(/\/+$/, "")}/v1/traces` : void 0;
 	log$1.info("Mastra observability wired through OTel bridge", {
 		serviceName,
 		requestContextKeys,
 		otelBase: otelBase ?? "<unset>",
-		resolvedTracesUrl: resolvedTracesUrl ?? "<noop; OTLP endpoint unset>"
+		resolvedTracesUrl: resolvedTracesUrl ?? "<unset>"
 	});
 	return new Observability({ configs: { serviceName: {
 		serviceName,
@@ -4042,7 +4092,10 @@ var MastraPlugin = class MastraPlugin extends Plugin {
 			log: this.log
 		});
 		const instanceStorage = memoryBuilder?.instanceStorage();
-		const observability = await buildObservability({ serviceName: this.name });
+		const observability = await buildObservability({
+			serviceName: this.name,
+			enabled: this.config.observability
+		});
 		this.mcp = buildMcpServer({
 			config: this.config,
 			pluginName: this.name,
@@ -4125,4 +4178,4 @@ function parseStatementLimit(raw) {
 const mastra = toPlugin(MastraPlugin);
 
 //#endregion
-export { DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, GENIE_INSTRUCTIONS, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraPlugin, TRACE_REQUEST_CONTEXT_KEYS, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };
+export { DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, GENIE_INSTRUCTIONS, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraPlugin, TRACE_REQUEST_CONTEXT_KEYS, approvalGatedToolIds, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, summarizeText, tool };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@dbx-tools/appkit-mastra-shared": "0.1.82",
-    "@dbx-tools/genie": "0.1.82",
-    "@dbx-tools/genie-shared": "0.1.82",
-    "@dbx-tools/model": "0.1.82",
-    "@dbx-tools/shared": "0.1.82",
+    "@dbx-tools/appkit-mastra-shared": "0.1.83",
+    "@dbx-tools/genie": "0.1.83",
+    "@dbx-tools/genie-shared": "0.1.83",
+    "@dbx-tools/model": "0.1.83",
+    "@dbx-tools/shared": "0.1.83",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",