@dbx-tools/appkit-mastra 0.3.29 → 0.3.31

package/src/config.ts

@@ -1,16 +1,24 @@
 /**
  * Plugin configuration types and shared `RequestContext` keys.
  *
+ * Owns the typed {@link MastraPluginConfig} (the plugin's slice of AppKit
+ * config) and {@link MASTRA_CONFIG_SCHEMA}, the JSON Schema the manifest
+ * publishes for it so scaffolding tools and agents can read the option set.
+ *
+ * Precedence per field is explicit plugin config, then the environment
+ * variable named on the field, then a built-in default.
+ *
  * Kept in a leaf module so `plugin.ts`, `server.ts`, `model.ts`, and
  * `memory.ts` can import them without creating a cycle.
  *
  * @module
  */
 
-import type { BasePluginConfig } from "@databricks/appkit";
+import { getExecutionContext, type BasePluginConfig, type ConfigSchema } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
 import type { BrandContext } from "@dbx-tools/shared-core";
 import type { AgentConfig } from "@mastra/core/agent";
+import type { RequestContext } from "@mastra/core/request-context";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 
@@ -83,6 +91,28 @@ export interface User {
   executionContext: appkit.ExecutionContextLike;
 }
 
+/**
+ * Canonical identity for an AppKit execution context: the OBO user id on a
+ * user-scoped call, the service principal id otherwise.
+ */
+export function executionContextUserId(context: appkit.ExecutionContextLike): string {
+  return "userId" in context ? context.userId : context.serviceUserId;
+}
+
+/**
+ * Identity every per-user cache entry is namespaced under, so an OBO result
+ * cannot be read back by another caller.
+ *
+ * Prefers the {@link User} that {@link MastraServer} stamps on the request
+ * context. The MCP transport routes do not thread that context into tool
+ * execution, so those fall back to the ambient execution context (the active
+ * OBO scope, or the service principal).
+ */
+export function resolveUserKey(requestContext?: RequestContext): string {
+  const user = requestContext?.get(MASTRA_USER_KEY) as User | undefined;
+  return user?.id ?? executionContextUserId(getExecutionContext());
+}
+
 /** PgVector config with an optional Mastra store id. */
 export type MastraMemoryConfig = PgVectorConfig & {
   id?: string;
@@ -129,7 +159,7 @@ export interface MastraMcpConfig {
 
 /** Configuration accepted by the Mastra AppKit plugin. */
 export interface MastraPluginConfig extends BasePluginConfig {
-  /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`. */
+  /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`; no env fallback. */
   providerId?: string;
   /**
    * PostgresStore for Mastra threads/messages. `true` reuses the
@@ -213,34 +243,40 @@ export interface MastraPluginConfig extends BasePluginConfig {
    *   or `providerId`.
    *
    * Resolution order per agent: `def.model` → `defaultModel` →
-   * built-in `/serving-endpoints` resolver.
+   * `DATABRICKS_SERVING_ENDPOINT_NAME` → built-in `/serving-endpoints`
+   * resolver.
    */
   defaultModel?: AgentConfig["model"] | string;
   /**
-   * Allow loose model names (`"claude sonnet"`) to be fuzzy-matched
-   * against the workspace's Model Serving endpoints. Defaults to
-   * `true`; set `false` to require exact endpoint names everywhere.
+   * Fuzzy-match loose model names (`"claude sonnet"`) against the workspace's
+   * Model Serving endpoints. Defaults to `true`; no env fallback.
+   *
+   * Set `false` to require exact endpoint names everywhere.
    */
   modelFuzzyMatch?: boolean;
   /**
-   * Fuse.js score threshold for the fuzzy matcher (0 = exact match,
-   * 1 = anything matches). Defaults to `0.4`. Lower values reject
-   * loose matches; raise it if you have a sprawling endpoint
-   * catalogue with similar-looking names.
+   * Fuse.js score threshold for the fuzzy matcher, 0 (exact) to 1 (anything).
+   * Defaults to `0.4`; no env fallback.
+   *
+   * Lower values reject loose matches; raise it if you have a sprawling
+   * endpoint catalogue with similar-looking names.
    */
   modelFuzzyThreshold?: number;
   /**
-   * TTL for the in-memory serving-endpoints list cache, in
-   * milliseconds. Defaults to 5 minutes. The cache is per workspace
-   * host and shared across users; concurrent callers coalesce on a
-   * single in-flight fetch.
+   * TTL for the in-memory serving-endpoints list cache, in milliseconds.
+   * Defaults to 5 minutes; no env fallback.
+   *
+   * The cache is per workspace host and shared across users; concurrent
+   * callers coalesce on a single in-flight fetch.
    */
   modelCacheTtlMs?: number;
   /**
-   * Allow clients to override the active model per request via the
-   * `X-Mastra-Model` header, `?model=` query string, or `model` body
-   * field. Defaults to `true`. Disable when running multi-tenant
-   * where untrusted clients shouldn't pick the backing endpoint.
+   * Let clients pick the backing endpoint per request. Defaults to `true`;
+   * no env fallback.
+   *
+   * Reads the `X-Mastra-Model` header, the `?model=` query string, or a
+   * `model` body field, in that order. Disable when running multi-tenant
+   * where untrusted clients shouldn't choose the endpoint.
    */
   modelOverride?: boolean;
   /**
@@ -459,3 +495,119 @@ export interface MastraPluginConfig extends BasePluginConfig {
    */
   brand?: BrandContext;
 }
+
+/**
+ * JSON Schema published on the manifest's `config.schema`, mirroring the
+ * documented defaults and environment fallbacks of {@link MastraPluginConfig}.
+ *
+ * Covers the JSON-expressible options only. `agents`, `tools`, and a
+ * `defaultModel` passed as a Mastra `DynamicArgument` are code-defined
+ * (functions / class instances), so they carry no schema entry; the
+ * `defaultModel` property below describes its string form.
+ */
+export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
+  type: "object",
+  properties: {
+    providerId: {
+      type: "string",
+      description: 'Mastra OpenAI-compatible provider id. Defaults to "databricks".',
+    },
+    storage: {
+      type: ["boolean", "object"],
+      description:
+        "PostgresStore for Mastra threads / messages. `true` reuses the `lakebase` plugin's pool, an object opens a dedicated store. Auto-enabled when the `lakebase` plugin is registered.",
+    },
+    memory: {
+      type: ["boolean", "object"],
+      description:
+        "PgVector store for Mastra semantic recall. `true` reuses the `lakebase` plugin's pool, an object opens a dedicated store. Auto-enabled when the `lakebase` plugin is registered.",
+    },
+    defaultAgent: {
+      type: "string",
+      description:
+        "Agent id used when the client names none. Defaults to the first registered agent, else the built-in `default`.",
+    },
+    defaultModel: {
+      type: "string",
+      description:
+        "Serving endpoint applied to every agent that omits its own model. Falls back to DATABRICKS_SERVING_ENDPOINT_NAME, then the auto-resolved catalogue.",
+    },
+    defaultModelFallbacks: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        "Priority-ordered endpoint names tried before the score-classified catalogue when nothing else pins a model.",
+    },
+    modelFuzzyMatch: {
+      type: "boolean",
+      description:
+        "Fuzzy-match loose model names against the workspace catalogue. Defaults to true.",
+    },
+    modelFuzzyThreshold: {
+      type: "number",
+      description:
+        "Fuse.js score threshold for the fuzzy matcher, 0 (exact) to 1 (anything). Defaults to 0.4.",
+    },
+    modelCacheTtlMs: {
+      type: "number",
+      description:
+        "TTL in ms for the serving-endpoints list cache, per workspace host. Defaults to 5 minutes.",
+    },
+    modelOverride: {
+      type: "boolean",
+      description:
+        "Honor a per-request model override from the X-Mastra-Model header, ?model= query, or a `model` body field. Defaults to true.",
+    },
+    genieSpaces: {
+      type: "object",
+      additionalProperties: { type: ["string", "object"] },
+      description:
+        "Genie spaces the agents can delegate to, keyed by alias (the tool-name suffix). Each value is a space id or `{ spaceId, hint }`. Falls back to the `genie` plugin's own `spaces` config, then DATABRICKS_GENIE_SPACE_ID under the `default` alias.",
+    },
+    genieSpaceCacheTtlMs: {
+      type: "number",
+      description: "TTL in ms for the Genie space metadata cache. Defaults to 5 minutes.",
+    },
+    agentMaxSteps: {
+      type: "number",
+      description:
+        "Maximum LLM steps each agent gets per turn (a tool call and the final reply each consume one). Defaults to 25.",
+    },
+    stripStaleCharts: {
+      type: "boolean",
+      description:
+        "Strip chartIds from recalled assistant tool results so the model cannot reuse a turn-scoped chart marker. Defaults to true.",
+    },
+    styleInstructions: {
+      type: ["string", "boolean"],
+      description:
+        "Style guardrails appended to every agent's instructions. A string replaces the built-in block, `false` disables it.",
+    },
+    observability: {
+      type: "boolean",
+      description:
+        "Bridge Mastra spans into AppKit's OTel pipeline. Defaults to on only when OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is set.",
+    },
+    feedback: {
+      type: "boolean",
+      description:
+        "Log thumbs / comment assessments to MLflow and surface the feedback controls. Defaults to on only when an OTLP endpoint and MLFLOW_EXPERIMENT_ID or MLFLOW_EXPERIMENT_NAME are set.",
+    },
+    mcp: {
+      type: ["boolean", "object"],
+      description:
+        "Expose the registered agents over MCP. Defaults to agents-only; an object tunes the server id, advertised metadata, and whether ambient tools are exposed.",
+    },
+    apiAccess: {
+      type: "string",
+      enum: ["scoped", "full"],
+      description:
+        'How much of the stock @mastra/express API is reachable through the mount. "scoped" (default) allows agent inference, read-only agent metadata, this plugin\'s own routes, and MCP; "full" dispatches the entire management surface.',
+    },
+    brand: {
+      type: "object",
+      description:
+        "Portable brand context applied to generated charts (series palette from colors.primary / colors.accent, base font from typography.sans).",
+    },
+  },
+};

