@dbx-tools/appkit-mastra 0.1.58 → 0.1.67

package/dist/index.d.ts

@@ -1,20 +1,1232 @@
+import { Chart } from "@dbx-tools/appkit-mastra-shared";
+import { ServingEndpointSummary } from "@dbx-tools/model";
+import { appkitUtils, logUtils } from "@dbx-tools/shared";
+import * as _mastra_core_agent0 from "@mastra/core/agent";
+import { Agent, AgentConfig, ToolsInput } from "@mastra/core/agent";
+import * as _mastra_core_tools0 from "@mastra/core/tools";
+import { Tool, createTool } from "@mastra/core/tools";
+import * as _databricks_appkit0 from "@databricks/appkit";
+import { BasePluginConfig, IAppRouter, Plugin, ResourceRequirement } from "@databricks/appkit";
+import { z } from "zod";
+import { RequestContext } from "@mastra/core/request-context";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { MCPServer } from "@mastra/mcp";
+import { Mastra } from "@mastra/core/mastra";
+import express from "express";
+import { Memory } from "@mastra/memory";
+import { PgVectorConfig, PostgresStore, PostgresStoreConfig } from "@mastra/pg";
+import { Pool } from "pg";
+import { MastraServer } from "@mastra/express";
+import * as _mastra_core_workflows0 from "@mastra/core/workflows";
+import * as _mastra_core_vector0 from "@mastra/core/vector";
+import * as _mastra_core_tts0 from "@mastra/core/tts";
+import * as _mastra_core_logger0 from "@mastra/core/logger";
+import * as _mastra_core_mcp0 from "@mastra/core/mcp";
+import * as _mastra_core_evals0 from "@mastra/core/evals";
+import * as _mastra_core_processors0 from "@mastra/core/processors";
+import * as _mastra_core_memory0 from "@mastra/core/memory";
+import * as _mastra_core_channels0 from "@mastra/core/channels";
+export * from "@dbx-tools/appkit-mastra-shared";
+export * from "@dbx-tools/model";
+
+//#region packages/appkit-mastra/src/genie.d.ts
+/** Default alias used when a single unnamed Genie space is wired up. */
+declare const DEFAULT_GENIE_ALIAS = "default";
+/** Per-space Genie agent configuration. */
+interface GenieSpaceConfig {
+  /** Genie `space_id`. Required; resolves via `client.genie.getSpace`. */
+  spaceId: string;
+  /**
+   * Optional human-readable description appended to the per-space
+   * tool descriptions so the calling LLM has hints about *what
+   * data* this space covers (e.g. "orders, returns,
+   * fulfillment"). When omitted, only the space's own
+   * `description` (fetched on first use of `get_space_description`)
+   * is shown.
+   */
+  hint?: string;
+}
+/** Map of alias -> space config. Accepts either explicit objects or bare space ids. */
+type GenieSpacesConfig = Record<string, GenieSpaceConfig | string>;
 /**
- * Server-side entry point for the AppKit Mastra integration. Mounts
- * the plugin via {@link mastra} and re-exports the full server surface
- * (config, agent wiring, Genie and chart tooling, and dynamic Model
- * Serving resolution) so apps build agent backends from one import.
+ * Suggested orchestration prompt for the central agent that owns
+ * the Genie tools. Compose into your agent's `instructions` to
+ * get the canonical "decompose questions, ask Genie focused
+ * sub-questions, place data / chart markers in prose" behavior:
  *
- * Client-side consumers should import URL helpers and the
- * {@link MastraClientConfig} type from `@dbx-tools/appkit-mastra-shared`
- * instead - that package is pure (no pg / fastembed / Mastra deps) and
- * is the right surface for browser bundles and `usePluginClientConfig`
- * consumers.
+ * ```ts
+ * createAgent({
+ *   instructions: `${myAgentInstructions}\n\n${GENIE_INSTRUCTIONS}`,
+ *   tools(plugins) {
+ *     return { ...plugins.genie?.toolkit() };
+ *   },
+ * });
+ * ```
+ *
+ * The prompt references the bare tool names (`ask_genie`,
+ * `get_space_description`, `get_space_serialized`,
+ * `get_statement`, `prepare_chart`) used for the single-space
+ * default alias. Multi-space deployments should write their own
+ * variant that names the suffixed per-space tools
+ * (e.g. `ask_genie_sales`).
  */
