@dbx-tools/appkit-mastra 0.3.44 → 0.4.1

package/lib/src/config.d.ts

@@ -0,0 +1,479 @@
+/**
+ * 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, 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 type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
+import type { MastraAgentDefinition, MastraTools } from "./agents.js";
+import type { GenieSpacesConfig } from "./genie.js";
+/**
+ * `RequestContext` key under which {@link MastraServer} stores the
+ * resolved AppKit user. `model.ts` reads it to mint user-scoped
+ * Databricks tokens.
+ */
+export declare const MASTRA_USER_KEY = "mastra__user";
+/**
+ * `RequestContext` keys for AppKit user metadata stamped by
+ * {@link MastraServer}. Surfaced as trace metadata via
+ * {@link TRACE_REQUEST_CONTEXT_KEYS} so traces are filterable by who
+ * issued the request without leaking the full user object.
+ */
+export declare const MASTRA_USER_NAME_KEY = "mastra__userName";
+export declare const MASTRA_USER_EMAIL_KEY = "mastra__userEmail";
+/**
+ * `RequestContext` key for the per-HTTP-request id stamped by
+ * {@link MastraServer}. Reads `X-Request-Id` from the incoming
+ * headers when present (so an upstream load balancer / API gateway
+ * can keep its trace correlation), falls back to a freshly minted
+ * UUID. Echoed back on the response and surfaced on every span via
+ * {@link TRACE_REQUEST_CONTEXT_KEYS} so logs and traces share a
+ * join key.
+ */
+export declare const MASTRA_REQUEST_ID_KEY = "mastra__requestId";
+/**
+ * `RequestContext` key for OAuth scopes parsed from the forwarded
+ * access token by {@link MastraServer.configureRequestContextScopes}.
+ * Workspace mounts that touch Databricks workspace files require
+ * `workspace` or `all-apis` in this list.
+ */
+export declare const MASTRA_SCOPES_KEY = "mastra__scopes";
+/**
+ * Canonical list of `RequestContext` keys we want Mastra to extract
+ * as metadata on every observability span (agent runs, model calls,
+ * tool invocations, workflow steps).
+ *
+ * Mirrors {@link https://mastra.ai/docs/observability/tracing/overview#automatic-metadata-from-requestcontext}:
+ * passed verbatim into `Observability.configs[*].requestContextKeys`,
+ * so any key listed here is read from `RequestContext` at trace
+ * start and attached as scalar span metadata. Keep the set to plain
+ * scalars - never include {@link MASTRA_USER_KEY} (it carries the
+ * full AppKit execution context with a `WorkspaceClient` reference).
+ *
+ * Order is purely cosmetic; Mastra de-dupes internally.
+ */
+export declare const TRACE_REQUEST_CONTEXT_KEYS: readonly string[];
+/** AppKit execution context plus the canonical user id. */
+export interface User {
+    id: string;
+    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 declare function executionContextUserId(context: appkit.ExecutionContextLike): string;
+/**
+ * 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 declare function resolveUserKey(requestContext?: RequestContext): string;
+/** PgVector config with an optional Mastra store id. */
+export type MastraMemoryConfig = PgVectorConfig & {
+    id?: string;
+};
+/**
+ * Fine-grained control for the optional MCP server exposure
+ * ({@link MastraPluginConfig.mcp}). Every field is optional; the object
+ * form only needs to set what differs from the defaults.
+ */
+export interface MastraMcpConfig {
+    /**
+     * Server id used in the route path (`/mcp/<serverId>/...`) and as the
+     * MCP registry id. Defaults to the plugin's registered name.
+     */
+    serverId?: string;
+    /** Display name advertised over MCP. Defaults to `"<displayName> MCP"`. */
+    name?: string;
+    /** Semantic version advertised over MCP. Defaults to `"1.0.0"`. */
+    version?: string;
+    /** Optional human-readable description advertised over MCP. */
+    description?: string;
+    /**
+     * Expose every registered agent as an `ask_<agentId>` MCP tool.
+     * Defaults to `true` - this is the "leverage the Mastra agents over
+     * MCP" behavior most callers want.
+     */
+    agents?: boolean;
+    /**
+     * Also expose the plugin's ambient tools (the built-in `render_data`
+     * plus anything in `config.tools`) as MCP tools. Defaults to `false`:
+     * the ambient tools assume an in-process chat turn (they publish
+     * writer events the chat UI consumes), so they aren't useful to a
+     * standalone MCP client. Turn this on only when those tools are safe
+     * to call out-of-band.
+     */
+    tools?: boolean;
+    /**
+     * Extra tools to expose over MCP beyond the agent / ambient sets.
+     * Use this for tools written specifically for MCP consumers.
+     */
+    extraTools?: MastraTools;
+}
+/** Configuration accepted by the Mastra AppKit plugin. */
+export interface MastraPluginConfig extends BasePluginConfig {
+    /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`; no env fallback. */
+    providerId?: string;
+    /**
+     * PostgresStore for Mastra threads/messages. `true` reuses the
+     * `lakebase` plugin's pool; an object opens a dedicated store.
+     */
+    storage?: boolean | PostgresStoreConfig;
+    /**
+     * PgVector store for Mastra memory recall. `true` reuses the
+     * `lakebase` plugin's pool; an object opens a dedicated store.
+     */
+    memory?: boolean | MastraMemoryConfig;
+    /**
+     * Code-defined agents. Accepts three shapes for convenience:
+     *
+     * - **Record**: `{ analyst: def, helper: def }` - keys become the
+     *   registered ids and the first key is the default.
+     * - **Single definition**: `def` - registered under
+     *   `slugify(def.name)` (or `"default"` when `name` is omitted) and
+     *   automatically marked as the default agent.
+     * - **Array**: `[def1, def2]` - each registered under
+     *   `slugify(def.name)` (or `agent_${i}` when `name` is omitted);
+     *   the first entry is the default.
+     *
+     * Each entry becomes a Mastra `Agent` reachable at
+     * `/api/<plugin>/route/chat/<id>` (the chat route also matches
+     * `:agentId`). When `agents` is omitted entirely, the plugin
+     * registers a single built-in `default` analyst so the bare
+     * `mastra()` call still mounts a working chat endpoint.
+     *
+     * @example Single-agent shorthand
+     * ```ts
+     * mastra({
+     *   agents: createAgent({ instructions: "..." }),
+     * });
+     * ```
+     *
+     * @example Array
+     * ```ts
+     * mastra({
+     *   agents: [
+     *     createAgent({ name: "analyst", instructions: "..." }),
+     *     createAgent({ name: "helper", instructions: "..." }),
+     *   ],
+     * });
+     * ```
+     *
+     * @example Record (explicit ids)
+     * ```ts
+     * mastra({
+     *   agents: {
+     *     analyst: createAgent({ instructions: "..." }),
+     *     helper: createAgent({ instructions: "..." }),
+     *   },
+     *   defaultAgent: "analyst",
+     * });
+     * ```
+     */
+    agents?: Record<string, MastraAgentDefinition> | MastraAgentDefinition | MastraAgentDefinition[];
+    /**
+     * Ambient tools spread into every registered agent's tools record;
+     * per-agent tools win on key collision. Use for a small shared
+     * library; for per-agent tools set `agents[id].tools` instead.
+     */
+    tools?: MastraTools;
+    /**
+     * Agent id used when the client doesn't specify one (the bare,
+     * un-suffixed history / suggestions routes resolve to it).
+     * Defaults to the first key in `agents` (or `"default"` when
+     * `agents` is omitted). Must match an id in `agents` when both are
+     * set; a mismatch throws at setup with the available candidates.
+     */
+    defaultAgent?: string;
+    /**
+     * Plugin-level default model applied to every agent that omits its
+     * own `model`. Mirrors AppKit's `agents({ defaultModel })`.
+     *
+     * - `string`: shorthand for "use the OBO auto-resolver but swap the
+     *   `modelId`" (e.g. `"databricks-claude-sonnet-4-6"`).
+     * - Any other Mastra `DynamicArgument<MastraModelConfig>`: passed
+     *   through verbatim. Use this when you need full control over auth
+     *   or `providerId`.
+     *
+     * Resolution order per agent: `def.model` → `defaultModel` →
+     * `DATABRICKS_SERVING_ENDPOINT_NAME` → built-in `/serving-endpoints`
+     * resolver.
+     */
+    defaultModel?: AgentConfig["model"] | string;
+    /**
+     * 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) 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; no env fallback.
+     *
+     * The cache is per workspace host and shared across users; concurrent
+     * callers coalesce on a single in-flight fetch.
+     */
+    modelCacheTtlMs?: number;
+    /**
+     * 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;
+    /**
+     * Priority-ordered list of endpoint names tried *first* when no
+     * agent / plugin / env / request-override model id is set, ahead of
+     * the dynamic score-classified catalogue. The resolver picks the
+     * first id that is actually present in the workspace's
+     * `/serving-endpoints` listing.
+     *
+     * When unset, resolution is driven by the live Foundation Model API
+     * `quality` / `speed` / `cost` scores: endpoints are classified into
+     * chat classes (`classifyEndpoints`) and walked best-first
+     * (ChatThinking -> ChatBalanced -> ChatFast), with the small built-in
+     * `FALLBACK_MODEL_IDS` list as the floor when the catalogue can't be
+     * read. Set this to
+     * pin a regulated workspace to an approved subset, or to put custom
+     * endpoints in front of the auto-classified catalogue.
+     */
+    defaultModelFallbacks?: readonly string[];
+    /**
+     * When `true` (default), every agent gets a built-in input
+     * processor that strips `chartId` fields from prior assistant
+     * tool-invocation results before they reach the model. This
+     * prevents the model from reusing turn-scoped chartIds it sees
+     * in memory recall (which would leave `[chart:<id>]` markers
+     * pointing at writer events that no longer exist).
+     *
+     * Set to `false` to opt out - useful if a non-default agent
+     * needs full visibility into prior chartIds (e.g. an audit
+     * agent reasoning about chart lineage).
+     */
+    stripStaleCharts?: boolean;
+    /**
+     * Style guardrails appended to every agent's `instructions` to curb
+     * common LLM-isms (em dashes, emojis, sycophantic openers, throwaway
+     * closers, excessive hedging).
+     *
+     * - `undefined` (default): use the built-in
+     *   `DEFAULT_STYLE_INSTRUCTIONS` from `agents.ts`.
+     * - `string`: replace the default with the supplied block.
+     * - `false`: disable entirely (agents see only their bespoke
+     *   `instructions`).
+     *
+     * Appended (not prepended) so the agent's role and rules come first
+     * and the style block leans on the model's recency bias.
+     */
+    styleInstructions?: string | false;
+    /**
+     * Genie spaces this plugin's agents can delegate to. One Mastra
+     * tool is registered per alias (`genie` for the well-known
+     * `default` alias, `genie_<alias>` otherwise). Each tool spins
+     * up a per-question Genie sub-agent that runs Databricks
+     * "agent mode" against the space, broadcasts wire events to the
+     * UI, fetches statement rows for non-empty results, and returns
+     * a `(string | data | chart)[]` summary the host UI renders
+     * inline.
+     *
+     * Entries accept either a full {@link GenieSpaceConfig} object
+     * or a bare `space_id` string when no extras are needed:
+     *
+     * ```ts
+     * mastra({
+     *   genieSpaces: {
+     *     default: "01ef0d3c0e1b1f4a8d2c3e4f5a6b7c8d",
+     *     forecasts: { spaceId: "01ef...", hint: "weekly demand forecasts" },
+     *   },
+     * });
+     * ```
+     *
+     * Reach the spaces from an agent's `tools(plugins)` callback via
+     * `plugins.genie?.toolkit()`; the resulting tools accept
+     * `{ content, conversationId? }` and return a hydrated summary.
+     *
+     * **Fallback discovery** (highest precedence first): if this
+     * field is omitted, the Genie agent also picks up spaces from
+     * (1) the AppKit `genie({ spaces: { ... } })` plugin instance
+     * when registered, and (2) the `DATABRICKS_GENIE_SPACE_ID`
+     * env var (registered under the `default` alias). This keeps
+     * existing AppKit deployments working without restating the
+     * spaces config in two places.
+     */
+    genieSpaces?: GenieSpacesConfig;
+    /**
+     * TTL for the in-memory Genie space metadata cache, in
+     * milliseconds. Defaults to 5 minutes. The Genie agent calls
+     * `client.genie.getSpace(...)` on every cold-start to get the
+     * title / description / warehouse id; cached responses skip the
+     * round-trip and concurrent callers coalesce on a single
+     * in-flight fetch. Drop to a smaller value when analysts are
+     * actively editing space metadata and you want changes visible
+     * within seconds; raise it to amortise the round-trip when
+     * space metadata is effectively frozen.
+     *
+     * Backed by AppKit's `CacheManager`, so the cache participates
+     * in telemetry spans (`cache.getOrExecute`) and benefits from
+     * Lakebase persistence when the `lakebase` plugin is wired up.
+     */
+    genieSpaceCacheTtlMs?: number;
+    /**
+     * Maximum LLM steps each agent gets per turn. One step = one
+     * round-trip to the underlying model (a tool call consumes a
+     * step, the final-text reply consumes one too). Applies to
+     * every agent registered through {@link MastraPluginConfig.agents}
+     * - per-agent overrides aren't surfaced yet because the same
+     * ceiling has been sufficient across every workload we've run.
+     *
+     * Defaults to {@link DEFAULT_AGENT_MAX_STEPS} (25), sized to fit
+     * a decomposed Genie turn (grounding + several `ask_genie` calls
+     * + `prepare_chart` per dataset + the final-text reply) with
+     * headroom for the model to chain a couple of follow-ups before
+     * answering. Mastra's own `agent.generate` default of 5 would
+     * cut multi-step orchestration off after 2-3 tool calls, so
+     * explicitly raising the ceiling here is what lets the
+     * agent-mode loop play out.
+     *
+     * Lower when an unusually slow or expensive model makes long
+     * turns unaffordable; raise for exploratory workloads that need
+     * 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.
+     *
+     * - `undefined` (default, auto): enabled only when MLflow tracing is
+     *   wired - an OTLP exporter endpoint is set and an MLflow experiment
+     *   is named (the same signals the observability pipeline needs to
+     *   ship traces to MLflow). Otherwise off, since there'd be no trace
+     *   to attach feedback to.
+     * - `true`: force on. Feedback controls show and writes are attempted
+     *   regardless of env detection (use when the env is configured in a
+     *   way the auto-probe doesn't recognize).
+     * - `false`: force off. No trace-id header, no feedback route, no UI.
+     *
+     * Feedback attaches to a turn's MLflow trace via the OpenTelemetry
+     * trace id the server stamps on each response; see `mlflow.ts`.
+     */
+    feedback?: boolean;
+    /**
+     * Expose the plugin's agents (and optionally tools) as a Mastra MCP
+     * server so external MCP clients - Claude Desktop, Cursor, the Mastra
+     * playground, or another agent - can call them over the standard MCP
+     * transports. Enabled by default (agents only): wrapping the
+     * already-registered agents costs nothing extra, so the endpoint is on
+     * out of the box; only the ambient tools (which assume an in-process
+     * chat turn) stay off unless explicitly opted in.
+     *
+     * - `undefined` (default) / `true`: expose every registered agent as
+     *   an `ask_<agentId>` MCP tool under a server whose id is the plugin
+     *   name.
+     * - `false`: no MCP endpoints.
+     * - {@link MastraMcpConfig}: fine-grained control over the server id,
+     *   advertised metadata, and which agents / tools are exposed.
+     *
+     * When enabled, the stock Mastra MCP routes mount under the plugin's
+     * base path (no bespoke route is added - the server is handed to the
+     * `Mastra` instance via `mcpServers`, which `@mastra/express` serves):
+     *
+     * - Streamable HTTP: `POST /api/<plugin>/mcp/<serverId>/mcp`
+     * - SSE (legacy):    `GET  /api/<plugin>/mcp/<serverId>/sse`
+     *                    `POST /api/<plugin>/mcp/<serverId>/messages`
+     *
+     * Requests run under the same AppKit OBO scope as the chat routes, so
+     * an agent invoked over MCP resolves its model and tools as the
+     * calling user.
+     */
+    mcp?: boolean | MastraMcpConfig;
+    /**
+     * How much of the stock `@mastra/express` management API is reachable
+     * through the plugin mount. `@mastra/express` registers its full route
+     * table (agent inference plus admin / mutating routes: direct tool
+     * execution, workflow control, raw memory read/write, telemetry, logs,
+     * scores). AppKit already authenticates every request as the OBO user,
+     * but nothing there restricts *which* of those operations the browser
+     * client may invoke.
+     *
+     * - `"scoped"` (default): only the routes the chat client legitimately
+     *   needs are dispatched to Mastra - agent inference
+     *   (`stream` / `generate` / `network`), read-only agent metadata, this
+     *   plugin's own OBO- and resource-scoped `/route/*` routes (history /
+     *   threads), and, when {@link mcp} is enabled, the MCP transport.
+     *   Everything else (tool execution, workflow control, raw memory,
+     *   telemetry, logs, scores, and other mutations) is rejected with
+     *   `403` before it reaches Mastra.
+     * - `"full"`: dispatch the entire stock Mastra API. Use only for a
+     *   trusted first-party console that genuinely needs the management
+     *   surface.
+     */
+    apiAccess?: "scoped" | "full";
+    /**
+     * Optional brand context applied to charts produced by the built-in
+     * `render_data` / `prepare_chart` tools. When set, the chart planner's
+     * Echarts output is themed with the brand's palette (series colors derived
+     * from `colors.primary` / `colors.accent`) and sans font
+     * (`typography.sans`) instead of Echarts' defaults. Omit for the default
+     * Echarts look.
+     *
+     * Pass the portable {@link BrandContext} shared across the UI and
+     * libraries (e.g. `brand.defaultBrandContext` from `@dbx-tools/shared-core`,
+     * or a customer brand) - the same object the email add-on and the UI
+     * `BrandProvider` consume, so a host themes charts, email, and UI from one
+     * source.
+     */
+    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 declare const MASTRA_CONFIG_SCHEMA: ConfigSchema;