@dbx-tools/appkit-mastra 0.3.28 → 0.3.30

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,9 +14,20 @@
  */
 
 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 {
+  DirectoryNotEmptyError,
+  DirectoryNotFoundError,
+  FileExistsError,
+  FileNotFoundError,
+  IsDirectoryError,
+  MastraFilesystem,
+  NotDirectoryError,
+  PermissionError,
+  WorkspaceReadOnlyError,
+} from "@mastra/core/workspace";
 import type {
   CopyOptions,
   FileContent,
@@ -24,20 +35,11 @@ import type {
   FileStat,
   FilesystemInfo,
   ListOptions,
+  MastraFilesystemOptions,
   ProviderStatus,
   ReadOptions,
   RemoveOptions,
   WriteOptions,
-  DirectoryNotEmptyError,
-  DirectoryNotFoundError,
-  FileExistsError,
-  FileNotFoundError,
-  IsDirectoryError,
-  MastraFilesystem,
-  NotDirectoryError,
-  PermissionError,
-  WorkspaceReadOnlyError,
-  type MastraFilesystemOptions,
 } from "@mastra/core/workspace";
 
 /* ------------------------------ constants ------------------------------ */
@@ -99,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(/\/+$/, "") || "/";
 }
@@ -295,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 --- */
@@ -516,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);