package/src/defaults.ts

@@ -0,0 +1,133 @@
+/**
+ * Interceptor defaults for every outbound call the plugin's own routes make
+ * through `Plugin.execute()`.
+ *
+ * One constant per call site so the cache / retry / timeout decision lives
+ * beside its reasoning instead of at the call site. The interceptor chain runs
+ * telemetry, timeout, retry, cache, so a disabled interceptor is a deliberate
+ * choice and is commented as such.
+ *
+ * The cache interceptor is inert without a `cache.cacheKey`, which is
+ * request-specific (a statement id, an agent id). Call sites therefore spread
+ * the constant and add the key; the identity namespace comes from the
+ * execution context's user id, which `execute()` resolves on its own.
+ *
+ * Cancellation is not expressed here: `execute()` derives a signal from the
+ * `timeout` setting only, so a caller's own signal is combined with it at the
+ * call site instead.
+ *
+ * @module
+ */
+
+/**
+ * Per-call interceptor settings. Structural stand-in for AppKit's
+ * `PluginExecuteConfig`: the barrel exports `StreamExecutionSettings` but not
+ * the non-streaming config, so the nominal type is unimportable here. Declared
+ * as a type alias (not an interface) so it keeps the implicit index signature
+ * AppKit's own config carries.
+ */
+type ExecuteConfig = {
+  cache?: { enabled?: boolean; ttl?: number; cacheKey?: (string | number | object)[] };
+  retry?: { enabled?: boolean; attempts?: number; initialDelay?: number; maxDelay?: number };
+  timeout?: number;
+};
+
+/** Default plus optional user-scoped settings, as `execute()` accepts them. */
+type ExecuteSettings = {
+  default: ExecuteConfig;
+  user?: ExecuteConfig;
+};
+
+/** Ceiling on a single Model Serving / Genie / MLflow REST round-trip. */
+const REST_TIMEOUT_MS = 30_000;
+
+/** Ceiling on one Statement Execution fetch, which can page a large result. */
+const STATEMENT_TIMEOUT_MS = 60_000;
+
+/** TTL for a cached statement result set, in seconds. */
+const STATEMENT_CACHE_TTL_SEC = 5 * 60;
+
+/**
+ * `GET /models`: the workspace's Model Serving catalogue.
+ */
+export const modelCatalogueDefaults: ExecuteSettings = {
+  default: {
+    // Cache disabled here because `listServingEndpoints` already memoizes the
+    // catalogue through the same `CacheManager`, keyed by workspace host with
+    // `config.modelCacheTtlMs`. That entry is shared across identities; a
+    // second interceptor cache would duplicate it once per user.
+    cache: { enabled: false },
+    // Retry enabled: listing endpoints is an idempotent GET, and the listing
+    // is on the chat UI's load path, so a transient 5xx should not blank the
+    // model picker.
+    retry: { enabled: true, attempts: 3 },
+    timeout: REST_TIMEOUT_MS,
+  },
+};
+
+/**
+ * `GET /suggestions`: the curated `sample_questions` on each Genie space.
+ */
+export const genieSuggestionDefaults: ExecuteSettings = {
+  default: {
+    // Cache disabled here because `collectSpaceSuggestions` keeps its own
+    // space-id-keyed entry; the questions are authored config, identical for
+    // every caller, so caching them per identity would only fan out copies.
+    cache: { enabled: false },
+    // Retry enabled: reading space metadata is idempotent, and the route
+    // degrades to an empty starter list on failure, so one retry is cheaper
+    // than an empty chat state.
+    retry: { enabled: true, attempts: 2 },
+    timeout: REST_TIMEOUT_MS,
+  },
+};
+
+/**
+ * `GET /embed/data/:id`: one Statement Execution result set.
+ */
+export const statementDataDefaults: ExecuteSettings = {
+  default: {
+    // Cache enabled: a completed statement's result set is immutable, and the
+    // same id is re-fetched every time the transcript re-renders a
+    // `[data:<statement_id>]` marker. The entry is namespaced by the caller's
+    // identity, so an OBO result never crosses users.
+    cache: { enabled: true, ttl: STATEMENT_CACHE_TTL_SEC },
+    // Retry enabled: fetching a statement by id is idempotent.
+    retry: { enabled: true, attempts: 3 },
+    timeout: STATEMENT_TIMEOUT_MS,
+  },
+};
+
+/**
+ * `GET /embed/chart/:id`: the cached chart entry behind a `[chart:<id>]`
+ * marker.
+ */
+export const chartFetchDefaults: ExecuteSettings = {
+  default: {
+    // Cache disabled: the read long-polls a cache entry that is expected to
+    // change from processing to settled, so a cached answer would pin the
+    // client to the pre-planner state.
+    cache: { enabled: false },
+    // Retry disabled: the helper already polls to its own deadline, so a retry
+    // would only restart a wait the caller is already inside.
+    retry: { enabled: false },
+    // No timeout: the poll budget is per request (`?timeoutMs=`, capped by the
+    // route) and cancellation rides the connection's abort signal, so a second
+    // ceiling here could cut a legitimate long-poll short.
+  },
+};
+
+/**
+ * `POST /route/feedback`: an MLflow trace assessment.
+ */
+export const feedbackWriteDefaults: ExecuteSettings = {
+  default: {
+    // Cache disabled: a write, and each submission is a distinct assessment.
+    cache: { enabled: false },
+    // Retry disabled: posting an assessment is not idempotent (a retry records
+    // a duplicate), and `logFeedback` already retries the one recoverable case
+    // itself, the trace not having finished exporting to MLflow yet.
+    retry: { enabled: false },
+    timeout: REST_TIMEOUT_MS,
+  },
+};

