@dbx-tools/appkit-mastra 0.1.112 → 0.3.1

package/README.md

@@ -1,44 +1,70 @@
 # @dbx-tools/appkit-mastra
 
-An AppKit plugin that hosts [Mastra](https://mastra.ai) agents inside a
-Databricks App with user-scoped workspace auth (OBO), optional
-Lakebase-backed memory, and the standard Mastra agent stream the React
-client drives via `@mastra/client-js`.
-
-Wiring it up looks the same as the AppKit
-`[agents](https://developers.databricks.com/docs/appkit/v0/plugins/agents)`
-plugin - same `createAgent` / `tool` helpers, same `tools(plugins)`
-callback, same `ToolkitOptions`. Switching a given agent between the two
-is a one-line import change.
-
-The implementation lives under `src/`: agent registration in
-`[agents.ts](src/agents.ts)`, the plugin + routes in
-`[plugin.ts](src/plugin.ts)` / `[server.ts](src/server.ts)`, thread
-history / listing in `[history.ts](src/history.ts)` /
-`[threads.ts](src/threads.ts)`, Model Serving resolution in
-`[model.ts](src/model.ts)` / `[serving.ts](src/serving.ts)`, Genie
-tooling in `[genie.ts](src/genie.ts)`, the chart pipeline in
-`[chart.ts](src/chart.ts)`, Databricks workspace mounts in
-`[workspaces.ts](src/workspaces.ts)` / `[filesystems.ts](src/filesystems.ts)`,
-and MLflow feedback logging in
-`[mlflow.ts](src/mlflow.ts)` (over the shared REST helper in
-`[rest.ts](src/rest.ts)`).
-
-## Quick start
+AppKit plugin and server-side toolkit for hosting Mastra agents inside a
+Databricks App.
+
+Import this package when an AppKit backend needs an agent service with
+Databricks on-behalf-of auth, optional Lakebase-backed memory, Databricks Genie
+tools, model selection, chart/data embeds, MLflow feedback, and MCP exposure.
+The package mounts the standard Mastra agent stream under the AppKit server, so
+clients can use Mastra-compatible chat transports instead of a custom protocol.
+
+Key features:
+
+- AppKit plugin lifecycle integration: routes, setup, shutdown, sibling plugin
+  access, and AppKit request context are handled inside `plugin.mastra()`.
+- Agent composition: define one or more Mastra agents, give each one local tools,
+  AppKit plugin toolkits, workspace skills, model defaults, and approval-gated
+  tools.
+- Databricks execution model: tool calls run with the active AppKit OBO client
+  where available, while storage and background work use service-principal
+  connections.
+- Durable conversations: Lakebase-backed Mastra storage provides thread
+  history, message persistence, and optional vector memory.
+- Rich data answers: Genie tools, statement fetches, chart preparation, and
+  embed markers let an agent answer with text plus delayed chart/table payloads.
+- Operational surfaces: model-list routes, feedback routes, MCP exposure,
+  scoped API gating, tracing, and MLflow feedback are bundled with the plugin.
+
+## Why Not Just AppKit Agents?
+
+Native AppKit includes a beta Agents plugin with markdown and TypeScript agent
+definitions, AppKit tool-provider integration, streaming chat, thread
+management, cancellation, and HITL approval. Use it when you want the AppKit
+agent model and do not need a separate agent framework.
+
+Use this package when you specifically want Mastra inside AppKit:
+
+- Mastra's larger plugin/tool ecosystem, MCP support, memory/storage model,
+  workflow primitives, and `@mastra/client-js` stream shape.
+- AppKit toolkits as Mastra tools, so Analytics, Files, Genie, and other AppKit
+  ToolProvider plugins stay available without rewriting them.
+- Genie as an agent tool that emits typed progress events, result metadata, and
+  delayed chart/data markers into the same assistant turn.
+- A paired React client in [`@dbx-tools/ui-mastra`](../../ui/mastra) with model
+  picking, thread sidebar, approvals, feedback, exports, and inline embeds.
+- Per-request model override and fuzzy endpoint resolution through
+  [`@dbx-tools/model`](../model), instead of binding every agent to a fixed
+  endpoint name.
+
+## Quick Start
 
 ```ts
-import { analytics, createApp, files, lakebase, server } from "@databricks/appkit";
-import { createAgent, mastra, tool } from "@dbx-tools/appkit-mastra";
+import { analytics, createApp, lakebase, server } from "@databricks/appkit";
+import { agents, genie, plugin } from "@dbx-tools/appkit-mastra";
 import { z } from "zod";
 
-const support = createAgent({
-  instructions: "You help customers with data and files.",
+const analyst = agents.createAgent({
+  name: "analyst",
+  instructions: ["You answer questions about workspace data.", genie.GENIE_INSTRUCTIONS].join(
+    "\n\n",
+  ),
   tools(plugins) {
     return {
-      ...plugins.analytics.toolkit(), // every analytics tool
-      ...plugins.files.toolkit({ only: ["uploads.read"] }), // filtered subset
-      get_weather: tool({
-        description: "Weather",
+      ...plugins.analytics.toolkit(),
+      ...plugins.genie?.toolkit(),
+      get_weather: agents.tool({
+        description: "Get a simple weather report.",
         schema: z.object({ city: z.string() }),
         execute: async ({ city }) => `Sunny in ${city}`,
       }),
@@ -50,380 +76,319 @@ await createApp({
   plugins: [
     server(),
     analytics(),
-    files(),
-    // Drop `lakebase()` in and `mastra` auto-enables per-agent thread
-    // storage plus shared semantic recall. Skip it for a stateless agent.
     lakebase(),
-    mastra({ agents: support }),
+    plugin.mastra({
+      agents: { analyst },
+      defaultAgent: "analyst",
+      genie: { spaces: { sales: "01ef..." } },
+    }),
   ],
 });
 ```
 
-`createAgent` is a no-op identity helper that anchors type inference;
-`tool` is the AppKit-shaped factory (`{ description, schema, execute }`)
-that adapts to Mastra's `createTool` under the hood. The full config
-shapes (`MastraAgentDefinition`, the plugin config) - every field and
-default - are typed in `[config.ts](src/config.ts)`.
+Benefits of importing the package:
+
+- `plugin.mastra()` registers a full AppKit plugin named `mastra`.
+- `agents.createAgent()` keeps agent definitions typed and applies the default
+  Databricks workspace/skill mounts.
+- `agents.tool()` lets the same AppKit-shaped tool body work in this Mastra
+  plugin.
+- `genie.GENIE_INSTRUCTIONS` and `plugins.genie.toolkit()` give agents a
+  Databricks Genie workflow without embedding a second agent.
+- Lakebase registration automatically enables durable thread storage and vector
+  memory unless you opt out.
 
-On the React side, drop in the prebuilt chat UI from
-`[@dbx-tools/appkit-mastra-ui](../appkit-mastra-ui)`; it wires itself
-from the plugin's published client config and streams over
-`@mastra/client-js`, so there's no transport code to write:
+## Agent Registration
 
-```tsx
-import { MastraChat } from "@dbx-tools/appkit-mastra-ui/react";
+`plugin.mastra({ agents })` accepts a single definition, an array, or a record.
+Records are best when clients need stable agent ids:
 
-export default function ChatPage() {
-  return <MastraChat showModelPicker />;
-}
+```ts
+plugin.mastra({
+  agents: {
+    support: agents.createAgent({ instructions: "Answer support questions." }),
+    analyst: agents.createAgent({ instructions: "Analyze workspace data." }),
+  },
+  defaultAgent: "support",
+});
 ```
 
-## Memory + storage
+When no agents are supplied, the plugin registers a built-in `default` analyst so
+the route surface still works for smoke tests. Each agent is streamed through the
+Mastra agent API mounted below the plugin path, typically `/api/mastra`.
 
-With no config, memory and storage are driven entirely by whether the
-`lakebase` plugin is registered:
+Use `agents.createTool` when you need Mastra-native fields such as
+`outputSchema`, `suspendSchema`, `requireApproval`, or MCP metadata. Use
+`agents.tool` for the smaller AppKit-compatible shape:
 
-- **No** `lakebase()` - the agent is fully stateless: no threads, no
-  recall.
-- `lakebase()` **registered** - both auto-enable. Each agent gets its
-  own `PostgresStore` schema (threads stay isolated per agent); every
-  agent shares one `PgVector` semantic-recall index.
+```ts
+const approveRefund = agents.createTool({
+  id: "approve_refund",
+  description: "Approve a refund request.",
+  inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
+  requireApproval: true,
+  execute: async ({ context }) => approve(context.orderId, context.amount),
+});
+```
 
-Override per plugin or per agent by passing `memory` / `storage` as
-`false` (opt out), `true` (explicit on), or a config object (dedicated
-index / schema). The fields are typed in `[config.ts](src/config.ts)`;
-the wiring is in `[memory.ts](src/memory.ts)`.
+## AppKit Toolkits
 
-## Workspace and Assistant skills
+The `tools(plugins)` callback receives a dynamic index of registered AppKit
+tool-provider plugins. Each entry exposes `.toolkit(opts)` with AppKit-compatible
+`prefix`, `only`, `except`, and `rename` options.
 
-Every `createAgent` call applies a Mastra `Workspace` by default via
-`createWorkspace()` (`[workspaces.ts](src/workspaces.ts)`). The
-workspace is resolved per request and backed by the OBO user's
-`WorkspaceClient` through `[filesystems.ts](src/filesystems.ts)`.
+```ts
+const agent = agents.createAgent({
+  instructions: "Use the narrowest tool that answers the question.",
+  tools(plugins) {
+    return {
+      ...plugins.analytics.toolkit({ only: ["query"] }),
+      ...plugins.files?.toolkit({ prefix: "files.", except: ["delete"] }),
+    };
+  },
+});
+```
 
-Unless you opt out, `assistantSkills: true` mounts read-only Databricks
-trees where Mastra looks for `SKILL.md` files:
+Tool calls dispatch back through the owning AppKit plugin, preserving OBO auth
+and AppKit telemetry behavior. Optional plugins should be guarded with `?.` when
+you spread their tools.
 
-| Databricks path                    | Workspace mount          |
-| ---------------------------------- | ------------------------ |
-| `/Workspace/.assistant/skills`     | `/workspace_skills`      |
-| `/Users/<email>/.assistant/skills` | `/workspace_user_skills` |
+## Memory And Storage
 
-Production mounts require `workspace` or `all-apis` on the forwarded
-access token. `[server.ts](src/server.ts)` stamps parsed scopes on
-`MASTRA_SCOPES_KEY` using `tokenUtils` from `@dbx-tools/shared`.
-`NODE_ENV=development` skips the scope gate.
+The `memory` and `storage` config fields can be `false`, `true`, or a concrete
+Mastra Postgres/PgVector config.
 
 ```ts
-import { createAgent, createWorkspace } from "@dbx-tools/appkit-mastra";
+plugin.mastra({
+  agents: analyst,
+  storage: true,
+  memory: { id: "analytics_memory", tableName: "agent_memory" },
+});
+```
+
+With `lakebase()` registered, both default to enabled:
+
+- storage uses a per-agent schema for durable threads and messages;
+- memory uses a shared vector index for semantic recall;
+- the service-principal pool is created outside any request so OBO user
+  identities are not captured in background storage work.
+
+Without `lakebase()`, agents are stateless unless you provide explicit storage
+and memory configs.
+
+## Workspace Skills
 
-// Default: Assistant skills on.
-const support = createAgent({ instructions: "..." });
+Every `agents.createAgent()` gets a default Mastra `Workspace` from
+`workspaces.createWorkspace()`. It mounts Databricks Workspace files through the
+current OBO user's `WorkspaceClient`, so Mastra can discover Assistant-style
+`SKILL.md` files at request time.
 
-// Extra per-request mounts (merged with built-in skill mounts).
-const analyst = createAgent({
-  instructions: "...",
-  workspace: createWorkspace({
+```ts
+const agent = agents.createAgent({
+  instructions: "Use mounted workspace skills when relevant.",
+  workspace: workspaces.createWorkspace({
+    assistantSkills: true,
     mounts: [
       async () => ({
-        mounts: { "/data": myFilesystem },
-        skillPaths: [],
+        mounts: { "/reference": myFilesystem },
+        skillPaths: ["/reference/skills"],
       }),
     ],
   }),
 });
-
-// Disable built-in skill mounts.
-const bare = createAgent({
-  instructions: "...",
-  workspace: createWorkspace({ assistantSkills: false }),
-});
-```
-
-Exported for direct use: `createWorkspace`, `DatabricksWorkspaceFilesystem`,
-`emptyFilesystem`, and path helpers (`normalizeDatabricksBasePath`,
-`isDbfsPath`, `resolveDatabricksAbsolutePath`, ...).
-
-## Conversations (threads)
-
-When storage is on, a user owns many conversation threads. The plugin
-resolves the thread a request targets from `RequestContext`, in order:
-
-1. A **client-selected thread id** - the thread-selection header
-   (`x-mastra-thread-id`) or `?threadId=` query. This is how the chat UI
-   references a specific conversation: it picks an id from the threads
-   listing (or mints one for a new chat) and stamps it on every call, so
-   streaming, history, and clear all target that thread.
-2. The **per-session cookie** (`appkit_<plugin-name>_session_id`), minted
-   on first contact, as the single-thread fallback for clients that
-   don't manage threads explicitly.
-
-The thread id pins both `agent.stream()` persistence and the history /
-threads routes, so client and server can never disagree on which
-conversation is active. Two custom routes back the UI's conversation
-management (registered alongside `/route/history`):
-
-- `GET /route/threads` (`/route/threads/:agentId`) - one page of the
-  caller's threads, newest first, **scoped to the caller's resource** so
-  a user only ever sees their own conversations.
-- `DELETE /route/threads` - delete the targeted thread (id from the
-  thread-selection header). Ownership is enforced server-side: a thread
-  is only removed when it belongs to the caller.
-- `PATCH /route/threads` - rename the targeted thread (id from the
-  thread-selection header) to the `{ title }` in the JSON body. Same
-  ownership enforcement; existing thread metadata is preserved.
-
-Each thread is auto-titled from its opening turn (Mastra's
-`generateTitle`), but titling runs on the **small / fast chat tier**
-(`ModelClass.ChatFast`) via the dedicated summarizer in
-`[summarize.ts](src/summarize.ts)` - not the agent's primary model - so
-naming a conversation never spends the heavyweight model. The route
-handlers live in `[threads.ts](src/threads.ts)`; the thread-id
-resolution is in `[server.ts](src/server.ts)`. The drop-in `MastraChat`
-from `@dbx-tools/appkit-mastra-ui` renders the whole conversation sidebar
-over these routes with no extra wiring.
-
-### Summarization (`summarize` tool)
-
-Every agent gets a system-default ambient `summarize` tool that condenses
-arbitrary text (long content, notes, transcripts, bulky tool results) on
-the small / fast chat tier instead of the agent's primary model. It takes
-`text` plus optional `instructions` (e.g. "one sentence", "list the action
-items") and a `maxWords` soft cap, and returns `{ summary }`. The same
-small-tier summarizer backs conversation titling above. Shadow it by
-defining a same-named tool in `config.tools` (or a per-agent `tools`), and
-reuse it programmatically via the exported `summarizeText(config, text, opts)` / `buildSummarizeTool(config)`.
-
-## The `tools(plugins)` callback
-
-Each agent supplies either a static `tools: { ... }` record or a
-`tools(plugins)` callback. The returned record accepts any tool shape
-Mastra understands - Mastra `createTool` tools, AppKit-shaped `tool()`
-tools, Vercel AI SDK tools, provider-defined tools, and toolkits from
-`plugins.<name>.toolkit(...)`.
-
-```ts
-tools(plugins) {
-  return {
-    ...plugins.analytics.toolkit(),                       // every analytics tool
-    ...plugins.files.toolkit({ only: ["uploads.read"] }), // filtered subset
-    get_weather: tool({
-      description: "Weather",
-      schema: z.object({ city: z.string() }),
-      execute: async ({ city }) => `Sunny in ${city}`,
-    }),
-  };
-}
 ```
 
-`plugins` is a runtime Proxy that auto-discovers any registered AppKit
-`ToolProvider` plugin (`analytics`, `files`, `lakebase`, `genie`, and
-any third-party plugin implementing the standard toolkit interface).
-Tool calls dispatch through the plugin's `executeAgentTool`, so OBO auth
-and telemetry spans stay intact. Plugins that aren't registered resolve
-to `undefined`, so guard optional backings with `?.` / `?? {}`.
-
-`toolkit(opts)` takes the same `ToolkitOptions` AppKit exposes
-(`prefix`, `only`, `except`, `rename`), passed through verbatim.
+Production workspace mounts require a forwarded token with `workspace`,
+`workspace.workspace`, or `all-apis` scope. Development mode skips that gate for
+local iteration.
 
-### `tool()` vs `createTool()`
+## Genie Tools
 
-`tool()` mirrors `@databricks/appkit/beta`'s shape so tool code is
-portable between the AppKit `agents` plugin and this one. Reach for
-Mastra's `createTool` when you need Mastra-only fields (`outputSchema`,
-`suspendSchema`, `requireApproval`, `mcp`, ...). An omitted `tool()` `id`
-is auto-derived from the description (slug + short hash) so traces stay
-stable across runs.
+`genie.buildGenieTools()` and `plugins.genie.toolkit()` expose tools for:
 
-## Genie
+- asking a configured Genie space;
+- reading space descriptions and serialized space metadata;
+- fetching statement rows by `statement_id`;
+- preparing charts from Genie result sets.
 
-`plugins.genie` returns a flat set of Mastra tools the central agent
-drives directly - no inner orchestrator agent. The agent asks the
-configured Genie space focused sub-questions, embeds inline markers in
-its prose, and the host UI resolves them (see [Embeds](#embeds)).
-
-The orchestration prompt ships as the exported `GENIE_INSTRUCTIONS`
-string; compose it into your agent's `instructions` to get the canonical
-behavior:
+The central agent drives those tools directly. Genie events stream through the
+Mastra writer using the shared contract from
+[`@dbx-tools/shared-mastra`](../../shared/mastra), so clients can show thinking,
+SQL, row counts, summaries, chart markers, and data markers as the turn runs.
 
 ```ts
-import { createAgent, GENIE_INSTRUCTIONS } from "@dbx-tools/appkit-mastra";
-
-const support = createAgent({
-  instructions: `${baseInstructions}\n\n${GENIE_INSTRUCTIONS}`,
+const agent = agents.createAgent({
+  instructions: `${baseInstructions}\n\n${genie.GENIE_INSTRUCTIONS}`,
   tools(plugins) {
-    return { ...plugins.genie?.toolkit() };
+    return { ...plugins.genie?.toolkit({ prefix: "" }) };
   },
 });
 ```
 
-AppKit's stock `genie()` plugin is honored only for its `spaces` config
-(and the matching `app.yaml` resources); the tools talk to Genie
-directly via `@dbx-tools/genie` (`genieEventChat`) and the workspace
-`statementExecution` API. Each Genie turn forwards its wire
-`GenieChatEvent`s through `ctx.writer` for live UI progress. The exact
-tool set, ids, and writer-event contract live in `[genie.ts](src/genie.ts)`
-and the `GenieWriterEvent` docs in
-`[@dbx-tools/appkit-mastra-shared](../appkit-mastra-shared)`.
-
-## Embeds
-
-Charts and data tables ride out-of-band via inline markers so the model
-never blocks on or round-trips large payloads:
-
-- `render_data` (a system-default ambient tool) and the Genie
-  `prepare_chart` tool both mint a `chartId` synchronously, kick chart
-  planning into the background, and return `{ chartId }` immediately. The
-  model embeds `[chart:<chartId>]` on its own line where the chart should
-  appear.
-- `[data:<statement_id>]` markers resolve to inline table data.
-
-The host UI splits the assistant text on these markers and long-polls
-the plugin's generic `${basePath}/embed/:type/:id` route until each
-entry settles. Cache entries carry a 1h TTL; after expiry the route
-404s and the marker falls through harmlessly. Implementation and the
-placement contract are in `[chart.ts](src/chart.ts)`; the wire shapes
-are in `[@dbx-tools/appkit-mastra-shared](../appkit-mastra-shared)`.
-
-## Feedback (MLflow)
-
-When MLflow tracing is wired for the deployment, the plugin lets users
-rate an assistant turn (thumbs up / down) and leave a comment, logged as
-a HUMAN [assessment](https://mlflow.org/docs/latest/genai/assessments/)
-on that turn's trace and attributed to the signed-in (OBO) user.
-
-Enablement is auto-detected: it turns on when an OTLP exporter endpoint
-(`OTEL_EXPORTER_OTLP_ENDPOINT` / `..._TRACES_ENDPOINT`) **and** an MLflow
-experiment (`MLFLOW_EXPERIMENT_ID` / `MLFLOW_EXPERIMENT_NAME`) are
-configured - the two signals that traces actually materialize in MLflow.
-Set `config.feedback` to `true` / `false` to force it on or off
-regardless of the env.
-
-```ts
-mastra({ agents: support, feedback: true }); // force-enable
-```
+## Charts And Data Embeds
 
-Under the hood the server derives MLflow's trace id from the active
-OpenTelemetry span (`tr-<hex(otelTraceId)>`) and stamps it on each
-turn's response (`MLFLOW_TRACE_ID_HEADER`); the client sends it back to
-`POST ${basePath}/route/feedback`, which posts the assessment to the
-Databricks MLflow REST API. Trace export is asynchronous, so a
-just-finished trace may not exist yet - the log call retries briefly on
-"not found" and otherwise fails softly (the chat stays usable). The
-current state is published to the client as
-`clientConfig().feedbackEnabled`; see `[mlflow.ts](src/mlflow.ts)` and
-the UI wiring in `[@dbx-tools/appkit-mastra-ui](../appkit-mastra-ui)`.
-
-## Model resolution
-
-Each agent call resolves a model lazily (so concurrent requests keep
-distinct user identities), delegating to
-`[@dbx-tools/model](../model)` for the actual workspace-aware selection
-(fuzzy name matching, score-based class classification, offline
-fallbacks). Its exports are re-exported here, so `ModelClass` /
-`modelForClass` and friends are available straight off
-`@dbx-tools/appkit-mastra`.
-
-The plugin layers on the config sources for _which_ model an agent asks
-for, in priority order: a per-request override, the per-agent `model`,
-the plugin `defaultModel`, then `DATABRICKS_SERVING_ENDPOINT_NAME`. With
-none set, resolution falls through to the dynamic class picker.
+`chart.prepareChart()` mints a chart id immediately, caches an in-progress
+record, resolves the data in the background, and stores a terminal chart or
+error. `chart.fetchChart()` long-polls that cache for route handlers and custom
+clients.
 
 ```ts
-import { createAgent, ModelClass, modelForClass } from "@dbx-tools/appkit-mastra";
-
-const classifier = createAgent({
-  instructions: "Classify this email into billing, support, or spam.",
-  model: modelForClass(ModelClass.ChatFast),
+const { chartId } = await chart.prepareChart({
+  config,
+  request: {
+    title: "Revenue by region",
+    chartType: "bar",
+    instructions: "Compare total revenue by region.",
+    data: rows,
+  },
+  resolveData: async () => rows,
 });
+
+const resolved = await chart.fetchChart(chartId);
 ```
 
-Per-request overrides arrive via the `X-Mastra-Model` header, a
-`?model=` query, or a `model` / `modelId` body field (see
-`[serving.ts](src/serving.ts)`). The cached endpoint catalogue is
-exposed at `GET ${basePath}/models` for model pickers; the same data is
-available in-process from a sibling plugin via
-`appkitUtils.require(this.context, mastra).exports()`.
-
-## MCP server
-
-The plugin's agents are exposed as a Mastra
-`[MCPServer](https://mastra.ai/docs/tools-mcp/mcp-overview)` **by
-default** so external MCP clients - Claude Desktop, Cursor, the Mastra
-playground, or another agent - can call them over the standard MCP
-transports. The server is registered on the Mastra instance via
-`mcpServers`, so `@mastra/express` serves the stock MCP routes under the
-plugin mount; no bespoke route is added. It's on out of the box because
-wrapping the already-registered agents is free - only the ambient tools
-(which assume an in-process chat turn) stay off unless opted in.
+Agents can return `[chart:<id>]` and `[data:<statement_id>]` markers in prose.
+The embed route resolves them later, which avoids forcing the language model to
+inline large tables or wait for chart planning before continuing its answer.
 
-```ts
-import { mastra } from "@dbx-tools/appkit-mastra";
+## Model Selection
 
-// MCP is on by default: every registered agent is an `ask_<agentId>`
-// MCP tool with no extra config.
-mastra({});
+`model.buildModel()` adapts the generic resolver from
+[`@dbx-tools/model`](../model) to Mastra. It resolves the model per request,
+so OBO identity and request-specific overrides stay isolated.
 
-// Turn it off entirely.
-mastra({ mcp: false });
+Model priority is:
 
-// Or tune the server id / metadata and expose extra tools.
-mastra({
-  mcp: {
-    serverId: "analytics",
-    name: "Analytics MCP",
-    version: "2.1.0",
-    tools: true, // also expose ambient tools (off by default)
-  },
+1. request override (`X-Mastra-Model`, `?model=`, body `model` / `modelId`);
+2. per-agent `model`;
+3. plugin `defaultModel`;
+4. `DATABRICKS_SERVING_ENDPOINT_NAME`;
+5. workspace catalogue ranking and static fallback floor.
+
+```ts
+plugin.mastra({
+  agents: analyst,
+  defaultModel: "claude sonnet",
+  modelFuzzyMatch: true,
+  modelOverride: true,
 });
 ```
 
-With `mcp` enabled the transports mount at clean paths under the plugin
-base path (`/api/<plugin>`):
-
-- Streamable HTTP: `POST /api/<plugin>/mcp`
-- SSE (legacy): `GET /api/<plugin>/sse` + `POST /api/<plugin>/messages`
+Use `serving.extractModelOverride()` and `serving.resolveServingConfig()` when
+building custom routes that should behave like the plugin's `/models` and stream
+routes.
 
-(`@mastra/express` mounts these under `/mcp/<serverId>/<transport>`
-internally - the plugin rewrites the clean alias to that route, so a
-client never sees the doubled `/mcp/<serverId>/mcp` segment.)
+## Threads, History, And Suggestions
 
-`serverId` defaults to the plugin name. 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. The resolved endpoint
-paths are available in-process via
-`appkitUtils.require(this.context, mastra).exports().getMcp()`.
+When storage is enabled, the plugin provides route helpers and in-process
+functions for conversation management:
 
-## Client API surface (`apiAccess`)
+- `history.loadHistory()` and `history.clearHistory()` read or clear one thread;
+- `threads.listThreads()`, `threads.renameThread()`, and
+  `threads.deleteThread()` operate on the caller's scoped conversations;
+- `genie.collectSpaceSuggestions()` reads starter questions from the configured
+  Genie space.
 
-`@mastra/express` registers its full management route table under the
-plugin mount - agent inference _plus_ admin / mutating routes (direct
-tool execution, workflow control, raw memory read/write, telemetry,
-logs, scores). AppKit authenticates every request as the OBO user, but
-does not restrict _which_ of those a browser client may call.
+The plugin resolves the active thread from `x-mastra-thread-id`, `?threadId=`,
+or a per-session fallback cookie. That keeps streaming, history, and clear
+operations aligned around the same conversation id.
 
-`config.apiAccess` gates that surface at the plugin's dispatch point:
+## Feedback And Observability
 
-- `"scoped"` (default): only the routes the chat client needs are
-  dispatched to Mastra - agent inference (`stream` / `generate` /
-  `network`), read-only agent metadata (`GET /agents`,
-  `GET /agents/:id`), this plugin's own OBO- and resource-scoped
-  `/route/*` routes (history / threads / feedback), and, when `mcp` is
-  enabled, the MCP transport. Everything else is refused 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.
+`observability.buildObservability()` wires Mastra tracing when OTLP export is
+configured. `mlflow.resolveFeedbackEnabled()` turns MLflow feedback on when both
+trace export and an MLflow experiment are configured, unless the plugin config
+forces a value.
 
 ```ts
-mastra({ agents: support }); // scoped by default
-mastra({ agents: support, apiAccess: "full" }); // opt into the full API
+plugin.mastra({
+  agents: analyst,
+  feedback: true,
+});
 ```
 
-The gate is a pure allowlist (`isMastraRequestAllowed` in
-`[server.ts](src/server.ts)`); the browser chat client only ever uses
-the agent stream and the `/route/*` routes, so the default breaks
-nothing.
+`mlflow.logFeedback()` logs a human assessment against the active MLflow trace.
+The response header name and request/response schemas live in
+[`@dbx-tools/shared-mastra`](../../shared/mastra).
+
+## MCP Exposure
+
+`mcp.buildMcpServer()` exposes registered agents as MCP tools by default. The
+AppKit plugin publishes clean aliases under its base path:
 
-## License
+```ts
+plugin.mastra({
+  agents: analyst,
+  mcp: {
+    serverId: "analytics",
+    name: "Analytics MCP",
+    tools: false,
+  },
+});
+```
 
-Apache-2.0
+Use `mcp: false` to disable MCP. Turn on `tools: true` only for ambient tools
+that are safe outside an in-process chat turn.
+
+## API Gate
+
+The stock `@mastra/express` app has broad management routes. The plugin's
+default `apiAccess: "scoped"` allows only the chat, read-only metadata,
+plugin-owned `/route/*`, embed, model, suggestion, and MCP surfaces that the
+client needs. Use `apiAccess: "full"` only for a trusted first-party console.
+
+`server.isMastraRequestAllowed()` is exported for tests and custom dispatch
+logic that need the same allowlist.
+
+## Configuration Reference
+
+The plugin config is intentionally centered on the AppKit lifecycle instead of
+requiring callers to assemble a Mastra server by hand.
+
+- `agents` registers a single agent, an array, or a record keyed by stable agent
+  ids. Records are best for UIs because the ids become route-visible.
+- `defaultAgent` controls which registered agent handles requests that do not
+  name an agent explicitly.
+- `storage` and `memory` accept `true`, `false`, or concrete Mastra Postgres /
+  PgVector options. `true` resolves from `lakebase()` when present.
+- `genie.spaces` maps aliases to Genie Space IDs. Those aliases flow into tools,
+  suggestions, and chart/data workflows.
+- `defaultModel`, `modelOverride`, and `modelFuzzyMatch` control how loose model
+  names are resolved through Databricks Model Serving.
+- `feedback` controls whether MLflow feedback routes are exposed. The automatic
+  mode enables feedback when tracing and an MLflow experiment are configured.
+- `mcp` controls whether agents are exposed as MCP tools and how that server is
+  named.
+- `apiAccess` chooses the route allowlist. Keep the default scoped mode for
+  deployed apps.
+
+Use this package when you want an AppKit-native agent runtime. Use the shared
+schemas in [`@dbx-tools/shared-mastra`](../../shared/mastra) when building a
+client that talks to these routes.
+
+## Modules
+
+- `plugin` - `MastraPlugin` and `mastra()` AppKit plugin factory.
+- `agents` - `createAgent`, `tool`, `createTool`, agent build helpers, fallback
+  defaults, and approval-gated tool inspection.
+- `config` - plugin config types and RequestContext key constants.
+- `model` / `serving` / `servingSanitize` - Mastra model config, request
+  overrides, serving-endpoint config, and request-body cleanup.
+- `genie` - Genie prompt, space normalization, Genie toolkits, and suggestions.
+- `chart` / `statement` / `writer` - chart cache, statement row fetches, and
+  safe writer events.
+- `history` / `threads` / `pagination` - conversation persistence helpers and
+  route handlers.
+- `memory` / `storageSchema` - Lakebase-backed Mastra store/vector setup.
+- `workspaces` / `filesystems` - Mastra workspace creation and Databricks
+  Workspace file adapters.
+- `mcp` - MCP server construction.
+- `observability` / `mlflow` - tracing and feedback.
+- `server` / `rest` / `processors` - Express dispatch, Databricks REST helpers,
+  stream/result processors.
+
+Browser-facing wire types are in
+[`@dbx-tools/shared-mastra`](../../shared/mastra). Genie event contracts are in
+[`@dbx-tools/shared-genie`](../../shared/genie). Model request/result contracts
+are in [`@dbx-tools/shared-model`](../../shared/model). The matching React chat
+surface is [`@dbx-tools/ui-mastra`](../../ui/mastra).