-export * from "@dbx-tools/appkit-mastra-shared";
-export * from "@dbx-tools/model";
-export * from "./src/agents.js";
-export * from "./src/chart.js";
-export * from "./src/config.js";
-export * from "./src/genie.js";
-export * from "./src/plugin.js";
-export { MASTRA_MODEL_OVERRIDE_KEY, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY, extractModelOverride, type ModelOverrideRequest, } from "./src/serving.js";
+declare const GENIE_INSTRUCTIONS: string;
+/**
+ * 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).
+ */
+declare function normalizeGenieSpaces(spaces: GenieSpacesConfig | Record<string, string | GenieSpaceConfig | undefined> | undefined): Record<string, GenieSpaceConfig>;
+/**
+ * Discover Genie space aliases from every supported source and
+ * merge them into a single record. Precedence (highest first):
+ *
+ *   1. {@link MastraPluginConfig.genieSpaces} on the `mastra(...)`
+ *      call. Explicit Mastra wiring always wins so users can
+ *      override AppKit's defaults per-agent.
+ *   2. AppKit `genie({ spaces: { ... } })` plugin instance. Lets
+ *      users keep using the existing AppKit config format
+ *      (`genie({ spaces: { sales: "...", ops: "..." } })`)
+ *      without restating the same record on the Mastra plugin.
+ *      Read off the live plugin instance via a structural cast
+ *      since `Plugin.config` is TS-protected (not runtime-private).
+ *   3. `DATABRICKS_GENIE_SPACE_ID` env var (registered under the
+ *      well-known `default` alias). Matches the AppKit `genie()`
+ *      plugin's fallback behavior so a bare `mastra()` + `genie()`
+ *      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.
+ */
+declare function resolveGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): Record<string, GenieSpaceConfig>;
+/**
+ * Build the flat Mastra tools record for every configured Genie
+ * space. Two shared, space-agnostic tools (`get_statement`,
+ * `prepare_chart`) are registered once regardless of how many
+ * spaces are wired; the per-space tools (`ask_genie`,
+ * `get_space_description`, `get_space_serialized`) are suffixed
+ * with `_<alias>` for non-default aliases so multi-space
+ * deployments stay disambiguated.
+ *
+ * Returns a record keyed by tool id, ready to spread into the
+ * central `Agent`'s `tools` map (or surfaced via the
+ * `plugins.genie?.toolkit()` callback). Returns an empty record
+ * when `spaces` resolves to zero entries so the caller can spread
+ * safely.
+ */
+declare function buildGenieTools(opts: {
+  spaces: GenieSpacesConfig | Record<string, GenieSpaceConfig>;
+  config: MastraPluginConfig;
+}): MastraTools;
+/**
+ * Plugin-toolkit adapter so the `plugins.genie?.toolkit()` lookup
+ * inside an agent's `tools(plugins)` callback returns the
+ * flat Genie tools record instead of throwing on missing plugin.
+ * Mirrors AppKit's `PluginToolkitProvider` shape.
+ */
+declare function buildGenieToolkitProvider(opts: {
+  spaces: GenieSpacesConfig | Record<string, GenieSpaceConfig>;
+  config: MastraPluginConfig;
+}): {
+  toolkit(opts?: unknown): MastraTools;
+};
+/**
+ * Collect the curated starter questions across every resolved Genie
+ * space, deduped and capped. Each space's `sample_questions` are
+ * fetched once (cached for {@link SUGGESTION_CACHE_TTL_MS}) via
+ * {@link getGenieSpace} + {@link genieSampleQuestions}, then merged in
+ * alias-iteration order so a single-space app surfaces that space's
+ * questions and a multi-space app round-trips breadth-first up to the
+ * cap. A per-space fetch failure degrades to "no questions for that
+ * space" (logged, not thrown) so one unreachable space never blanks
+ * the whole list. Returns `[]` when no spaces are configured.
+ */
+declare function collectSpaceSuggestions(opts: {
+  spaces: Record<string, GenieSpaceConfig>;
+  client: WorkspaceClient;
+  signal?: AbortSignal;
+  limit?: number;
+}): Promise<string[]>;
+//#endregion
+//#region packages/appkit-mastra/src/config.d.ts
+/**
+ * `RequestContext` key under which {@link MastraServer} stores the
+ * resolved AppKit user. `model.ts` reads it to mint user-scoped
+ * Databricks tokens.
+ */
+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.
+ */
+declare const MASTRA_USER_NAME_KEY = "mastra__userName";
+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.
+ */
+declare const MASTRA_REQUEST_ID_KEY = "mastra__requestId";
+/**
+ * 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.
+ */
+declare const TRACE_REQUEST_CONTEXT_KEYS: readonly string[];
+/** AppKit execution context plus the canonical user id. */
+interface User {
+  id: string;
+  executionContext: appkitUtils.ExecutionContextLike;
+}
+/** PgVector config with an optional Mastra store id. */
+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.
+ */
+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. */
+interface MastraPluginConfig extends BasePluginConfig {
+  /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`. */
+  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` →
+   * 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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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;
+  /**
+   * 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. Disabled by default.
+   *
+   * - `undefined` / `false`: no MCP endpoints.
+   * - `true`: expose every registered agent as an `ask_<agentId>` MCP
+   *   tool under a server whose id is the plugin name.
+   * - {@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;
+}
+//#endregion
+//#region packages/appkit-mastra/src/memory.d.ts
+/**
+ * Builds one `Memory` per agent against a shared service-principal
+ * Lakebase pool. Per-instance state keeps the shared `PgVector` alive
+ * across calls so registering N agents stays cheap.
+ */
+declare class MemoryBuilder {
+  private readonly config;
+  private readonly servicePrincipalPool;
+  private sharedVector;
+  constructor(config: MastraPluginConfig, servicePrincipalPool: Pool);
+  /**
+   * Build a `Memory` for `agentId` after the plugin/agent cascade.
+   * Returns `undefined` when the agent has neither storage nor a
+   * 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;
+  /**
+   * Resolve the agent's vector store. Cascade:
+   *
+   * - falsy: no vector.
+   * - `boolean` / `undefined-inheriting-true`: return the shared
+   *   singleton (built lazily on first call). All agents that
+   *   default-enable memory write into and recall from one index.
+   * - object: build a dedicated `PgVector` for this agent.
+   */
+  private buildVector;
+  private getSharedVector;
+}
+//#endregion
+//#region packages/appkit-mastra/src/agents.d.ts
+/**
+ * Tool record accepted by every Mastra `Agent.tools` field and by the
+ * `tools(plugins)` callback on {@link MastraAgentDefinition}.
+ *
+ * Alias of Mastra's `ToolsInput`, so it already accepts:
+ *
+ * - Mastra tools built with {@link createTool} (or `new Tool(...)`)
+ * - Mastra tools built with the AppKit-shaped {@link tool} wrapper
+ *   below
+ * - Vercel AI SDK tools (`tool({ ... })` from `ai`)
+ * - Provider-defined tools (e.g. `openai.tools.webSearch(...)`)
+ *
+ * Existing tool libraries drop in as-is - nothing in this package
+ * forces a rebuild.
+ */
+type MastraTools = ToolsInput;
+/**
+ * AppKit-shaped tool factory. Lets users mix-and-match tools across
+ * AppKit's `agents` plugin and `mastra` with a single import:
+ *
+ * ```ts
+ * import { tool } from "@dbx-tools/appkit-mastra";
+ * import { z } from "zod";
+ *
+ * get_weather: tool({
+ *   description: "Weather",
+ *   schema: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => `Sunny in ${city}`,
+ * }),
+ * ```
+ *
+ * Maps onto Mastra's `createTool`:
+ *
+ * - `description` -> `description` (required)
+ * - `schema` -> `inputSchema` (optional)
+ * - `execute(input)` -> `execute(input, ctx)` - Mastra already calls
+ *   the first arg with the parsed inputs, so the body shape is
+ *   identical. The Mastra `context` arg is forwarded as the second
+ *   parameter when the caller declares it.
+ * - `id`: optional. Defaults to a stable identifier derived from
+ *   `description` (slugified, with a short hash suffix for
+ *   uniqueness). Pass an explicit `id` when you need a stable string
+ *   for tracing or MCP exposure.
+ *
+ * Reach for {@link createTool} when you need Mastra-only fields
+ * (`outputSchema`, `suspendSchema`, `requireApproval`, `mcp`, etc.).
+ */
+declare function tool(opts: AppKitToolOptions): Tool;
+/**
+ * Input shape for the AppKit-style {@link tool} factory. A trimmed
+ * subset of Mastra's `createTool` options that mirrors the
+ * `@databricks/appkit/beta` `tool({ description, schema, execute })`
+ * signature.
+ *
+ * Generics are intentionally absent - inference flows through the
+ * caller's `schema` (typically a Zod object), and the `execute` body
+ * destructures naturally from that. Reach for {@link createTool} when
+ * you need the fully-typed input/output schemas wired explicitly.
+ */
+interface AppKitToolOptions {
+  /** Optional stable identifier; auto-derived from `description` when omitted. */
+  id?: string;
+  /** Human-readable description shown to the model. Required. */
+  description: string;
+  /**
+   * Optional input schema (any Standard Schema instance, e.g. Zod).
+   * Maps to Mastra's `inputSchema`; passed through to the model
+   * verbatim.
+   */
+  schema?: unknown;
+  /**
+   * Execute body. First arg is the parsed input (typed off `schema`
+   * when supplied), second arg is the full Mastra execution context
+   * (request context, abort signal, mastra instance) if you need it.
+   */
+  execute: (input: any, context?: unknown) => unknown;
+}
+/**
+ * Identity helper that brands a definition as a Mastra agent. Mirrors
+ * AppKit's `createAgent(def)` so the registration shape matches:
+ *
+ * ```ts
+ * const support = createAgent({
+ *   instructions: "...",
+ *   model: "databricks-claude-sonnet-4-6",
+ *   tools(plugins) { return { ... }; },
+ * });
+ * ```
+ *
+ * Returns the definition unchanged - the wrapper exists only to anchor
+ * type inference and to match the AppKit API surface.
+ */
+declare function createAgent<T extends MastraAgentDefinition>(def: T): T;
+/**
+ * Filter / rename options accepted by every plugin's `.toolkit()`
+ * method. Mirrors AppKit's `ToolkitOptions` verbatim so options pass
+ * through unchanged - the underlying AppKit plugin does the filtering
+ * and we just adapt the resulting entries into Mastra tools.
+ */
+interface ToolkitOptions {
+  /**
+   * Key prefix prepended to every tool name. AppKit's default is
+   * `${pluginName}.` when omitted; pass an explicit `""` to drop it.
+   */
+  prefix?: string;
+  /** Allowlist of local tool names. */
+  only?: string[];
+  /** Denylist of local tool names. */
+  except?: string[];
+  /** Remap specific local names to different keys. */
+  rename?: Record<string, string>;
+}
+/**
+ * Toolkit provider shape every entry in the {@link MastraPlugins} map
+ * exposes. Identical to AppKit's `PluginToolkitProvider` - any AppKit
+ * plugin that implements the standard `ToolProvider` interface
+ * (`getAgentTools` + `executeAgentTool` + `toolkit`) is reachable
+ * through this surface automatically.
+ */
+interface MastraPluginToolkitProvider {
+  /**
+   * Returns a Mastra-shaped tools record adapted from the plugin's
+   * agent tools. Each tool dispatches back through the plugin's
+   * `executeAgentTool` so OBO auth and telemetry spans stay intact.
+   */
+  toolkit(opts?: ToolkitOptions): MastraTools;
+}
+/**
+ * Plugin map handed to the function form of
+ * {@link MastraAgentDefinition.tools}. Mirrors AppKit's `Plugins`
+ * type exactly: a string-keyed record where every value exposes
+ * `.toolkit(opts)`.
+ *
+ * Implemented as a runtime Proxy that auto-discovers any registered
+ * AppKit plugin implementing the standard `ToolProvider` interface
+ * (`analytics`, `files`, `lakebase`, `genie`, plus any third-party
+ * plugin that does the same). Unknown names resolve to `undefined`
+ * at runtime, so guard with `?.` and `?? {}` when spreading from a
+ * plugin that may not be registered in every environment.
+ *
+ * @example
+ * ```ts
+ * createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       ...plugins.analytics.toolkit(),
+ *       ...plugins.files.toolkit({ only: ["uploads.read"] }),
+ *       get_weather: tool({
+ *         description: "Weather",
+ *         schema: z.object({ city: z.string() }),
+ *         execute: async ({ city }) => `Sunny in ${city}`,
+ *       }),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+type MastraPlugins = Record<string, MastraPluginToolkitProvider>;
+/** Function form of {@link MastraAgentDefinition.tools}. */
+type MastraToolsFn = (plugins: MastraPlugins) => MastraTools | Promise<MastraTools>;
+/**
+ * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
+ * plugin uses for `AgentDefinition`. The registry key under
+ * `config.agents` is the `agentId` the client streams against; `name`
+ * is purely informational (defaults to the key).
+ */
+interface MastraAgentDefinition {
+  /** Display name used as `Agent.name`. Defaults to the registry key. */
+  name?: string;
+  /** Optional long-form description; surfaced as `Agent.description`. */
+  description?: string;
+  /** System prompt body. */
+  instructions: string;
+  /**
+   * Per-agent model override.
+   *
+   * - `undefined` (default): falls back to the workspace
+   *   `/serving-endpoints` resolver that {@link buildModel} configures
+   *   from the per-request `WorkspaceClient`.
+   * - `string`: shorthand for "use the default resolver but swap the
+   *   `modelId`" (e.g. `"databricks-meta-llama-3-3-70b-instruct"`).
+   * - Any other Mastra `DynamicArgument<MastraModelConfig>`: passed
+   *   straight through to `Agent.model`. Use this when you need full
+   *   control over auth or providerId.
+   */
+  model?: AgentConfig["model"] | string;
+  /**
+   * Per-agent tool record. Either a plain map or a callback that
+   * receives the typed {@link MastraPlugins} sibling-plugin index and
+   * returns a map. The callback runs exactly once at agent setup; the
+   * result is cached for the agent's lifetime.
+   */
+  tools?: MastraTools | MastraToolsFn;
+  /**
+   * Per-agent semantic recall (PgVector) override. Cascades from
+   * `config.memory`; the agent value wins when set.
+   *
+   * - `undefined` (default): inherit `config.memory`. When that's
+   *   enabled, the agent **shares the plugin-level singleton `PgVector`
+   *   instance** (cross-agent semantic recall across the same index).
+   * - `false`: disable semantic recall for this agent only.
+   * - `true`: enable using the shared singleton (same as default when
+   *   plugin memory is enabled; useful to opt in when plugin disabled).
+   * - {@link MastraMemoryConfig} object: dedicated `PgVector` for this
+   *   agent (private recall index). Bypasses the shared singleton.
+   */
+  memory?: boolean | MastraMemoryConfigOverride;
+  /**
+   * Per-agent thread/message storage (`PostgresStore`) override.
+   * Cascades from `config.storage`; the agent value wins when set.
+   *
+   * - `undefined` (default): inherit `config.storage`. When that's
+   *   enabled, the agent gets its **own per-agent `PostgresStore`**
+   *   keyed by `schemaName: "mastra_<agentId>"` so threads and
+   *   messages stay isolated between agents in the same database.
+   * - `false`: disable storage for this agent only (purely in-memory).
+   * - `true`: enable with the per-agent default schema.
+   * - {@link MastraStorageConfigOverride} object: dedicated
+   *   `PostgresStore` config (custom schema, connection, etc.).
+   */
+  storage?: boolean | MastraStorageConfigOverride;
+}
+/**
+ * Distributive `Omit` so unions in `PostgresStoreConfig` /
+ * `PgVectorConfig` keep their discriminants after the override types
+ * strip `id`. The built-in `Omit` collapses unions to one shape with
+ * common fields only, which loses the connection-style discriminants.
+ */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+/**
+ * `PostgresStoreConfig` minus `id` - per-agent overrides accept any
+ * Mastra-supported storage shape. `id` is filled in automatically
+ * from the agent registry key so traces stay stable.
+ */
+type MastraStorageConfigOverride = DistributiveOmit<PostgresStoreConfig, "id"> & {
+  id?: string;
+};
+/**
+ * `PgVectorConfig` minus `id` - per-agent overrides accept any
+ * Mastra-supported vector shape. `id` is filled in automatically
+ * from the agent registry key.
+ */
+type MastraMemoryConfigOverride = DistributiveOmit<PgVectorConfig, "id"> & {
+  id?: string;
+};
+/** Output of {@link buildAgents}: resolved agents plus the default id. */
+interface BuiltAgents {
+  agents: Record<string, Agent>;
+  defaultAgentId: string;
+  /**
+   * Ambient tools shared across every agent (the built-in system tools
+   * spread with `config.tools`). Surfaced so the optional MCP server
+   * can re-expose them when {@link MastraMcpConfig.tools} is enabled.
+   */
+  ambientTools: MastraTools;
+}
+/** Fallback agent id used when `config.agents` is omitted entirely. */
+declare const FALLBACK_AGENT_ID = "default";
+/**
+ * Default per-turn step ceiling applied to every registered agent
+ * when {@link MastraPluginConfig.agentMaxSteps} is unset. 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 - well above Mastra's own `agent.generate` default of
+ * 5, which would cut multi-step orchestration off mid-loop.
+ */
+declare const DEFAULT_AGENT_MAX_STEPS = 25;
+/**
+ * Style guardrails appended to every agent's `instructions` to curb
+ * common LLM-isms (em dashes, emojis, sycophantic openers, excessive
+ * hedging, throwaway closers). Appended rather than prepended so the
+ * agent's role/context comes first; the model's recency bias then
+ * helps the style rules dominate the response surface.
+ *
+ * Override globally via {@link MastraPluginConfig.styleInstructions}
+ * (pass `false` to disable entirely, or a string to replace).
+ */
+declare const DEFAULT_STYLE_INSTRUCTIONS: string;
+/**
+ * Resolve every entry in `config.agents` into a Mastra `Agent`
+ * instance. When `config.agents` is omitted the plugin registers a
+ * single built-in `default` analyst so the bare `mastra()` call still
+ * yields a working agent.
+ *
+ * Per-agent tool callbacks are invoked once with a typed
+ * {@link MastraPlugins} index built from registered sibling plugins
+ * (currently `genie`; extend `MastraPlugins` to surface more).
+ *
+ * @throws when `config.defaultAgent` is set to an id that isn't in the
+ *   resolved registry; this is a wiring bug, not a runtime condition.
+ */
+declare function buildAgents(opts: {
+  config: MastraPluginConfig;
+  context: appkitUtils.PluginContextLike | undefined;
+  memoryBuilder?: MemoryBuilder;
+  log: logUtils.Logger;
+}): Promise<BuiltAgents>;
+//#endregion
+//#region packages/appkit-mastra/src/chart.d.ts
+/**
+ * Canonical planner input shape. Tools that source rows from an
+ * inline dataset (`render_data`) use it as their `inputSchema`
+ * verbatim; tools that resolve rows from a remote (`prepare_chart`
+ * over a Genie statement) `omit({ data })` and `extend` with their
+ * own identifier field, so the field-level `.describe()` text
+ * stays a single source of truth. Server-only - the UI never
+ * sees a planner request, only the resolved {@link Chart}.
+ */
+declare const chartPlannerRequestSchema: z.ZodObject<{
+  title: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  data: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+type ChartPlannerRequest = z.infer<typeof chartPlannerRequestSchema>;
+/** Inputs to {@link prepareChart}. */
+interface PrepareChartOptions {
+  /** Plugin config; resolves the planner agent's model. */
+  config: MastraPluginConfig;
+  /** Display title forwarded to the planner agent. */
+  title?: string;
+  /** Optional intent hint forwarded to the planner agent. */
+  description?: string;
+  /**
+   * Resolves the rows to chart. Called once, in the background.
+   * Any thrown error lands in the cache as the entry's `error`
+   * field (never propagated to the caller of {@link prepareChart}).
+   * An empty `rows` array is rejected as `"dataset has no rows;
+   * nothing to chart"`.
+   */
+  resolveData: (signal?: AbortSignal) => Promise<{
+    rows: ReadonlyArray<Record<string, unknown>>;
+  }>;
+  /**
+   * Per-request `RequestContext`. Forwarded to the planner agent so
+   * user-scoped model resolution (OBO) stays in effect.
+   */
+  requestContext?: RequestContext;
+  /**
+   * Cooperative cancellation. Forwarded to `resolveData` and the
+   * planner agent. Note: the chart task continues running in the
+   * background after the parent request ends, so external abort
+   * signals are best-effort; typical use is to leave this unset
+   * and let the 1h TTL cap stale entries.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Mint a `chartId`, cache an empty `{ chartId }` placeholder
+ * synchronously, and kick off a background task that resolves the
+ * dataset and runs the planner. Returns the `chartId` once the
+ * placeholder lands so the first {@link fetchChart} call always
+ * sees an entry (no spurious 404 race).
+ *
+ * The background task swallows its own failures and writes them
+ * as `error` entries, so callers never see a rejected promise.
+ * Cache state machine:
+ *
+ *   - just after this call returns: `{ chartId }` (processing)
+ *   - on planner success:           `{ chartId, result }`
+ *   - on data / planner failure:    `{ chartId, error }`
+ */
+declare function prepareChart(opts: PrepareChartOptions): Promise<{
+  chartId: string;
+}>;
+/** Inputs to {@link fetchChart}. */
+interface FetchChartOptions {
+  /**
+   * Server-side polling budget in ms. When the entry stays in
+   * the processing state past this window, the helper returns the
+   * last seen value (still processing) so the client can re-poll.
+   * Defaults to {@link DEFAULT_FETCH_TIMEOUT_MS} (60s).
+   */
+  timeoutMs?: number;
+  /**
+   * Poll interval in ms. Defaults to
+   * {@link DEFAULT_FETCH_INTERVAL_MS} (250ms).
+   */
+  intervalMs?: number;
+  /** External cancellation handle (e.g. request `req.signal`). */
+  signal?: AbortSignal;
+}
+/**
+ * Long-poll the chart cache until the entry settles (`result` or
+ * `error` set), the entry is missing, or the server-side timeout
+ * elapses.
+ *
+ * Returns:
+ *   - the resolved {@link Chart} when it settled, errored, or
+ *     stayed in processing past `timeoutMs` (so the client can
+ *     re-poll);
+ *   - `undefined` when the entry is missing or expired (the
+ *     consumer should treat as 404).
+ *
+ * `signal` lets the caller cancel ahead of timeout (e.g. the HTTP
+ * request closed). Cancellation propagates to the inter-poll sleep
+ * so the helper returns immediately.
+ */
+declare function fetchChart(chartId: string, options?: FetchChartOptions): Promise<Chart | undefined>;
+/**
+ * Build the `render_data` Mastra tool bound to the given plugin
+ * config. Auto-wired as a system tool on every agent (see
+ * `agents.ts`); per-agent tools can shadow it by registering a
+ * same-named entry.
+ *
+ * Thin wrapper over {@link prepareChart} for callers that already
+ * have a dataset in hand. Mints a `chartId` synchronously, caches
+ * an empty placeholder, and kicks off the chart-planner in the
+ * background. Returns just the `chartId`; the host UI resolves
+ * `[chart:<chartId>]` markers by hitting the plugin's
+ * `/embed/chart/:id` route.
+ *
+ * For Genie statement results, prefer the Genie agent's
+ * `prepare_chart` tool, which accepts a `statement_id` and
+ * resolves the rows lazily.
+ */
+declare function buildRenderDataTool(config: MastraPluginConfig): _mastra_core_tools0.Tool<{
+  title: string;
+  data: readonly Record<string, unknown>[];
+  description?: string | undefined;
+}, {
+  chartId: string;
+}, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;
+//#endregion
+//#region packages/appkit-mastra/src/mcp.d.ts
+/**
+ * A built MCP server plus the request paths it answers on, relative to
+ * the plugin's base path (`/api/<plugin>`). The paths are informational
+ * (logging / `exports().getMcp()`); the routes themselves are mounted
+ * by `@mastra/express` off the `Mastra` instance's `mcpServers`.
+ */
+interface ResolvedMcp {
+  /** Registry id, used in the route path (`/mcp/<serverId>/...`). */
+  serverId: string;
+  /** The Mastra MCP server to hand to `new Mastra({ mcpServers })`. */
+  server: MCPServer;
+  /** Streamable-HTTP transport path, relative to the plugin base path. */
+  httpPath: string;
+  /** SSE transport path, relative to the plugin base path. */
+  ssePath: string;
+  /** SSE message path, relative to the plugin base path. */
+  messagePath: string;
+}
+/**
+ * Build the plugin's MCP server, or `null` when `config.mcp` is falsy
+ * (the default - no MCP endpoints).
+ *
+ * `true` exposes every registered agent as an `ask_<agentId>` MCP tool
+ * under a server id equal to the plugin name. The object form
+ * ({@link MastraMcpConfig}) tunes the id / advertised metadata and can
+ * additionally expose the plugin's ambient tools or a set of extra
+ * MCP-only tools.
+ */
+declare function buildMcpServer(opts: {
+  config: MastraPluginConfig;
+  pluginName: string;
+  displayName: string;
+  agents: Record<string, Agent>;
+  ambientTools: MastraTools;
+}): ResolvedMcp | null;
+//#endregion
+//#region packages/appkit-mastra/src/server.d.ts
+/**
+ * `@mastra/express` subclass that stamps `RequestContext` with the
+ * AppKit user, resource id, and a thread id backed by an HTTP-only
+ * session cookie (`appkit_<plugin-name>_session_id`).
+ */
+declare class MastraServer$1 extends MastraServer {
+  private config;
+  private log;
+  constructor(config: MastraPluginConfig, ...args: ConstructorParameters<typeof MastraServer>);
+  registerAuthMiddleware(): void;
+  configureRequestContextUser(requestContext: RequestContext): void;
+  /**
+   * Stamp a per-request id and echo it on the response so an upstream
+   * proxy / curl client / browser-side log line can pair its view of
+   * the request with the matching trace span. Reuses `X-Request-Id`
+   * when the upstream already supplies one so multi-hop traces stay
+   * joined; otherwise mints a UUIDv4.
+   *
+   * The id is surfaced as `mastra__requestId` span metadata via
+   * {@link TRACE_REQUEST_CONTEXT_KEYS} and as the `X-Request-Id`
+   * response header so dev tools can copy it from either side.
+   */
+  configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  configureRequestContextThreadId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  configureRequestContextModelOverride(req: express.Request, requestContext: RequestContext): void;
+}
+//#endregion
+//#region packages/appkit-mastra/src/plugin.d.ts
+/**
+ * AppKit plugin (registered name: `mastra`) that hosts Mastra agents
+ * with optional Lakebase-backed memory and AI SDK chat routes under
+ * the plugin mount (typically `/api/mastra`).
+ */
+declare class MastraPlugin extends Plugin<MastraPluginConfig> {
+  static manifest: {
+    name: "mastra";
+    displayName: string;
+    description: string;
+    stability: "beta";
+    resources: {
+      required: never[];
+      optional: Omit<ResourceRequirement, "required">[];
+    };
+  };
+  /**
+   * Tighten resource requirements based on which features are enabled.
+   * AppKit calls this at registration time (config-aware) so disabled
+   * features don't surface their resource asks to the host app.
+   */
+  static getResourceRequirements(config: MastraPluginConfig): ResourceRequirement[];
+  private log;
+  private built;
+  private mastra;
+  private mastraApp;
+  private mastraServer;
+  /**
+   * The optional MCP server exposing this plugin's agents / tools, or
+   * `null` when `config.mcp` is disabled (the default). Built in
+   * {@link buildAgentAndServer} and registered on the Mastra instance.
+   */
+  private mcp;
+  /**
+   * Dedicated service-principal Lakebase pool backing Mastra memory /
+   * storage. Built once in {@link buildAgentAndServer} (outside any
+   * `asUser` scope, so it never inherits a request's OBO identity) and
+   * drained in {@link abortActiveOperations}. `null` until setup runs
+   * or when Lakebase isn't needed.
+   */
+  private servicePrincipalPool;
+  setup(): Promise<void>;
+  /**
+   * When the `lakebase` plugin is registered, auto-enable `storage`
+   * and `memory` unless the caller opted out explicitly (`false` or a
+   * custom config object). Run after `setup:complete` so the lookup
+   * is reliable: any plugin that registers itself synchronously is
+   * already in the registry by the time this fires.
+   */
+  private applyLakebaseAutoDefaults;
+  /**
+   * Drain the memory service-principal pool on shutdown. AppKit calls
+   * this during teardown; the lakebase plugin closes its own SP / OBO
+   * pools the same way. Fire-and-forget so shutdown isn't blocked on a
+   * slow drain, and clear the handle so a re-`setup()` rebuilds it.
+   */
+  abortActiveOperations(): void;
+  exports(): {
+    /**
+     * Ids of every registered agent in registration order. Matches
+     * AppKit `agents.list()` so callers can iterate the registry the
+     * same way under both plugins.
+     */
+    list: () => string[];
+    /**
+     * Look up a registered agent by id. Returns `null` (not
+     * undefined) when unknown so call sites can early-return without
+     * a separate `in` check.
+     */
+    get: (id: string) => Agent | null;
+    /**
+     * The agent the client converses with when it doesn't name one.
+     * Resolves to `config.defaultAgent`, the first registered id, or
+     * the built-in `default` fallback.
+     */
+    getDefault: () => Agent | null; /** Underlying Mastra instance for advanced use (custom routes etc.). */
+    getMastra: () => Mastra<Record<string, Agent<any, _mastra_core_agent0.ToolsInput, undefined, unknown, _mastra_core_agent0.AgentEditorConfig | undefined>>, Record<string, _mastra_core_workflows0.AnyWorkflow>, Record<string, _mastra_core_vector0.MastraVector<any>>, Record<string, _mastra_core_tts0.MastraTTS>, _mastra_core_logger0.IMastraLogger, Record<string, _mastra_core_mcp0.MCPServerBase<any>>, Record<string, _mastra_core_evals0.MastraScorer<any, any, any, any>>, Record<string, _mastra_core_tools0.ToolAction<any, any, any, any, any, any, unknown>>, Record<string, _mastra_core_processors0.Processor<any, unknown>>, Record<string, _mastra_core_memory0.MastraMemory>, Record<string, _mastra_core_channels0.ChannelProvider>> | null;
+    /**
+     * MCP endpoint info when `config.mcp` is enabled, else `null`.
+     * Paths are absolute (under the plugin mount), ready to hand to an
+     * MCP client. Streamable HTTP is `http`; the SSE pair is the
+     * legacy transport.
+     */
+    getMcp: () => {
+      serverId: string;
+      http: string;
+      sse: string;
+      messages: string;
+    } | null; /** Express subapp Mastra is mounted on; mostly for tests. */
+    getMastraServer: () => MastraServer$1 | null;
+    /**
+     * Fetch the workspace's Model Serving endpoints (cached). Same
+     * payload the `GET /models` route returns; surfaced here so
+     * other plugins / scripts can introspect the catalogue without
+     * an HTTP round-trip. AppKit wraps this with `asUser(req)` for
+     * OBO scoping automatically.
+     */
+    listModels: () => Promise<ServingEndpointSummary[]>;
+    /**
+     * Force-evict cached endpoint listings via AppKit's
+     * `CacheManager`. Useful in tests or right after an admin
+     * deploys a new endpoint and doesn't want to wait for the TTL.
+     * Returns the underlying `CacheManager.delete`/`clear` promise.
+     */
+    clearModelsCache: (host?: string) => Promise<void>;
+  };
+  clientConfig(): Record<string, unknown>;
+  injectRoutes(router: IAppRouter): void;
+  /**
+   * Invoke the Mastra express sub-app. Exists as a method (instead of reading
+   * `this.mastraApp` through the `asUser(req)` proxy at the call site) so the
+   * proxy binds this plain method - whose `.bind` is `Function.prototype.bind`
+   * - rather than the express app, whose `.bind` is the HTTP BIND route
+   * registrar (see the note in `injectRoutes`). Runs inside the user scope so
+   * `getExecutionContext()` returns the OBO client for the agent/model
+   * resolvers.
+   */
+  private dispatchMastra;
+  /**
+   * Implementation backing the `/suggestions` route. Runs inside the
+   * AppKit user-context proxy so `getExecutionContext()` returns the
+   * OBO-scoped client. Resolves the plugin's Genie spaces and merges
+   * their curated `sample_questions` (see {@link collectSpaceSuggestions}).
+   * Returns `[]` when no Genie space is configured so the client
+   * shows a bare empty state instead of built-in example prompts.
+   */
+  private fetchSuggestions;
+  /**
+   * Implementation backing the `data` embed resolver
+   * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so
+   * `getExecutionContext()` returns the OBO-scoped workspace
+   * client, then reuses the same `fetchStatementData` pipeline
+   * the `get_statement` tool runs so the LLM and the UI see the
+   * exact same shape for the same statement.
+   *
+   * Returns `undefined` for upstream 404s so the route can map
+   * them to a clean HTTP 404; any other failure bubbles up.
+   */
+  private fetchStatement;
+  /**
+   * Return `this.asUser(req)` when the request carries an OBO token,
+   * otherwise return `this` directly. Prevents the noisy AppKit warn
+   * (`asUser() called without user token in development mode. Skipping
+   * user impersonation.`) on every request in local dev where the
+   * browser never sends `x-forwarded-access-token`. Behavior is
+   * unchanged in production: a missing token always means a real OBO
+   * proxy call (and AppKit will throw upstream if that's wrong).
+   */
+  private userScopedSelf;
+  /**
+   * Implementation backing both the `/models` route and the
+   * `listModels` export. Runs inside the AppKit user-context proxy so
+   * `getExecutionContext()` returns the OBO-scoped client.
+   */
+  private listModels;
+  private buildAgentAndServer;
+}
+declare const mastra: _databricks_appkit0.ToPlugin<typeof MastraPlugin, MastraPluginConfig, "mastra">;
+//#endregion
+//#region packages/appkit-mastra/src/serving.d.ts
+/**
+ * `RequestContext` key under which {@link MastraServer} stores the
+ * per-request model override (header / query / body). `model.ts`
+ * reads it before falling back to the agent / plugin default.
+ */
+declare const MASTRA_MODEL_OVERRIDE_KEY = "mastra__model_override";
+/**
+ * Minimal Express-ish request shape used by {@link extractModelOverride}.
+ * Keeps this module independent of `express` so the helper can be
+ * reused from non-Express adapters.
+ */
+interface ModelOverrideRequest {
+  headers?: Record<string, string | string[] | undefined>;
+  query?: Record<string, unknown> | undefined;
+  body?: unknown;
+}
+/**
+ * Pull a model override out of a single HTTP request, checking
+ * sources in priority order:
+ *
+ *   1. `X-Mastra-Model` header
+ *   2. `?model=` query string parameter
+ *   3. Body field (`model` or `modelId`, in that order)
+ *
+ * Returns `null` when nothing is set, so callers can wrap with
+ * `if (override) ...` without juggling empty strings. Body inspection
+ * is lenient - any plain object with one of the configured keys
+ * counts, mirroring how AI SDK chat clients pass arbitrary metadata
+ * alongside `messages`.
+ */
+declare function extractModelOverride(req: ModelOverrideRequest): string | null;
+//#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, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, tool };