package/src/filesystems.ts

@@ -14,7 +14,7 @@
  */
 
 import { posix as path } from "node:path";
-import { getExecutionContext } from "@databricks/appkit";
+import { ExecutionError, getExecutionContext, ValidationError } from "@databricks/appkit";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { error, functionModule, hash, log } from "@dbx-tools/shared-core";
 import {
@@ -101,7 +101,11 @@ export interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOp
 export function normalizeDatabricksBasePath(basePath: string): string {
   const trimmed = basePath.trim();
   if (!trimmed.startsWith("/")) {
-    throw new Error(`Databricks base path must be absolute: ${basePath}`);
+    throw ValidationError.invalidValue(
+      "basePath",
+      basePath,
+      "an absolute Databricks path, e.g. /Volumes/catalog/schema/volume",
+    );
   }
   return trimmed.replace(/\/+$/, "") || "/";
 }
@@ -297,8 +301,16 @@ export class DatabricksWorkspaceFilesystem extends MastraFilesystem {
     if (ErrorType) {
       throw new ErrorType(workspacePath);
     }
-    const message = error.errorMessage(err);
-    throw new Error(`Databricks filesystem ${workspacePath}: ${message}`);
+    // The upstream message is logged rather than raised: it reaches the model
+    // (and from there the chat transcript) as the tool's failure text.
+    logger.warn("operation-failed", {
+      path: workspacePath,
+      error: error.errorMessage(err),
+    });
+    throw new ExecutionError(`Databricks filesystem operation failed for ${workspacePath}`, {
+      cause: error.toError(err),
+      context: { path: workspacePath },
+    });
   }
 
   /* --- lifecycle --- */
@@ -518,7 +530,7 @@ export class DatabricksWorkspaceFilesystem extends MastraFilesystem {
     const created = await this.client.dbfs.create({ path: absolutePath, overwrite });
     const handle = created.handle;
     if (handle === undefined) {
-      throw new Error(`DBFS create did not return a handle for ${absolutePath}`);
+      throw ExecutionError.missingData("DBFS upload handle");
     }
     for (let offset = 0; offset < buffer.length; offset += DBFS_PUT_MAX_BYTES) {
       const slice = buffer.subarray(offset, offset + DBFS_PUT_MAX_BYTES);

package/src/genie.ts

@@ -36,7 +36,13 @@
  * @module
  */
 
-import { CacheManager, genie } from "@databricks/appkit";
+import {
+  CacheManager,
+  ConfigurationError,
+  ExecutionError,
+  genie,
+  ValidationError,
+} from "@databricks/appkit";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { plugin } from "@dbx-tools/appkit";
 import { chat, space as genieSpace } from "@dbx-tools/genie";
@@ -50,7 +56,7 @@ import { z } from "zod";
 
 import type { MastraTools } from "./agents";
 import { chartPlannerRequestSchema, prepareChart } from "./chart";
-import { MASTRA_USER_KEY } from "./config";
+import { MASTRA_USER_KEY, resolveUserKey } from "./config";
 import type { MastraPluginConfig, User } from "./config";
 import { fetchStatementData } from "./statement";
 import { safeWrite } from "./writer";
@@ -114,11 +120,17 @@ function requireClient(
 } {
   const requestContext = ctx?.requestContext;
   if (!requestContext) {
-    throw new Error(`${toolId}: missing requestContext (MastraServer must stamp MASTRA_USER_KEY)`);
+    throw ConfigurationError.resourceNotFound(
+      `${toolId} request context`,
+      "Invoke the tool from an agent turn served by the mastra plugin.",
+    );
   }
   const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
   if (!user) {
-    throw new Error(`${toolId}: no user on requestContext (MASTRA_USER_KEY not set)`);
+    throw ConfigurationError.resourceNotFound(
+      `${toolId} user context`,
+      "Invoke the tool from an agent turn served by the mastra plugin, which stamps the AppKit user on the Mastra request context.",
+    );
   }
   return { client: user.executionContext.client, requestContext };
 }
@@ -163,15 +175,6 @@ const CONVERSATION_TTL_SEC = 4 * 60 * 60;
 /** Cache namespace prefix so coexisting Mastra caches don't collide. */
 const CONVERSATION_CACHE_NAMESPACE = "mastra:genie:conversation";
 
-/**
- * `userKey` for `CacheManager.getOrExecute` / `generateKey`. Genie
- * conversations are scoped to a single user + space + thread, and
- * `threadId` is already user-scoped (Mastra mints threads per
- * `resourceId`), so a constant user key here is safe and keeps the
- * cache key short.
- */
-const CONVERSATION_USER_KEY = "mastra-genie";
-
 /**
  * Build the per-request {@link RequestContext} key the active
  * Genie `conversation_id` lives under for `spaceId`. Scoped by
@@ -211,18 +214,23 @@ function writeContextConversationId(
 }
 
 /**
- * Build the canonical cache key for a `(spaceId, threadId)` pair.
- * Returns `undefined` when `threadId` is missing - callers should
+ * Build the canonical cache key for a `(spaceId, threadId)` pair, owned by
+ * `userKey`. Returns `undefined` when `threadId` is missing - callers should
  * skip caching entirely in that case (no Mastra memory wired up).
+ *
+ * The identity is part of the key because a client picks its own `threadId`
+ * (the thread-selection header / `?threadId=`), so the id alone does not
+ * establish who owns the Genie conversation behind it.
  */
 async function conversationCacheKey(
   spaceId: string,
   threadId: string | undefined,
+  userKey: string,
 ): Promise<string | undefined> {
   if (!threadId) return undefined;
   return (await CacheManager.getInstance()).generateKey(
     [CONVERSATION_CACHE_NAMESPACE, spaceId, threadId],
-    CONVERSATION_USER_KEY,
+    userKey,
   );
 }
 
@@ -395,7 +403,18 @@ function buildAskGenieTool(opts: { spaceId: string; alias: string; hint?: string
       automatically while the call is in flight.
     `),
     inputSchema: z.object({
-      question: z.string().min(1, "question is required"),
+      question: z
+        .string()
+        .min(1, "question is required")
+        .describe(
+          string.toDescription(`
+            ONE focused natural-language question about the data in this
+            space, covering a single metric / dimension / time window
+            (e.g. "What was Q3 revenue by region?"). Decompose a
+            multi-part ask into separate calls rather than combining it
+            here.
+          `),
+        ),
     }),
     outputSchema: z.object({
       message: genieModel.GenieMessageSchema,
@@ -416,10 +435,10 @@ function buildAskGenieTool(opts: { spaceId: string; alias: string; hint?: string
       // of wasting a turn.
       const trimmed = question.trim();
       if (trimmed.length === 0 || PLACEHOLDER_QUESTIONS.has(trimmed.toLowerCase())) {
-        throw new Error(
-          `${toolId}: refusing placeholder question "${question}" - ` +
-            `call ${toolId} only with a real natural-language question, ` +
-            `or skip the call entirely`,
+        throw ValidationError.invalidValue(
+          `${toolId}.question`,
+          question,
+          "a real natural-language question, not a placeholder; skip the call instead",
         );
       }
 
@@ -430,7 +449,11 @@ function buildAskGenieTool(opts: { spaceId: string; alias: string; hint?: string
       // The same `RequestContext` is reused across every `ask_genie`
       // call within one user turn, so `ensureConversationSeeded`
       // hits the cache at most once per request per space.
-      const cacheKey = await conversationCacheKey(spaceId, threadId);
+      const cacheKey = await conversationCacheKey(
+        spaceId,
+        threadId,
+        resolveUserKey(requestContext),
+      );
       await ensureConversationSeeded(requestContext, spaceId, cacheKey);
 
       // Fire the lifecycle `started` event before any LLM /
@@ -466,7 +489,7 @@ function buildAskGenieTool(opts: { spaceId: string; alias: string; hint?: string
           }
         }
         if (!finalMessage) {
-          throw new Error("Genie turn ended without a result event");
+          throw ExecutionError.missingData("Genie result event");
         }
         return finalMessage;
       };
@@ -612,7 +635,17 @@ function buildGetStatementTool() {
       upstream total - compare to \`rows.length\` to detect truncation.
     `),
     inputSchema: z.object({
-      statement_id: z.string().min(1, "statement_id is required"),
+      statement_id: z
+        .string()
+        .min(1, "statement_id is required")
+        .describe(
+          string.toDescription(`
+            Genie \`statement_id\` whose rows to read. Take it from
+            \`message.query_result.statement_id\` or
+            \`message.attachments[*].query.statement_id\` on an
+            \`ask_genie\` result; it is never a value you construct.
+          `),
+        ),
       limit: z
         .number()
         .int()
@@ -702,9 +735,10 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
     outputSchema: wire.ChartSchema.pick({ chartId: true }),
     execute: async (request, ctxRaw) => {
       const ctx = ctxRaw as ToolExecuteCtx;
-      const { client } = requireClient(ctx, toolId);
+      const { client, requestContext } = requireClient(ctx, toolId);
       return prepareChart({
         config,
+        userKey: resolveUserKey(requestContext),
         ...(request.title ? { title: request.title } : {}),
         ...(request.description ? { description: request.description } : {}),
         resolveData: (taskSignal) =>
@@ -855,9 +889,12 @@ export const GENIE_INSTRUCTIONS = string.toDescription([
  * Normalize the {@link GenieSpacesConfig} record. Bare-string
  * entries (`{ default: "01ef..." }`) get wrapped as
  * `{ spaceId: "01ef..." }`; object entries pass through unchanged.
- * `undefined` and empty-string values are dropped so callers can
- * pass `process.env.X` directly (matches AppKit `genie()`'s
- * defensive treatment of unset env vars).
+ *
+ * @throws ConfigurationError when an alias is present but carries no space id
+ *   (`{ default: process.env.DATABRICKS_GENIE_SPACE_ID }` with the variable
+ *   unset). An alias that resolves to nothing is a wiring contradiction: the
+ *   agent would advertise no Genie tool for a space the deployment believes it
+ *   configured, so it fails at construction instead of going quiet.
  */
 export function normalizeGenieSpaces(
   spaces: GenieSpacesConfig | Record<string, string | GenieSpaceConfig | undefined> | undefined,
@@ -865,18 +902,22 @@ export function normalizeGenieSpaces(
   if (!spaces) return {};
   const out: Record<string, GenieSpaceConfig> = {};
   for (const [alias, value] of Object.entries(spaces)) {
-    if (value === undefined) continue;
-    if (typeof value === "string") {
-      if (!value) continue;
-      out[alias] = { spaceId: value };
-      continue;
-    }
-    if (!value.spaceId) continue;
-    out[alias] = value;
+    const spaceId = typeof value === "string" ? value : value?.spaceId;
+    if (!spaceId) throw missingSpaceId(alias);
+    out[alias] = typeof value === "string" ? { spaceId } : value!;
   }
   return out;
 }
 
+/** Config contradiction: an alias present in `genieSpaces` with no space id. */
+function missingSpaceId(alias: string): ConfigurationError {
+  const envHint =
+    alias === DEFAULT_GENIE_ALIAS
+      ? "Set DATABRICKS_GENIE_SPACE_ID, pass the space id inline, or drop the alias."
+      : `Pass the space id inline (DATABRICKS_GENIE_SPACE_ID only backs the "${DEFAULT_GENIE_ALIAS}" alias) or drop the alias.`;
+  return ConfigurationError.resourceNotFound(`genieSpaces.${alias} space id`, envHint);
+}
+
 /**
  * AppKit `genie` plugin's config shape, derived from the factory
  * itself so it stays in lock-step with the upstream type without
@@ -907,9 +948,9 @@ type AppKitGenieConfig = NonNullable<Parameters<typeof genie>[0]>;
  *      pair just works.
  *
  * Aliases collide cleanly: a higher-precedence source's value
- * replaces a lower one's wholesale. Sources that contribute zero
- * aliases (or contribute only `undefined` / empty entries) are
- * silently ignored.
+ * replaces a lower one's wholesale. A source that contributes zero
+ * aliases is skipped; a source that names an alias without a space
+ * id fails through {@link normalizeGenieSpaces}.
  */
 export function resolveGenieSpaces(
   config: MastraPluginConfig,

package/src/history.ts

@@ -18,6 +18,7 @@
  * @module
  */
 
+import { ValidationError } from "@databricks/appkit";
 import { error, log } from "@dbx-tools/shared-core";
 import type {
   MastraClearHistoryResponse,
@@ -207,8 +208,10 @@ export function historyRoute(options: HistoryRouteOptions) {
   const { path } = options;
   const fixedAgent = "agent" in options ? options.agent : undefined;
   if (!fixedAgent && !path.includes(":agentId")) {
-    throw new Error(
-      "historyRoute path must include `:agentId` or `agent` must be passed explicitly",
+    throw ValidationError.invalidValue(
+      "historyRoute.path",
+      path,
+      "a path containing `:agentId`, or an explicit `agent`",
     );
   }
   // Tiny resolver shared by GET / DELETE: derive the active agent