@dbx-tools/appkit-mastra 0.1.58 → 0.1.67

package/dist/index.js

@@ -1,20 +1,3349 @@
+import { ChartSchema, ChartTypeSchema, MASTRA_ROUTES, MODEL_OVERRIDE_BODY_FIELDS, MODEL_OVERRIDE_HEADER, MODEL_OVERRIDE_QUERY } from "@dbx-tools/appkit-mastra-shared";
+import { DEFAULT_FUZZY_THRESHOLD, DEFAULT_MODEL_CACHE_TTL_MS, FALLBACK_MODEL_IDS, ModelClass, clearServingEndpointsCache, listServingEndpoints, parseModelClass, selectModel } from "@dbx-tools/model";
+import { apiUtils, appkitUtils, commonUtils, httpUtils, logUtils, netUtils, projectUtils, stringUtils } from "@dbx-tools/shared";
+import { Agent } from "@mastra/core/agent";
+import { createTool, createTool as createTool$1 } from "@mastra/core/tools";
+import { CacheManager, Plugin, genie, getExecutionContext, getUsernameWithApiLookup, lakebase, toPlugin } from "@databricks/appkit";
+import { z } from "zod";
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
+import { GenieMessageSchema } from "@dbx-tools/genie-shared";
+import { MCPServer } from "@mastra/mcp";
+import { Mastra } from "@mastra/core/mastra";
+import express from "express";
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+import { registerApiRoute } from "@mastra/core/server";
+import { fastembed } from "@mastra/fastembed";
+import { Memory } from "@mastra/memory";
+import { PgVector, PostgresStore } from "@mastra/pg";
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+import { Observability } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+import { MastraServer } from "@mastra/express";
+
+export * from "@dbx-tools/appkit-mastra-shared"
+
+export * from "@dbx-tools/model"
+
+//#region packages/appkit-mastra/src/config.ts
 /**
- * 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.
- *
- * 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.
- */
-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, } from "./src/serving.js";
+* `RequestContext` key under which {@link MastraServer} stores the
+* resolved AppKit user. `model.ts` reads it to mint user-scoped
+* Databricks tokens.
+*/
+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.
+*/
+const MASTRA_USER_NAME_KEY = "mastra__userName";
+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.
+*/
+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.
+*/
+const TRACE_REQUEST_CONTEXT_KEYS = [
+	MASTRA_RESOURCE_ID_KEY,
+	MASTRA_THREAD_ID_KEY,
+	MASTRA_REQUEST_ID_KEY,
+	MASTRA_USER_NAME_KEY,
+	MASTRA_USER_EMAIL_KEY,
+	"mastra__model_override"
+];
+
+//#endregion
+//#region packages/appkit-mastra/src/serving.ts
+/**
+* Mastra-specific glue over the generic `@dbx-tools/model` toolkit.
+*
+* The live `/serving-endpoints` catalogue access, fuzzy name
+* resolution, and class/fallback selection all live in
+* `@dbx-tools/model`; this module only adds what is specific to the
+* Mastra plugin: pulling a per-request model override off an HTTP
+* request (header / query / body) and projecting the plugin config
+* onto the knobs `buildModel` and the `/models` route share.
+*/
+/**
+* `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.
+*/
+const MASTRA_MODEL_OVERRIDE_KEY = "mastra__model_override";
+/**
+* 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`.
+*/
+function extractModelOverride(req) {
+	const headers = req.headers;
+	if (headers) {
+		const headerVal = stringUtils.firstNonEmpty(headers[MODEL_OVERRIDE_HEADER] ?? headers[MODEL_OVERRIDE_HEADER.toLowerCase()]);
+		if (headerVal) return headerVal;
+	}
+	if (req.query) {
+		const queryVal = stringUtils.firstNonEmpty(req.query[MODEL_OVERRIDE_QUERY]);
+		if (queryVal) return queryVal;
+	}
+	if (req.body && typeof req.body === "object") {
+		const record = req.body;
+		for (const field of MODEL_OVERRIDE_BODY_FIELDS) {
+			const bodyVal = stringUtils.firstNonEmpty(record[field]);
+			if (bodyVal) return bodyVal;
+		}
+	}
+	return null;
+}
+/**
+* Read the fuzzy-resolution config knobs off the plugin config with
+* `@dbx-tools/model` defaults applied. Kept here so `buildModel` and
+* the `/models` route agree on what "enabled" means.
+*
+* `fallbacks` is the priority-ordered list `resolveModel` walks first
+* when nothing explicit is set; defaults to an empty list so the
+* generic resolver falls through to the live catalogue and its own
+* `FALLBACK_MODEL_IDS` floor.
+*/
+function resolveServingConfig(config) {
+	return {
+		ttlMs: config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS,
+		threshold: config.modelFuzzyThreshold ?? DEFAULT_FUZZY_THRESHOLD,
+		fuzzy: config.modelFuzzyMatch !== false,
+		allowOverride: config.modelOverride !== false,
+		fallbacks: config.defaultModelFallbacks ?? []
+	};
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/model.ts
+/**
+* Databricks Model Serving resolver for Mastra agents.
+*
+* Each agent step calls {@link buildModel} with the active
+* `RequestContext`. The user stamped by `MastraServer` carries an
+* AppKit `WorkspaceClient`; we ask it for the workspace host and a
+* fresh bearer header, then point Mastra's OpenAI-compatible provider
+* at `/serving-endpoints` on that host.
+*
+* This module only adds the Mastra-specific glue. The actual model
+* selection - listing the workspace catalogue and resolving an
+* explicit name / class / fallback chain to a real endpoint id - lives
+* in `@dbx-tools/model` ({@link selectModel}) so non-Mastra consumers
+* (e.g. a job that just needs a model name) can reuse it. Here we
+* assemble the explicit ask from Mastra's request context (the
+* per-request override under {@link MASTRA_MODEL_OVERRIDE_KEY}, the
+* agent / plugin `modelId`, or `DATABRICKS_SERVING_ENDPOINT_NAME`),
+* pass the plugin's fuzzy / class / fallback knobs through, and wrap
+* the resolved id in the OpenAI-compatible provider config Mastra
+* expects. Catalogue fetches fail loud: network / auth errors
+* propagate so callers see the real SDK message.
+*/
+/**
+* Resolve a `MastraModelConfig` for the current agent step. Runs
+* while `agent.stream` is inside the `asUser(req)` scope so tokens
+* are user-scoped; outside an active user context the workspace
+* client falls back to the service principal.
+*/
+async function buildModel(config, requestContext, overrides = {}) {
+	setupFetchInterceptor();
+	const executionContext = requestContext.get(MASTRA_USER_KEY)?.executionContext ?? getExecutionContext();
+	const clientConfig = executionContext.client.config;
+	const host = (await clientConfig.getHost()).toString();
+	const headers = new Headers();
+	await clientConfig.authenticate(headers);
+	const url = new URL("/serving-endpoints", host).toString().replace(/\/$/, "");
+	const log = logUtils.logger(config);
+	const serving = resolveServingConfig(config);
+	const requested = (serving.allowOverride ? requestContext.get(MASTRA_MODEL_OVERRIDE_KEY) : void 0) ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
+	const requestedClass = requested !== void 0 ? parseModelClass(requested) : null;
+	const explicit = requestedClass === null ? requested : void 0;
+	const modelClass = requestedClass ?? overrides.modelClass;
+	const { modelId, source } = await selectModel(executionContext.client, host, {
+		...explicit !== void 0 ? { explicit } : {},
+		fuzzy: serving.fuzzy,
+		threshold: serving.threshold,
+		...modelClass !== void 0 ? { modelClass } : {},
+		fallbacks: serving.fallbacks,
+		ttlMs: serving.ttlMs
+	});
+	log.debug("model selected", {
+		modelId,
+		source,
+		requested
+	});
+	return {
+		providerId: config.providerId ?? "databricks",
+		modelId,
+		url,
+		headers: Object.fromEntries(headers.entries())
+	};
+}
+/** Path prefix that identifies a Databricks Model Serving REST call. */
+const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
+/**
+* Install a single shared `globalThis.fetch` wrapper for every POST to
+* `/serving-endpoints/...`. The wrapper does two things:
+*
+*   1. Rewrites the outgoing `messages` array to repair Mastra/AI SDK
+*      stream-replay quirks that Databricks-hosted Claude rejects (see
+*      {@link sanitizeServingMessages}).
+*   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
+*      4xx debugging doesn't have to fight AI SDK's `[Array]`
+*      formatter.
+*
+* Safe to call from any hot path: {@link commonUtils.memoize} ensures
+* the wrapper is installed at most once per process, so subsequent
+* calls collapse to a single cached promise even when
+* {@link buildModel} fires on every agent step.
+*/
+const setupFetchInterceptor = commonUtils.memoize(() => {
+	const log = logUtils.logger("mastra/llm");
+	const original = globalThis.fetch.bind(globalThis);
+	globalThis.fetch = (async (input, init) => {
+		const url = netUtils.urlBuilder(input);
+		if (!url || !url.pathname.startsWith(SERVING_ENDPOINTS_PATH_PREFIX) || typeof init?.body !== "string") return original(input, init);
+		const rewritten = rewriteServingBody(init.body);
+		if (rewritten !== init.body) init = {
+			...init,
+			body: rewritten
+		};
+		try {
+			log.debug("POST", {
+				url: url.toString(),
+				body: JSON.parse(rewritten)
+			});
+		} catch {
+			log.debug("POST", {
+				url: url.toString(),
+				bodyType: "non-JSON"
+			});
+		}
+		return original(input, init);
+	});
+});
+/**
+* Parse, sanitize, and re-serialize a `/serving-endpoints/...` POST
+* body. Returns the original string verbatim when the body is not
+* JSON, has no `messages`, or no rewrite was needed; this lets the
+* caller skip the allocation of a new `init` object in the common
+* pass-through case.
+*/
+function rewriteServingBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return body;
+	}
+	if (!Array.isArray(parsed.messages)) return body;
+	return sanitizeServingMessages(parsed.messages) ? JSON.stringify(parsed) : body;
+}
+/**
+* Repair a Mastra/AI SDK message replay that Databricks-hosted Claude
+* rejects with `"This model does not support assistant message
+* prefill. The conversation must end with a user message."`.
+*
+* The bug pattern: when an assistant turn streams text *and* a
+* `tool_call`, the AI SDK persists them as two separate assistant
+* entries (text-only and tool-call-only). On the next agent step the
+* tool-call entry is replayed *before* the tool result and the
+* text entry is replayed *after* it, so the conversation ends with a
+* trailing assistant text message. Anthropic interprets that as a
+* prefill request and rejects it on Databricks (the upstream Bedrock
+* route disallows prefill).
+*
+* Fix: when the last message is an assistant text with no `tool_calls`
+* and the chain immediately before it is `assistant(tool_calls=...)`
+* followed only by `tool(...)` results, fold the trailing text back
+* into the `content` of that opening assistant and drop the duplicate.
+* The result is the canonical OpenAI shape
+* `[..., user, assistant(text + tool_calls), tool(...)]` which both
+* Databricks Claude and every other endpoint accept.
+*
+* Mutates `messages` in place; returns `true` when something changed
+* so the caller knows whether to re-serialize.
+*/
+function sanitizeServingMessages(messages) {
+	if (messages.length < 2) return false;
+	const last = messages[messages.length - 1];
+	if (!last || last.role !== "assistant" || last.tool_calls && last.tool_calls.length > 0) return false;
+	let i = messages.length - 2;
+	while (i >= 0 && messages[i]?.role === "tool") i--;
+	if (i < 0) return false;
+	const opener = messages[i];
+	if (!opener || opener.role !== "assistant" || !opener.tool_calls || opener.tool_calls.length === 0) return false;
+	opener.content = [stringUtils.trimToNull(opener.content), stringUtils.trimToNull(last.content)].filter((s) => s !== null).join("\n\n");
+	messages.pop();
+	return true;
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/chart.ts
+/**
+* Chart planner + chart cache.
+*
+* Self-contained chart subsystem with two layers:
+*
+*   1. Inner planner agent (private). Pure dataset-in /
+*      `EChartsOption`-out brain. Driven by {@link prepareChart};
+*      callers never instantiate it directly.
+*   2. {@link prepareChart}: orchestration on top of the planner.
+*      Mints a `chartId`, caches an empty `{ chartId }` record
+*      synchronously, then resolves the dataset and runs the
+*      planner in the background. The terminal entry settles with
+*      either `result` (success) or `error` (failure). Both
+*      undefined means the entry is still processing.
+*
+* The cache surface ({@link fetchChart}) is the only state the
+* HTTP route and the chart-producing tools share. `prepareChart`
+* is dataset-agnostic - callers supply a `resolveData` callback
+* that fetches the rows however they like (Genie statement, inline
+* dataset, custom API). The module has no knowledge of Genie or
+* statement ids; those concerns live in the tools that wrap it.
+*
+* Wire-format schemas live in `@dbx-tools/appkit-mastra-shared` so
+* the demo client and any other UI consumer share the exact same
+* shape this module reads and writes.
+*/
+const log$5 = logUtils.logger("mastra/chart");
+/**
+* TTL for cached chart entries. One hour balances "long enough for
+* the host UI to fetch the chart well after the model finished
+* talking" against "short enough that abandoned chart ids don't
+* pin storage". Matches the typical Databricks OBO token lifetime
+* so any data re-resolution stays inside the original auth window.
+*/
+const CHART_CACHE_TTL_SEC = 3600;
+/** Cache namespace; keeps the chart keyspace tidy. */
+const CHART_CACHE_NAMESPACE = "mastra:chart";
+/**
+* `userKey` for `CacheManager.generateKey`. Chart ids are minted
+* via `commonUtils.id()` (v4 UUID) and are unguessable, so a
+* constant user key is fine. The HTTP route can re-scope to the
+* requesting user when policy demands it.
+*/
+const CHART_CACHE_USER_KEY = "mastra-chart";
+/** Default server-side long-poll budget for {@link fetchChart}. */
+const DEFAULT_FETCH_TIMEOUT_MS = 6e4;
+/** Default inter-poll sleep for {@link fetchChart}. */
+const DEFAULT_FETCH_INTERVAL_MS = 250;
+/**
+* One series data point. Wide variant set so the planner agent can
+* faithfully pass through whatever the SQL row set contained
+* (numbers, stringified numbers, nulls for missing measurements,
+* `[x, y]` tuples for scatter, `{name, value}` slices for pie)
+* without the structured-output guard rejecting the whole plan.
+*
+* Three layers of tolerance:
+*
+*   1. {@link z.preprocess} normalizes wire shapes BEFORE union
+*      dispatch: stringified numbers parse to numbers, finite
+*      checks reject `NaN` / `Infinity`, 2-element arrays coerce
+*      tuple components, and `{value}` objects with missing /
+*      stringified `value` get coerced or rejected uniformly.
+*      Anything not handleable becomes `null`.
+*   2. The union accepts `null` as a first-class variant. Echarts
+*      renders null as a gap on bar / line / area (which is the
+*      right visual signal for "missing reading"). Scatter and
+*      pie filter nulls in {@link planToEchartsOption} because
+*      Echarts crashes on null tuples / slices.
+*   3. {@link z.union#catch} backstops the whole thing: if
+*      preprocess somehow produces a shape that still doesn't
+*      match any variant, the bad item becomes `null` instead of
+*      taking down the entire chart with a
+*      `Structured output validation failed` error.
+*/
+const chartDataPointSchema = z.preprocess((v) => {
+	if (v === null || v === void 0) return null;
+	if (typeof v === "number") return Number.isFinite(v) ? v : null;
+	if (typeof v === "string") {
+		const n = Number(v);
+		return Number.isFinite(n) ? n : null;
+	}
+	if (Array.isArray(v) && v.length === 2) {
+		const x = typeof v[0] === "number" ? v[0] : Number(v[0]);
+		const y = typeof v[1] === "number" ? v[1] : Number(v[1]);
+		return Number.isFinite(x) && Number.isFinite(y) ? [x, y] : null;
+	}
+	if (typeof v === "object" && v !== null && "value" in v) {
+		const obj = v;
+		const val = typeof obj.value === "number" ? obj.value : Number(obj.value);
+		if (!Number.isFinite(val)) return null;
+		const rawName = obj.name;
+		return {
+			name: typeof rawName === "string" ? rawName : rawName == null ? "" : String(rawName),
+			value: val
+		};
+	}
+	return null;
+}, z.union([
+	z.number(),
+	z.null(),
+	z.tuple([z.number(), z.number()]),
+	z.object({
+		name: z.string(),
+		value: z.number()
+	})
+])).catch(null);
+/**
+* Compact, model-friendly representation of an Echarts spec. The
+* planner agent emits this; {@link planToEchartsOption} expands it
+* into a real `EChartsOption` JSON. Two layers because letting the
+* model fill in a fully-typed `EChartsOption` is brittle (hundreds
+* of optional fields, deep unions, version-dependent shapes). A
+* small "chart plan" schema is much more reliable for a fast model
+* and keeps animation / tooltip / styling defaults consistent
+* across charts.
+*/
+const chartPlanSchema = z.object({
+	chartType: ChartTypeSchema,
+	title: z.string().optional().describe(stringUtils.toDescription(`
+        Short title shown above the chart. Optional; defaults to the
+        \`title\` argument the caller passed in.
+      `)),
+	xAxisLabel: z.string().optional().describe(stringUtils.toDescription(`
+        Axis label below the chart. Used for bar / line / area / scatter;
+        ignored for pie.
+      `)),
+	yAxisLabel: z.string().optional().describe(stringUtils.toDescription(`
+        Axis label to the left of the chart. Used for bar / line / area /
+        scatter; ignored for pie.
+      `)),
+	categories: z.array(z.string()).optional().describe(stringUtils.toDescription(`
+        X-axis category labels for \`bar\` / \`line\` / \`area\` charts
+        (one per data point in each series). Omit for \`scatter\` (uses
+        [x, y] tuples) and \`pie\` (each slice carries its own \`name\`).
+      `)),
+	series: z.array(z.object({
+		name: z.string().describe(stringUtils.toDescription(`
+            Legend name for this series.
+          `)),
+		data: z.array(chartDataPointSchema).describe(stringUtils.toDescription(`
+            Data points. For \`bar\` / \`line\` / \`area\`, an array of
+            numbers aligned to \`categories\`. For \`scatter\`, an array
+            of \`[x, y]\` numeric tuples. For \`pie\`, an array of
+            \`{name, value}\` objects.
+          `))
+	})).min(1).describe(stringUtils.toDescription(`
+        One or more series to plot. Pie charts use exactly one series;
+        bar/line/area can stack multiple series sharing the same
+        \`categories\` axis.
+      `))
+});
+/**
+* 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}.
+*/
+const chartPlannerRequestSchema = z.object({
+	title: z.string().describe(stringUtils.toDescription(`
+        Concise title shown above the chart (e.g. "Top 10 SKUs by Revenue").
+      `)),
+	description: z.string().optional().describe(stringUtils.toDescription(`
+        One-line intent the chart-planner uses when picking a chart type
+        and axis encodings (e.g. "compare quarterly revenue across
+        regions", "highlight the steep drop after position 5"). Not shown
+        to the user.
+      `)),
+	data: z.array(z.record(z.string(), z.unknown())).nonempty("Data must contain at least one row").readonly().describe(stringUtils.toDescription(`
+        Tabular dataset to chart. One object per row, keyed by column
+        name. Values may be strings, numbers, booleans, or null. The
+        chart-planner decides which columns are categories vs. numeric
+        series. Cap at a few hundred rows for legibility; sample /
+        aggregate larger datasets first.
+      `))
+});
+/**
+* Format {@link ChartTypeSchema}'s variants as a single
+* human-friendly string of `` `<value>` for <description> ``
+* clauses joined by semicolons, drawn from each variant's own
+* `.describe()` so the planner prompt stays in lock-step with
+* the schema by construction.
+*/
+function formatChartTypePicker() {
+	return ChartTypeSchema.options.map((opt) => `\`${opt.value}\` for ${opt.description ?? ""}`).join("; ");
+}
+/**
+* System prompt for the inner chart-planning agent. Tuned for a
+* fast-tier model (Haiku, GPT-5-mini, Gemini Flash Lite).
+*/
+const CHART_PLANNER_INSTRUCTIONS = stringUtils.toDescription(`
+  You design Apache Echarts visualizations. The user gives you a
+  tabular dataset (rows of objects) plus a title and an optional
+  description of the intent. You produce a small chart plan (chart
+  type, axis labels, categories, series) that best conveys the data.
+
+  Decision guide. Pick the chart type whose data shape matches the
+  dataset and the user's intent: ${formatChartTypePicker()}.
+
+  When in doubt between bar and line, prefer bar for unordered
+  categories and line for ordered ones (dates, time buckets, ranks).
+  Never pick pie for more than 7 slices.
+
+  For bar / line / area: pick one column as the category axis (usually
+  the only string-valued column) and one or more numeric columns as
+  series. Sort categories by the primary series value descending unless
+  the data is naturally ordered (dates, ranks).
+
+  For pie: pick the category column for slice names and one numeric
+  column for slice values. Emit a single series.
+
+  For scatter: pick two numeric columns and emit \`[x, y]\` tuples in a
+  single series.
+
+  Keep series names human-readable (use the column name; title case it
+  lightly if needed). Keep titles concise; do not repeat the user's
+  title in xAxisLabel / yAxisLabel.
+`);
+/**
+* One planner `Agent` per plugin config. Cached on config object
+* identity so callers can `prepareChart({ config, ... })` from a
+* hot path without paying the Agent-constructor cost every call.
+* `WeakMap` lets retired configs (e.g. test reconfigurations)
+* release their agent without manual eviction.
+*/
+const plannerAgents = /* @__PURE__ */ new WeakMap();
+function getPlannerAgent(config) {
+	let agent = plannerAgents.get(config);
+	if (!agent) {
+		agent = new Agent({
+			id: "chart_planner",
+			name: "Chart Planner",
+			description: "Picks chart type and axis encodings for a dataset.",
+			instructions: CHART_PLANNER_INSTRUCTIONS,
+			model: ({ requestContext }) => buildModel(config, requestContext, { modelClass: ModelClass.ChatFast })
+		});
+		plannerAgents.set(config, agent);
+	}
+	return agent;
+}
+/**
+* Run the planner against `request` and return the resolved
+* Echarts spec. Throws on planner failure - {@link prepareChart}
+* catches and stashes the error in the cache entry.
+*/
+async function runChartPlanner(config, request, options = {}) {
+	const { title, description, data } = request;
+	const { requestContext, abortSignal } = options;
+	const prompt = stringUtils.toDescription({
+		Title: title,
+		...description ? { Description: description } : {},
+		"Dataset (JSON, one row per object)": JSON.stringify(data, null, 2)
+	});
+	const result = await getPlannerAgent(config).generate(prompt, {
+		structuredOutput: { schema: chartPlanSchema },
+		...requestContext ? { requestContext } : {},
+		...abortSignal ? { abortSignal } : {}
+	});
+	const plan = chartPlanSchema.parse(result.object);
+	const option = planToEchartsOption(plan, title);
+	return {
+		chartType: plan.chartType,
+		option
+	};
+}
+/** Build the canonical cache key for a `chartId`. */
+async function chartCacheKey(chartId) {
+	return (await CacheManager.getInstance()).generateKey([CHART_CACHE_NAMESPACE, chartId], CHART_CACHE_USER_KEY);
+}
+/**
+* Persist a {@link Chart} entry under its `chartId`. Refreshes
+* the TTL on every write. Cache-layer failures are logged and
+* swallowed so background runners never throw into the
+* unhandled-rejection stream.
+*/
+async function writeChart(entry) {
+	try {
+		const key = await chartCacheKey(entry.chartId);
+		await CacheManager.getInstanceSync().set(key, entry, { ttl: CHART_CACHE_TTL_SEC });
+	} catch (err) {
+		log$5.warn("write-error", {
+			chartId: entry.chartId,
+			error: commonUtils.errorMessage(err)
+		});
+	}
+}
+/**
+* Look up a chart by id. Returns `undefined` on miss, on
+* expiry, or when the cache layer is unhealthy - never throws.
+*/
+async function readChart(chartId) {
+	try {
+		const key = await chartCacheKey(chartId);
+		return await CacheManager.getInstanceSync().get(key) ?? void 0;
+	} catch (err) {
+		log$5.warn("read-error", {
+			chartId,
+			error: commonUtils.errorMessage(err)
+		});
+		return;
+	}
+}
+/**
+* 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 }`
+*/
+async function prepareChart(opts) {
+	const chartId = commonUtils.id();
+	await writeChart({ chartId });
+	log$5.debug("queued", { chartId });
+	runPrepareChart(chartId, opts);
+	return { chartId };
+}
+async function runPrepareChart(chartId, opts) {
+	const startedAt = Date.now();
+	try {
+		const data = await opts.resolveData(opts.signal);
+		if (data.rows.length === 0) throw new Error("dataset has no rows; nothing to chart");
+		const result = await runChartPlanner(opts.config, {
+			title: opts.title ?? "Chart",
+			...opts.description ? { description: opts.description } : {},
+			data: data.rows
+		}, {
+			...opts.requestContext ? { requestContext: opts.requestContext } : {},
+			...opts.signal ? { abortSignal: opts.signal } : {}
+		});
+		await writeChart({
+			chartId,
+			result
+		});
+		log$5.info("done", {
+			chartId,
+			chartType: result.chartType,
+			elapsedMs: Date.now() - startedAt
+		});
+	} catch (err) {
+		const error = commonUtils.errorMessage(err);
+		log$5.warn("error", {
+			chartId,
+			error
+		});
+		await writeChart({
+			chartId,
+			error
+		});
+	}
+}
+/**
+* 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.
+*/
+async function fetchChart(chartId, options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+	const intervalMs = options.intervalMs ?? DEFAULT_FETCH_INTERVAL_MS;
+	const deadline = Date.now() + timeoutMs;
+	let last;
+	while (true) {
+		options.signal?.throwIfAborted();
+		last = await readChart(chartId);
+		if (!last) return void 0;
+		if (last.result !== void 0 || last.error !== void 0) return last;
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) return last;
+		await commonUtils.sleep(Math.min(intervalMs, remaining), options.signal);
+	}
+}
+/**
+* Expand a {@link ChartPlan} into a full Echarts `EChartsOption`
+* JSON. Centralized here so the planner agent only fills in the
+* compact plan shape; tooltip / animation / color / grid defaults
+* stay consistent across charts and are easy to tune without
+* retraining model behaviour.
+*/
+function planToEchartsOption(plan, fallbackTitle) {
+	const baseTitle = plan.title ?? fallbackTitle;
+	const grid = {
+		left: 48,
+		right: 24,
+		top: 56,
+		bottom: 48,
+		containLabel: true
+	};
+	if (plan.chartType === "pie") {
+		const slices = (plan.series[0]?.data ?? []).filter((d) => d !== null && typeof d === "object" && !Array.isArray(d));
+		return {
+			title: {
+				text: baseTitle,
+				left: "center"
+			},
+			tooltip: { trigger: "item" },
+			legend: { bottom: 0 },
+			series: [{
+				name: plan.series[0]?.name ?? baseTitle,
+				type: "pie",
+				radius: ["35%", "65%"],
+				data: slices
+			}]
+		};
+	}
+	if (plan.chartType === "scatter") return {
+		title: {
+			text: baseTitle,
+			left: "center"
+		},
+		tooltip: { trigger: "item" },
+		legend: { bottom: 0 },
+		grid,
+		xAxis: {
+			type: "value",
+			name: plan.xAxisLabel
+		},
+		yAxis: {
+			type: "value",
+			name: plan.yAxisLabel
+		},
+		series: plan.series.map((s) => ({
+			name: s.name,
+			type: "scatter",
+			data: s.data.filter((d) => Array.isArray(d) && d.length === 2)
+		}))
+	};
+	const isArea = plan.chartType === "area";
+	const seriesType = plan.chartType === "bar" ? "bar" : "line";
+	return {
+		title: {
+			text: baseTitle,
+			left: "center"
+		},
+		tooltip: { trigger: "axis" },
+		legend: { bottom: 0 },
+		grid,
+		xAxis: {
+			type: "category",
+			data: plan.categories ?? [],
+			name: plan.xAxisLabel
+		},
+		yAxis: {
+			type: "value",
+			name: plan.yAxisLabel
+		},
+		series: plan.series.map((s) => ({
+			name: s.name,
+			type: seriesType,
+			data: s.data,
+			smooth: seriesType === "line",
+			...isArea ? { areaStyle: {} } : {}
+		}))
+	};
+}
+/**
+* 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.
+*/
+function buildRenderDataTool(config) {
+	return createTool$1({
+		id: "render_data",
+		description: stringUtils.toDescription([
+			`
+        Submit a tabular dataset for inline rendering as a chart in
+        the user's view. Pass a title, the raw rows (array of objects
+        keyed by column name), and an optional one-line description
+        of the insight to highlight. Returns a short \`chartId\`;
+        the chart renders inline at the position you embed the
+        matching \`[chart:<chartId>]\` marker.
+      `,
+			`
+        Placement contract: embed \`[chart:<chartId>]\` on its own
+        line (blank lines above and below) wherever you want the
+        chart to appear in your reply. The chart resolves
+        asynchronously - the tool returns the id immediately and the
+        host UI fetches the chart from the cache once the planner
+        lands. You can call \`render_data\` multiple times in the
+        same turn (the tool is parallel-safe) and interleave the
+        markers with prose so each chart sits next to its
+        commentary.
+      `,
+			`
+        Use whenever a SQL row set, API response, or hand-built
+        dataset would land better as a picture than as a list or
+        table. Cap input at a few hundred rows; sample or aggregate
+        larger datasets first.
+      `
+		]),
+		inputSchema: chartPlannerRequestSchema,
+		outputSchema: ChartSchema.pick({ chartId: true }),
+		execute: async (input, ctxRaw) => {
+			const { title, description, data } = input;
+			const ctx = ctxRaw;
+			return prepareChart({
+				config,
+				title,
+				...description ? { description } : {},
+				resolveData: () => Promise.resolve({ rows: data }),
+				...ctx?.requestContext ? { requestContext: ctx.requestContext } : {}
+			});
+		}
+	});
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/statement.ts
+/**
+* Hard server-side cap on rows returned by the
+* `/embed/data/:id` route. Sized to keep responses small
+* enough for inline tables to render snappily; the route surfaces
+* a `truncated` flag whenever the upstream `rowCount` exceeds
+* this so end users know they're seeing a sample.
+*/
+const STATEMENT_ROW_CAP = 500;
+/**
+* Best-effort numeric coercion for the Statement Execution API's
+* all-strings cells. Leaves non-numeric strings (and explicit
+* `null`s) intact; everything else flows through `Number`.
+*/
+function coerceCell(cell) {
+	if (cell === null) return null;
+	if (/^-?\d+(\.\d+)?$/.test(cell)) {
+		const n = Number(cell);
+		if (Number.isFinite(n)) return n;
+	}
+	return cell;
+}
+/**
+* Fetch a single statement's rows via the Statement Execution API
+* and reshape into the shared {@link GenieDatasetData} shape
+* (column array + row records).
+*
+* Optional `limit` slices the returned `rows` client-side so the
+* agent can scan a small sample without paging the full result
+* set into context. `rowCount` always reflects the upstream total
+* so callers know when the slice truncated.
+*
+* Exported because every consumer in the plugin (the
+* `get_statement` tool, the `prepare_chart` dataset resolver, and
+* the `/embed/data/:id` route) needs the exact same
+* fetch + coercion pipeline so LLM-side `get_statement` output
+* and UI-side `[data:<id>]` rendering stay shape-identical for
+* the same `statement_id`.
+*/
+async function fetchStatementData(client, statementId, options) {
+	const ctx = options?.signal ? apiUtils.toContext(options.signal) : void 0;
+	const r = await client.statementExecution.getStatement({ statement_id: statementId }, ctx);
+	const columns = (r.manifest?.schema?.columns ?? []).map((c) => c.name ?? "");
+	const dataArray = r.result?.data_array ?? [];
+	return {
+		columns,
+		rows: (options?.limit !== void 0 && options.limit >= 0 ? dataArray.slice(0, options.limit) : dataArray).map((row) => {
+			const obj = {};
+			columns.forEach((col, i) => {
+				obj[col] = coerceCell(row[i] ?? null);
+			});
+			return obj;
+		}),
+		rowCount: r.manifest?.total_row_count ?? dataArray.length
+	};
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/writer.ts
+/**
+* Best-effort `writer.write`. No-op when `writer` is undefined;
+* caught errors are logged via `log.warn("writer:error", ...)`
+* along with any caller-supplied `context` fields (e.g. a
+* `chartId` or `messageId`) so the warning is greppable per
+* resource.
+*
+* Returns when the write resolves or rejects; never throws.
+*/
+async function safeWrite(log, writer, chunk, context = {}) {
+	if (!writer) {
+		log.debug("writer:no-writer", context);
+		return;
+	}
+	try {
+		await writer.write(chunk);
+		log.debug("writer:ok", context);
+	} catch (err) {
+		log.warn("writer:error", {
+			...context,
+			error: commonUtils.errorMessage(err)
+		});
+	}
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/genie.ts
+/**
+* Genie tools for Mastra.
+*
+* Surfaces each configured Genie space as a small set of flat Mastra
+* tools the calling agent drives directly - no inner orchestrator
+* agent. The central agent decomposes user questions, picks which
+* space to ask, streams the per-turn wire events (status, thinking,
+* sql, rows) through `ctx.writer`, and composes the final reply.
+* Rows are never fetched eagerly: the agent reads a statement's
+* values only when it needs to reason about them, otherwise it embeds
+* a `[data:<statement_id>]` marker in prose and lets the host UI
+* resolve the data. Charts are minted asynchronously and referenced
+* by `[chart:<chartId>]` markers so prose isn't blocked on chart
+* generation; the host UI fetches the cached spec by id once ready.
+* Space description and serialized-space lookups are available for
+* grounding when the agent needs schema context.
+*
+* Each tool's `execute` pulls the per-request
+* {@link WorkspaceClient} off `ctx.requestContext` (stamped by
+* `MastraServer` under {@link MASTRA_USER_KEY}) and the per-call
+* `writer` / `abortSignal` off `ctx`, so the tools are stateless
+* across requests and the central agent owns the loop.
+*
+* The tools talk to Genie directly via `@dbx-tools/genie`
+* (`genieEventChat`); statement-row fetching is delegated to
+* {@link fetchStatementData} from `./statement.js`, which wraps
+* the workspace `statementExecution.getStatement` API. AppKit's
+* stock `genie` plugin is honored only for its `spaces` config
+* so existing AppKit-style wiring keeps working without change.
+*
+* Suggested orchestration prompt for the central agent lives in
+* {@link GENIE_INSTRUCTIONS}; compose it into the agent's own
+* `instructions` when you want the canonical "how to drive the
+* Genie tools" guidance.
+*/
+const log$4 = logUtils.logger("mastra/genie");
+/** Default alias used when a single unnamed Genie space is wired up. */
+const DEFAULT_GENIE_ALIAS = "default";
+/**
+* Pull the per-request {@link WorkspaceClient} off the active
+* `RequestContext`. The Mastra plugin's server middleware stamps
+* a {@link User} on the context under {@link MASTRA_USER_KEY}
+* for every request; tools fail loudly when it's missing because
+* that means the Mastra plugin isn't running (e.g. a tool was
+* invoked outside the chat route).
+*/
+function requireClient(ctx, toolId) {
+	const requestContext = ctx?.requestContext;
+	if (!requestContext) throw new Error(`${toolId}: missing requestContext (MastraServer must stamp MASTRA_USER_KEY)`);
+	const user = requestContext.get(MASTRA_USER_KEY);
+	if (!user) throw new Error(`${toolId}: no user on requestContext (MASTRA_USER_KEY not set)`);
+	return {
+		client: user.executionContext.client,
+		requestContext
+	};
+}
+/**
+* Lowercased placeholder strings we reject at the `ask_genie`
+* boundary so the LLM doesn't spend a Genie round-trip on a
+* non-question. Genie politely answers any of these with "Your
+* request '...' does not relate to..." which is pure UI noise.
+* Kept narrow on purpose - real questions sometimes start with
+* one of these tokens, so we only match the FULL trimmed string.
+*/
+const PLACEHOLDER_QUESTIONS = new Set([
+	"noop",
+	"no-op",
+	"skip",
+	"none",
+	"n/a",
+	"na",
+	"null",
+	"undefined",
+	"test",
+	"placeholder"
+]);
+/**
+* Estimated Genie conversation lifetime in seconds. Databricks
+* publishes no official TTL on the conversation resource itself;
+* community projects (e.g. the open-source Databricks Genie Bot)
+* converge on 4 hours of inactivity as a safe operating window.
+* Treat this as an estimate that gets *extended on every use* by
+* re-setting the cache entry after each successful turn (sliding
+* TTL via re-`set`). When the estimate ends up wrong (conversation
+* deleted, expired upstream, cross-space referenced), `ask_genie`
+* catches the SDK's `RESOURCE_DOES_NOT_EXIST`/404 and transparently
+* starts a fresh conversation.
+*/
+const CONVERSATION_TTL_SEC = 14400;
+/** Cache namespace prefix so coexisting Mastra caches don't collide. */
+const CONVERSATION_CACHE_NAMESPACE = "mastra:genie:conversation";
+/**
+* `userKey` for `CacheManager.getOrExecute` / `generateKey`. Genie
+* conversations are scoped to a single user + space + thread, and
+* `threadId` is already user-scoped (Mastra mints threads per
+* `resourceId`), so a constant user key here is safe and keeps the
+* cache key short.
+*/
+const CONVERSATION_USER_KEY = "mastra-genie";
+/**
+* Build the per-request {@link RequestContext} key the active
+* Genie `conversation_id` lives under for `spaceId`. Scoped by
+* space so an app calling two Genie spaces in one request keeps
+* each conversation distinct (Genie conversation ids are
+* space-scoped on the wire). The same `RequestContext` instance
+* flows from the central agent through to every `ask_genie`
+* invocation, so writes on one call are visible on the next
+* without an explicit shared ref.
+*/
+const conversationContextKey = (spaceId) => `mastra__genie_conversation__${spaceId}`;
+/**
+* Read the active Genie `conversation_id` for `spaceId` off the
+* per-request {@link RequestContext}. Returns `undefined` when no
+* conversation has been started yet this request.
+*/
+function readContextConversationId(requestContext, spaceId) {
+	return requestContext.get(conversationContextKey(spaceId));
+}
+/**
+* Write the active Genie `conversation_id` for `spaceId` onto the
+* per-request {@link RequestContext}. Subsequent `ask_genie` calls
+* in this request will reuse it.
+*/
+function writeContextConversationId(requestContext, spaceId, conversationId) {
+	requestContext.set(conversationContextKey(spaceId), conversationId);
+}
+/**
+* Build the canonical cache key for a `(spaceId, threadId)` pair.
+* Returns `undefined` when `threadId` is missing - callers should
+* skip caching entirely in that case (no Mastra memory wired up).
+*/
+async function conversationCacheKey(spaceId, threadId) {
+	if (!threadId) return void 0;
+	return (await CacheManager.getInstance()).generateKey([
+		CONVERSATION_CACHE_NAMESPACE,
+		spaceId,
+		threadId
+	], CONVERSATION_USER_KEY);
+}
+/**
+* Read the cached Genie conversation id for `(spaceId, threadId)`.
+* Returns `undefined` on miss, on expiry, or when the cache layer
+* is unhealthy - never throws. The TTL is renewed via re-`set`
+* after each successful turn (see {@link saveCachedConversationId}).
+*/
+async function readCachedConversationId(cacheKey) {
+	if (!cacheKey) return void 0;
+	try {
+		return await CacheManager.getInstanceSync().get(cacheKey) ?? void 0;
+	} catch (err) {
+		log$4.warn("conversation-cache:read-error", { error: commonUtils.errorMessage(err) });
+		return;
+	}
+}
+/**
+* Persist the active conversation id under `cacheKey`, refreshing
+* its TTL. Idempotent; no-op when `cacheKey` or `conversationId`
+* is missing. Re-setting the same key acts as a sliding TTL: every
+* turn that uses the conversation extends the window by another
+* {@link CONVERSATION_TTL_SEC} seconds.
+*/
+async function saveCachedConversationId(cacheKey, conversationId) {
+	if (!cacheKey || !conversationId) return;
+	try {
+		await CacheManager.getInstanceSync().set(cacheKey, conversationId, { ttl: CONVERSATION_TTL_SEC });
+	} catch (err) {
+		log$4.warn("conversation-cache:write-error", { error: commonUtils.errorMessage(err) });
+	}
+}
+/** Force-evict a cached conversation id. Used on the stale-id recovery path. */
+async function evictCachedConversationId(cacheKey) {
+	if (!cacheKey) return;
+	try {
+		await CacheManager.getInstanceSync().delete(cacheKey);
+	} catch (err) {
+		log$4.warn("conversation-cache:delete-error", { error: commonUtils.errorMessage(err) });
+	}
+}
+/**
+* Lazy-seed the active Genie `conversation_id` for `spaceId` from
+* the cross-request cache onto the per-request `RequestContext`.
+* No-op when the slot is already populated (subsequent
+* `ask_genie` calls in the same turn) so we hit the cache at most
+* once per request per space.
+*/
+async function ensureConversationSeeded(requestContext, spaceId, cacheKey) {
+	if (readContextConversationId(requestContext, spaceId)) return;
+	const cached = await readCachedConversationId(cacheKey);
+	if (cached) writeContextConversationId(requestContext, spaceId, cached);
+}
+/**
+* Agent-facing `prepare_chart` input schema. Reuses
+* {@link chartPlannerRequestSchema} (the dataset-driven planner
+* contract) but swaps the inline `data` field for a Genie
+* `statement_id` the tool resolves into rows server-side.
+* `title` is loosened to optional - the planner falls back to a
+* generic placeholder when the agent doesn't supply one.
+*
+* Shaped to match Genie's wire form - `statement_id` (snake)
+* mirrors `query_result.statement_id` and the `get_statement`
+* tool's input field name, so the LLM only ever sees one
+* spelling for the same identifier.
+*/
+const prepareChartRequestSchema = chartPlannerRequestSchema.omit({
+	data: true,
+	title: true
+}).extend({
+	statement_id: z.string().min(1, "statement_id is required").describe(stringUtils.toDescription(`
+          Genie \`statement_id\` to chart. Read from
+          \`message.query_result.statement_id\` or
+          \`message.attachments[*].query.statement_id\` returned by
+          \`ask_genie\`.
+        `)),
+	title: chartPlannerRequestSchema.shape.title.optional()
+});
+/**
+* Suffix appended to per-space tool ids when the alias isn't the
+* well-known `default`. Single-space deployments get the bare
+* names (`ask_genie`, `get_space_description`, ...); multi-space
+* deployments get `ask_genie_<alias>` etc. so each space's tools
+* stay disambiguated in the central agent's tool registry.
+*/
+function aliasSuffix(alias) {
+	if (alias === DEFAULT_GENIE_ALIAS) return "";
+	const slug = stringUtils.toIdentifier(alias);
+	return slug ? `_${slug}` : "";
+}
+/**
+* Drop `suggested_questions` attachments from a {@link GenieMessage}
+* before handing it to the central LLM. Those entries already
+* surface in the UI as one-tap pills via the writer's
+* `suggested_questions` events (see `collectSuggestions` on the
+* client); if we let them ride back in the tool result the LLM
+* tends to quote them inline in its prose, double-showing the
+* same questions and stepping on the dedicated suggestion UI.
+* Query / text / row attachments are preserved so the model can
+* still read `statement_id`, SQL, and the answer text.
+*/
+function stripSuggestedQuestions(message) {
+	const attachments = message.attachments;
+	if (!attachments || attachments.length === 0) return message;
+	const filtered = attachments.filter((att) => !att.suggested_questions);
+	if (filtered.length === attachments.length) return message;
+	return {
+		...message,
+		attachments: filtered
+	};
+}
+function buildAskGenieTool(opts) {
+	const { spaceId, alias, hint } = opts;
+	const toolId = `ask_genie${aliasSuffix(alias)}`;
+	const hintLine = hint ? ` (${hint})` : "";
+	return createTool$1({
+		id: toolId,
+		description: stringUtils.toDescription(`
+      Ask the Genie space "${alias}"${hintLine} ONE focused
+      natural-language sub-question and wait for the turn to
+      complete. Genie answers best when each call covers a
+      single metric / dimension / time window, so expect to
+      call this tool MULTIPLE TIMES per user turn (typically
+      two to six) and let the results from earlier calls inform
+      later ones - that's the normal pattern, not the exception.
+      Do NOT try to cram a multi-part question into a single
+      call; decompose first, then ask each piece.
+
+      Returns the final \`GenieMessage\`. Rows are NOT included -
+      the Genie wire response carries the \`statement_id\` for any
+      SQL that ran (at \`message.query_result.statement_id\` or the
+      first attachment's \`query.statement_id\`); call
+      \`get_statement\` with that id only when you need to read
+      the underlying values to reason about them. If you just
+      want to display the rows to the user, embed a
+      \`[data:<statement_id>]\` marker in your prose instead -
+      the host UI fetches and renders the rows on its own. Wire
+      events (status, thinking, sql) stream to the user
+      automatically while the call is in flight.
+    `),
+		inputSchema: z.object({ question: z.string().min(1, "question is required") }),
+		outputSchema: z.object({ message: GenieMessageSchema }),
+		execute: async ({ question }, ctxRaw) => {
+			const ctx = ctxRaw;
+			const { client, requestContext } = requireClient(ctx, toolId);
+			const writer = ctx?.writer;
+			const signal = ctx?.abortSignal;
+			const threadId = requestContext.get(MASTRA_THREAD_ID_KEY);
+			const trimmed = question.trim();
+			if (trimmed.length === 0 || PLACEHOLDER_QUESTIONS.has(trimmed.toLowerCase())) throw new Error(`${toolId}: refusing placeholder question "${question}" - call ${toolId} only with a real natural-language question, or skip the call entirely`);
+			const cacheKey = await conversationCacheKey(spaceId, threadId);
+			await ensureConversationSeeded(requestContext, spaceId, cacheKey);
+			await safeWrite(log$4, writer, {
+				type: "started",
+				spaceId,
+				content: question
+			});
+			const runTurn = async () => {
+				const seedConversationId = readContextConversationId(requestContext, spaceId);
+				let finalMessage;
+				for await (const event of genieEventChat(spaceId, question, {
+					workspaceClient: client,
+					...seedConversationId ? { conversationId: seedConversationId } : {},
+					...signal ? { context: signal } : {}
+				})) {
+					if (event.type !== "message") await safeWrite(log$4, writer, event);
+					const eventConversationId = event.conversation_id;
+					if (eventConversationId) writeContextConversationId(requestContext, spaceId, eventConversationId);
+					if (event.type === "result") finalMessage = event.message;
+				}
+				if (!finalMessage) throw new Error("Genie turn ended without a result event");
+				return finalMessage;
+			};
+			let finalMessage;
+			try {
+				finalMessage = await runTurn();
+			} catch (err) {
+				const seeded = readContextConversationId(requestContext, spaceId);
+				if (seeded && apiUtils.isNotFoundError(err)) {
+					log$4.warn("conversation-cache:stale, resetting", {
+						spaceId,
+						conversationId: seeded,
+						error: commonUtils.errorMessage(err)
+					});
+					await evictCachedConversationId(cacheKey);
+					writeContextConversationId(requestContext, spaceId, void 0);
+					finalMessage = await runTurn();
+				} else throw err;
+			}
+			await saveCachedConversationId(cacheKey, readContextConversationId(requestContext, spaceId));
+			return { message: stripSuggestedQuestions(finalMessage) };
+		}
+	});
+}
+function buildSpaceDescriptionTool(opts) {
+	const { spaceId, alias } = opts;
+	const toolId = `get_space_description${aliasSuffix(alias)}`;
+	return createTool$1({
+		id: toolId,
+		description: stringUtils.toDescription(`
+      Return the Genie space "${alias}"'s title, description, and
+      warehouse id. Cheap (single REST call, no LLM round-trip).
+      Call this FIRST on any user turn that's going to touch
+      \`ask_genie\`, unless the same description already landed
+      earlier in this conversation - the title + description tell
+      you what tables, metrics, and time windows the space
+      actually covers, which is what lets you decompose the
+      user's question into the right \`ask_genie\` sub-questions.
+    `),
+		inputSchema: z.object({}),
+		outputSchema: z.object({
+			spaceId: z.string(),
+			title: z.string().optional(),
+			description: z.string().optional(),
+			warehouseId: z.string().optional()
+		}),
+		execute: async (_input, ctxRaw) => {
+			const ctx = ctxRaw;
+			const { client } = requireClient(ctx, toolId);
+			const signal = ctx?.abortSignal;
+			const space = await getGenieSpace(spaceId, {
+				workspaceClient: client,
+				serialized: false,
+				...signal ? { context: signal } : {}
+			});
+			return {
+				spaceId,
+				...space.title ? { title: space.title } : {},
+				...space.description ? { description: space.description } : {},
+				...space.warehouse_id ? { warehouseId: space.warehouse_id } : {}
+			};
+		}
+	});
+}
+function buildSpaceSerializedTool(opts) {
+	const { spaceId, alias } = opts;
+	const toolId = `get_space_serialized${aliasSuffix(alias)}`;
+	return createTool$1({
+		id: toolId,
+		description: stringUtils.toDescription(`
+      Return the full \`GenieSpace\` JSON for the "${alias}" space.
+      Use only when you need exact column / table identifiers
+      \`get_space_description\` doesn't expose. Larger payload, so
+      prefer the description tool when it's enough.
+    `),
+		inputSchema: z.object({}),
+		outputSchema: z.object({ space: z.unknown() }),
+		execute: async (_input, ctxRaw) => {
+			const ctx = ctxRaw;
+			const { client } = requireClient(ctx, toolId);
+			const signal = ctx?.abortSignal;
+			return { space: await getGenieSpace(spaceId, {
+				workspaceClient: client,
+				...signal ? { context: signal } : {}
+			}) };
+		}
+	});
+}
+/**
+* Default row cap for {@link buildGetStatementTool} when the agent
+* doesn't supply a `limit`. Sized to keep result sets out of the
+* model context unless the agent explicitly opts into more rows -
+* the cheap shape (column names + a handful of representative
+* rows) is usually enough to reason about a query.
+*/
+const DEFAULT_STATEMENT_LIMIT = 50;
+function buildGetStatementTool() {
+	const toolId = "get_statement";
+	return createTool$1({
+		id: toolId,
+		description: stringUtils.toDescription(`
+      Fetch the rows of a Genie statement by its \`statement_id\` (the
+      value at \`message.query_result.statement_id\` or
+      \`message.attachments[*].query.statement_id\` returned from
+      \`ask_genie\`). Use this ONLY when you need to read the underlying
+      values to reason about them in your reply - e.g. naming the
+      largest row, computing a delta the visualization wouldn't already
+      convey, or filtering down to a specific record. If you'd just be
+      reciting numbers the user will see anyway, skip the call and
+      embed a \`[data:<statement_id>]\` marker in your prose instead;
+      the host UI fetches and renders the rows on its own. \`limit\`
+      caps the number of rows returned (defaults to
+      ${DEFAULT_STATEMENT_LIMIT}). \`rowCount\` reflects the full
+      upstream total - compare to \`rows.length\` to detect truncation.
+    `),
+		inputSchema: z.object({
+			statement_id: z.string().min(1, "statement_id is required"),
+			limit: z.number().int().nonnegative().optional().describe("Max rows to return. Defaults to a small sample; raise only when more rows are genuinely needed.")
+		}),
+		outputSchema: z.object({
+			columns: z.array(z.string()),
+			rows: z.array(z.record(z.string(), z.unknown())),
+			rowCount: z.number(),
+			truncated: z.boolean()
+		}),
+		execute: async ({ statement_id, limit }, ctxRaw) => {
+			const ctx = ctxRaw;
+			const { client } = requireClient(ctx, toolId);
+			const signal = ctx?.abortSignal;
+			const data = await fetchStatementData(client, statement_id, {
+				limit: limit ?? DEFAULT_STATEMENT_LIMIT,
+				...signal ? { signal } : {}
+			});
+			return {
+				columns: data.columns,
+				rows: data.rows,
+				rowCount: data.rowCount,
+				truncated: data.rows.length < data.rowCount
+			};
+		}
+	});
+}
+/**
+* `prepare_chart` Mastra tool. Thin wrapper over
+* {@link prepareChart} that resolves the dataset by fetching the
+* Genie statement's rows on demand. The tool mints a `chartId`
+* synchronously, caches an empty placeholder, and kicks off the
+* planner in the background so the agent loop never blocks. The
+* host UI resolves `[chart:<chartId>]` markers by reading the
+* cached {@link Chart} entry (1h TTL).
+*
+* Space-agnostic: a Genie `statement_id` is workspace-scoped, so
+* one shared `prepare_chart` tool covers every wired Genie space.
+*
+* Cancellation: deliberately does NOT forward the per-call
+* `abortSignal` to {@link prepareChart}. The planner task is
+* fire-and-forget background work; the tool's own `execute`
+* resolves the moment the `chartId` is minted, so the per-call
+* signal aborts the second the tool returns. The 1h cache TTL
+* caps abandoned entries.
+*/
+function buildPrepareChartTool(opts) {
+	const { config } = opts;
+	const toolId = "prepare_chart";
+	return createTool$1({
+		id: toolId,
+		description: stringUtils.toDescription([
+			`
+        Queue a chart for the rows of a Genie statement. Mints a
+        short \`chartId\` synchronously and kicks off a BACKGROUND
+        task that fetches the statement's rows, runs the
+        chart-planner to pick a chart type and Echarts spec, and
+        caches the result under the \`chartId\` for one hour. The
+        host UI fetches the cached chart on its own once it lands.
+      `,
+			`
+        To display the chart in your reply, embed
+        \`[chart:<chartId>]\` on its own line at the position you
+        want it to appear, using the EXACT \`chartId\` string this
+        call returned. Never construct a chart id yourself (it is
+        not the \`statement_id\` or any variation of it) - only a
+        value returned by this tool resolves to a real chart. The
+        tool returns immediately - do NOT wait or call it again to
+        "check progress"; the chart resolves asynchronously on the
+        host UI's side.
+      `,
+			`
+        Use this only when the data has a story a chart conveys
+        better than a table (trends, rankings, distributions,
+        parts-of-a-whole). For raw rows, embed
+        \`[data:<statement_id>]\` instead and skip this tool.
+      `
+		]),
+		inputSchema: prepareChartRequestSchema,
+		outputSchema: ChartSchema.pick({ chartId: true }),
+		execute: async (request, ctxRaw) => {
+			const ctx = ctxRaw;
+			const { client } = requireClient(ctx, toolId);
+			return prepareChart({
+				config,
+				...request.title ? { title: request.title } : {},
+				...request.description ? { description: request.description } : {},
+				resolveData: (taskSignal) => fetchStatementData(client, request.statement_id, { ...taskSignal ? { signal: taskSignal } : {} }),
+				...ctx?.requestContext ? { requestContext: ctx.requestContext } : {}
+			});
+		}
+	});
+}
+/**
+* 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:
+*
+* ```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`).
+*/
+const GENIE_INSTRUCTIONS = stringUtils.toDescription(["Genie orchestration. For every user question that needs SQL-backed data:", { numbered: [
+	`
+        Start by calling \`get_space_description\` to ground yourself
+        in what the space covers (tables, metrics, time windows),
+        unless you already saw the same description earlier in this
+        conversation. Reach for \`get_space_serialized\` only when you
+        need exact column / table identifiers the description doesn't
+        expose - it's a much larger payload.
+      `,
+	`
+        Decompose the user's question into focused sub-questions
+        BEFORE asking Genie anything. One sub-question per distinct
+        metric, dimension, or time window. Then call \`ask_genie\`
+        once per sub-question - usually two to six calls per turn,
+        and let earlier answers inform what you ask next. Cramming
+        a multi-part question into one \`ask_genie\` call almost
+        always produces a worse answer than asking the pieces
+        separately. Only collapse to a single call when the question
+        is genuinely atomic ("what was Q3 revenue?").
+
+        Worked example: user asks "How did SKU 1234's revenue
+        compare to its category average last quarter, and which
+        regions drove the gap?" Decomposes to: (a) \`ask_genie\`
+        for SKU 1234's Q3 revenue, (b) \`ask_genie\` for the
+        category-average Q3 revenue, (c) \`ask_genie\` for SKU
+        1234's Q3 revenue split by region. Three focused calls,
+        each grounded in the prior results.
+      `,
+	`
+        Each \`ask_genie\` call returns the terminal \`GenieMessage\`.
+        When the turn ran SQL the result has a \`statement_id\` - read
+        it from \`message.query_result.statement_id\` (or the first
+        attachment's \`query.statement_id\`).
+      `,
+	[
+		`
+          To DISPLAY a result set in your reply, embed a marker on its
+          own line where the visualization should appear. Two marker
+          shapes:
+        `,
+		{ bullets: [`
+              \`[data:<statement_id>]\` - render the rows as a table.
+              Use this when there's no clear visual story (long lists,
+              reference data, single-row results, or the user just
+              wants to see the data). Embed the marker directly; no
+              tool call needed.
+            `, `
+              \`[chart:<chartId>]\` - render the rows as a chart. To
+              get a \`<chartId>\`, call \`prepare_chart\` with the
+              statement's id (and an optional \`title\` / one-line
+              \`description\` of the insight to surface). The tool
+              returns the \`chartId\` synchronously and prepares the
+              chart spec in the background; embed the returned id as
+              \`[chart:<chartId>]\` on its own line wherever the
+              chart should appear. Use a chart when the data has a
+              story a visual conveys better than a table (trends,
+              rankings, distributions, parts-of-a-whole).
+
+              NEVER invent or hand-build a \`<chartId>\`. A valid
+              \`<chartId>\` is the opaque token a \`prepare_chart\`
+              call returned to you in THIS turn - nothing else. It
+              is NOT a \`statement_id\`, and it is NOT a
+              \`statement_id\` prefix with a label appended (e.g.
+              \`01f1...-region-fill\`). If you have not called
+              \`prepare_chart\` and received an id back, do not write
+              a \`[chart:...]\` marker at all - use \`[data:...]\`
+              instead. A fabricated chart id renders nothing and
+              wastes a request.
+            `] },
+		`
+          The host UI resolves both markers on its own once it sees
+          them - you do NOT need to call \`get_statement\` just to
+          display data, and you do NOT need to wait on
+          \`prepare_chart\` (it returns the id immediately and the
+          host UI fetches the cached chart later). Pick at most one
+          marker per statement; don't chart AND table the same result
+          side by side.
+        `
+	],
+	`
+        Call \`get_statement(statement_id, limit?)\` ONLY when you need
+        to read the actual values to reason about them (e.g. naming a
+        specific row, computing a delta the table or chart wouldn't
+        show, or sanity-checking a result before interpreting it). If
+        you'd just be reciting numbers the visualization already shows,
+        skip the call and use a marker instead. \`limit\` defaults to a
+        small sample; raise it only when you genuinely need more rows.
+      `,
+	`
+        Compose your final reply as plain prose. Interleave paragraphs
+        with \`[data:...]\` / \`[chart:...]\` markers wherever a result
+        should render. Don't dump all markers at the end - place each
+        one next to the prose that interprets it. Don't restate every
+        number the visualization already shows; call out deltas,
+        anomalies, takeaways.
+      `
+] }]);
+/**
+* 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).
+*/
+function normalizeGenieSpaces(spaces) {
+	if (!spaces) return {};
+	const out = {};
+	for (const [alias, value] of Object.entries(spaces)) {
+		if (value === void 0) continue;
+		if (typeof value === "string") {
+			if (!value) continue;
+			out[alias] = { spaceId: value };
+			continue;
+		}
+		if (!value.spaceId) continue;
+		out[alias] = value;
+	}
+	return out;
+}
+/**
+* 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.
+*/
+function resolveGenieSpaces(config, context) {
+	const merged = {};
+	const envSpaceId = process.env["DATABRICKS_GENIE_SPACE_ID"];
+	if (envSpaceId) merged[DEFAULT_GENIE_ALIAS] = { spaceId: envSpaceId };
+	const geniePlugin = appkitUtils.instance(context, genie);
+	if (geniePlugin) {
+		const pluginSpaces = geniePlugin.config?.spaces;
+		if (pluginSpaces) Object.assign(merged, normalizeGenieSpaces(pluginSpaces));
+	}
+	if (config.genieSpaces) Object.assign(merged, normalizeGenieSpaces(config.genieSpaces));
+	return merged;
+}
+/**
+* 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.
+*/
+function buildGenieTools(opts) {
+	const normalized = normalizeGenieSpaces(opts.spaces);
+	const tools = {};
+	if (Object.keys(normalized).length === 0) return tools;
+	tools.get_statement = buildGetStatementTool();
+	tools.prepare_chart = buildPrepareChartTool({ config: opts.config });
+	for (const [alias, space] of Object.entries(normalized)) {
+		const askTool = buildAskGenieTool({
+			spaceId: space.spaceId,
+			alias,
+			...space.hint ? { hint: space.hint } : {}
+		});
+		const descTool = buildSpaceDescriptionTool({
+			spaceId: space.spaceId,
+			alias
+		});
+		const serTool = buildSpaceSerializedTool({
+			spaceId: space.spaceId,
+			alias
+		});
+		tools[askTool.id] = askTool;
+		tools[descTool.id] = descTool;
+		tools[serTool.id] = serTool;
+	}
+	return tools;
+}
+/**
+* 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.
+*/
+function buildGenieToolkitProvider(opts) {
+	return { toolkit(_opts) {
+		return buildGenieTools(opts);
+	} };
+}
+/**
+* Default cap on starter suggestions surfaced to the chat empty
+* state. Sample-question lists can run long (10+ on a curated
+* space); a handful of one-tap prompts reads better than a wall of
+* buttons.
+*/
+const SUGGESTION_LIMIT = 6;
+/**
+* How long a space's parsed sample questions stay cached. They're
+* authored config that changes rarely, and the lookup is an extra
+* REST round-trip per chat mount, so a few minutes of caching keeps
+* the empty state instant on reload without going stale for long.
+*/
+const SUGGESTION_CACHE_TTL_MS = 10 * 6e4;
+/** Space-id -> cached sample questions with an absolute expiry. */
+const _suggestionCache = /* @__PURE__ */ new Map();
+/** Read a space's cached questions, or `undefined` on miss / expiry. */
+function readSuggestionCache(spaceId) {
+	const entry = _suggestionCache.get(spaceId);
+	if (!entry) return void 0;
+	if (entry.expires <= Date.now()) {
+		_suggestionCache.delete(spaceId);
+		return;
+	}
+	return entry.questions;
+}
+/** Cache a space's parsed questions for {@link SUGGESTION_CACHE_TTL_MS}. */
+function writeSuggestionCache(spaceId, questions) {
+	_suggestionCache.set(spaceId, {
+		questions,
+		expires: Date.now() + SUGGESTION_CACHE_TTL_MS
+	});
+}
+/**
+* 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.
+*/
+async function collectSpaceSuggestions(opts) {
+	const limit = opts.limit ?? SUGGESTION_LIMIT;
+	const merged = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const { spaceId } of Object.values(opts.spaces)) {
+		let questions = readSuggestionCache(spaceId);
+		if (!questions) try {
+			questions = genieSampleQuestions(await getGenieSpace(spaceId, {
+				workspaceClient: opts.client,
+				...opts.signal ? { context: opts.signal } : {}
+			}));
+			writeSuggestionCache(spaceId, questions);
+		} catch (err) {
+			log$4.warn("suggestions:fetch-error", {
+				spaceId,
+				error: commonUtils.errorMessage(err)
+			});
+			questions = [];
+		}
+		for (const question of questions) {
+			if (seen.has(question)) continue;
+			seen.add(question);
+			merged.push(question);
+			if (merged.length >= limit) return merged;
+		}
+	}
+	return merged;
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/processor.ts
+var ResultProcessor = class {
+	id = "result-processor";
+	processDataParts = true;
+	async processOutputStream({ part }) {
+		if (!part || typeof part !== "object") return part;
+		if (![
+			"step-finish",
+			"finish",
+			"tool-result",
+			"data-tool-agent"
+		].includes(part.type)) return part;
+		const payload = part.payload;
+		if (!payload || typeof payload !== "object") return part;
+		for (const key of [
+			"output",
+			"messages",
+			"response",
+			"result"
+		]) if (key in payload) {
+			const value = payload[key];
+			if (typeof value === "object") payload[key] = {};
+			else if (Array.isArray(value)) payload[key] = [];
+			else delete payload[key];
+		}
+		return part;
+	}
+};
+
+//#endregion
+//#region packages/appkit-mastra/src/processors/strip-stale-charts.ts
+/**
+* Mastra input processor that strips `chartId` fields from every
+* tool-invocation result in prior assistant messages before they
+* reach the model.
+*
+* Why: chartIds are turn-scoped from the model's point of view -
+* each `prepare_chart` / `render_data` call mints a fresh id and
+* the host UI binds it to that turn's reply. Mastra Memory
+* replays prior tool results into the prompt; if old chartIds
+* leak through, the model is tempted to copy them verbatim into
+* the new turn's `[chart:<id>]` markers and the host UI ends up
+* rendering an unrelated chart from the chart cache (or
+* a 404 once the 1h TTL elapsed). This processor removes the
+* temptation by deleting `chartId` keys from every assistant
+* message's tool results before the prompt is built. The current
+* turn's tool results don't exist yet at `processInput` time, so
+* they pass through unmodified.
+*
+* The strip is recursive - any nested `chartId` field is removed,
+* regardless of which tool produced the result. This covers
+* `prepare_chart` / `render_data` top-level chartIds and any
+* legacy `datasets[].chartId` payloads uniformly without coupling
+* to specific tool ids.
+*/
+const log$3 = logUtils.logger("mastra/processor/strip-stale-charts");
+/**
+* Recursively clone `value`, omitting any property whose key is
+* `chartId`. Arrays are mapped element-wise; primitives are
+* returned as-is. The result is structurally identical to the
+* input minus chartIds, so downstream message-shape consumers
+* keep working.
+*/
+function stripChartIds(value) {
+	if (Array.isArray(value)) return value.map(stripChartIds);
+	if (value && typeof value === "object") {
+		const obj = value;
+		const out = {};
+		for (const [key, val] of Object.entries(obj)) {
+			if (key === "chartId") continue;
+			out[key] = stripChartIds(val);
+		}
+		return out;
+	}
+	return value;
+}
+/**
+* Input processor that scrubs `chartId` from every tool-invocation
+* result in the message list. Wired onto every agent by default
+* via {@link buildAgents}; opt out with
+* `MastraPluginConfig.stripStaleCharts: false`.
+*/
+const stripStaleChartsProcessor = {
+	id: "strip-stale-charts",
+	description: "Removes chartId fields from prior tool-invocation results so the model can't reuse turn-scoped ids from memory.",
+	processInput(args) {
+		let stripped = 0;
+		for (const message of args.messages) {
+			if (message.role !== "assistant") continue;
+			const parts = message.content?.parts;
+			if (!Array.isArray(parts)) continue;
+			for (const part of parts) {
+				if (part.type !== "tool-invocation") continue;
+				const inv = part.toolInvocation;
+				if (!inv || inv.result === void 0) continue;
+				const before = inv.result;
+				const after = stripChartIds(before);
+				if (typeof before === "object" && before !== null && JSON.stringify(before).length !== JSON.stringify(after).length) {
+					inv.result = after;
+					stripped += 1;
+				}
+			}
+		}
+		if (stripped > 0) log$3.debug("stripped", { results: stripped });
+		return args.messages;
+	}
+};
+
+//#endregion
+//#region packages/appkit-mastra/src/agents.ts
+/**
+* Agent registration for the Mastra AppKit plugin.
+*
+* Mirrors the shape of the AppKit `agents` plugin (`config.agents` map
+* of {@link MastraAgentDefinition}, dual-form `tools` accepting a plain
+* record or a `(plugins) => tools` callback). Resolves each definition
+* into a Mastra `Agent` instance during plugin setup; user-supplied
+* tool callbacks are invoked exactly once with a typed
+* {@link MastraPlugins} map built from registered sibling plugins.
+*
+* When no agents are registered the plugin falls back to a single
+* built-in analyst so the bare `mastra()` call still mounts a working
+* streamable agent for demos.
+*/
+/**
+* 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.).
+*/
+function tool(opts) {
+	return createTool$1({
+		id: opts.id ?? deriveToolId(opts.description),
+		description: opts.description,
+		...opts.schema ? { inputSchema: opts.schema } : {},
+		execute: opts.execute
+	});
+}
+/**
+* Build a deterministic Mastra tool id from a description.
+* Delegates to {@link stringUtils.toUniqueSlug}: slug + always-on
+* 6-char FNV-1a base-32 suffix so two tools with the same leading
+* words don't collide in traces. Stable across runs.
+*/
+function deriveToolId(description) {
+	return stringUtils.toUniqueSlug(description, { fallbackPrefix: "tool" });
+}
+/**
+* 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.
+*/
+function createAgent(def) {
+	return def;
+}
+/** Fallback agent id used when `config.agents` is omitted entirely. */
+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.
+*/
+const DEFAULT_AGENT_MAX_STEPS = 25;
+const FALLBACK_AGENT_INSTRUCTIONS = `You are a data analyst. The user will ask questions about
+business metrics and may share personal preferences you should remember across turns.
+
+Rules:
+
+1. Quote numbers exactly. Never invent data.
+2. When the user states a preference or durable fact about themselves
+   ("I'm in EU so use EUR", "always show me the SQL"), acknowledge that
+   you will remember it.
+3. If you don't have enough information to answer, ask a clarifying
+   question instead of guessing.`;
+/**
+* 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).
+*/
+const DEFAULT_STYLE_INSTRUCTIONS = [
+	"Output style:",
+	"",
+	"Use markdown formatting, including headings, lists, and code blocks.",
+	"Avoid lists and headers for short replies.",
+	"Plain prose.",
+	"Use hyphens (-) only. Never use em dashes or en dashes.",
+	"Never use emojis.",
+	"Skip openers like 'Great question', 'Absolutely', and 'I'd be happy to help'.",
+	"Skip closers like 'Let me know if you have any questions'.",
+	"Skip self-disclaimers like 'I should mention' and 'It's important to note'.",
+	"Answer directly.",
+	"Do not include a preamble before the actual answer.",
+	"Use lists and headers only when they clarify a multi-part answer."
+].join("\n");
+/**
+* Resolve the style block to append to every agent's instructions.
+* Returns `null` when the caller opted out (`styleInstructions: false`).
+*/
+function resolveStyleInstructions(config) {
+	if (config.styleInstructions === false) return null;
+	if (typeof config.styleInstructions === "string") return config.styleInstructions;
+	return DEFAULT_STYLE_INSTRUCTIONS;
+}
+/**
+* Join an agent's bespoke instructions with the resolved style block.
+* Returns the bespoke text unchanged when the style block is disabled.
+*/
+function composeInstructions(agentInstructions, style) {
+	if (!style) return agentInstructions;
+	return `${agentInstructions.trimEnd()}\n\n${style}`;
+}
+/**
+* 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.
+*/
+async function buildAgents(opts) {
+	const { config, context, memoryBuilder, log } = opts;
+	const definitions = resolveDefinitions(config);
+	const ids = Object.keys(definitions);
+	const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
+	const plugins = buildPluginsMap(config, context);
+	const ambientTools = {
+		render_data: buildRenderDataTool(config),
+		...config.tools ?? {}
+	};
+	const style = resolveStyleInstructions(config);
+	const outputProcessors = [new ResultProcessor()];
+	const inputProcessors = config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor];
+	const agents = {};
+	for (const [id, def] of Object.entries(definitions)) {
+		const tools = await resolveTools(def.tools, plugins, ambientTools);
+		const memory = memoryBuilder?.forAgent(id, def);
+		agents[id] = new Agent({
+			id,
+			name: def.name ?? id,
+			...def.description !== void 0 ? { description: def.description } : {},
+			instructions: composeInstructions(def.instructions, style),
+			model: resolveModel(config, def.model),
+			defaultOptions: { maxSteps: config.agentMaxSteps ?? DEFAULT_AGENT_MAX_STEPS },
+			tools,
+			...memory ? { memory } : {},
+			inputProcessors,
+			outputProcessors
+		});
+		log.info("agent registered", {
+			id,
+			name: def.name ?? id,
+			defaultModel: describeAgentDefaultModel(config, def),
+			tools: Object.keys(tools)
+		});
+	}
+	if (!agents[defaultAgentId]) throw new Error(`mastra: defaultAgent "${defaultAgentId}" not found in registered agents (${ids.join(", ") || "none"})`);
+	log.info("agents ready", {
+		ids,
+		defaultAgentId
+	});
+	return {
+		agents,
+		defaultAgentId,
+		ambientTools
+	};
+}
+/**
+* Best-effort description of the *static* default model an agent will
+* resolve to at call time. Walks the same precedence ladder as
+* {@link resolveModel} / {@link buildModel}:
+*
+*   1. Per-agent `def.model` (string sugar -> the literal id;
+*      function / `DynamicArgument` -> `"<dynamic>"` because the
+*      resolver decides at call time).
+*   2. Plugin-level `config.defaultModel` (same rules).
+*   3. `DATABRICKS_SERVING_ENDPOINT_NAME` env var.
+*   4. First entry of `config.defaultModelFallbacks ?? FALLBACK_MODEL_IDS`.
+*
+* Used for the startup `agent registered` log so operators can see
+* which endpoint each agent points at by default. Per-request
+* overrides (`X-Mastra-Model` etc.) and the workspace-catalogue
+* fuzzy match are still applied at runtime.
+*/
+function describeAgentDefaultModel(config, def) {
+	const effective = def.model ?? config.defaultModel;
+	if (typeof effective === "string") return effective;
+	if (effective !== void 0) return "<dynamic>";
+	return process.env.DATABRICKS_SERVING_ENDPOINT_NAME ?? config.defaultModelFallbacks?.[0] ?? FALLBACK_MODEL_IDS[0];
+}
+/**
+* Normalize `config.agents` into a `Record<id, definition>`. Accepts
+* any of the three shapes documented on
+* {@link MastraPluginConfig.agents}:
+*
+* - Record - returned as-is when non-empty.
+* - Single definition (detected via the required `instructions`
+*   field) - keyed by `slugify(def.name)` or `FALLBACK_AGENT_ID`.
+* - Array - keyed by `slugify(def.name)` or `agent_${i}`; duplicate
+*   slugs fail loudly so users know to set explicit names.
+*
+* Omitted or empty inputs fall back to a single built-in analyst so
+* the bare `mastra()` call still mounts a working chat route.
+*/
+function resolveDefinitions(config) {
+	const input = config.agents;
+	if (!input) return fallbackDefinitions();
+	if (Array.isArray(input)) {
+		if (input.length === 0) return fallbackDefinitions();
+		const out = {};
+		input.forEach((def, i) => {
+			const key = deriveAgentKey(def, i);
+			if (out[key]) throw new Error(`mastra: duplicate agent id "${key}" derived from name "${def.name ?? ""}"; set unique \`name\`s on each definition`);
+			out[key] = def;
+		});
+		return out;
+	}
+	if (typeof input.instructions === "string") {
+		const def = input;
+		return { [deriveAgentKey(def)]: def };
+	}
+	const record = input;
+	if (Object.keys(record).length === 0) return fallbackDefinitions();
+	return record;
+}
+/** Derive a registry id from a definition's `name`, with a fallback. */
+function deriveAgentKey(def, index) {
+	if (def.name) {
+		const slug = stringUtils.toIdentifier(def.name);
+		if (slug) return slug;
+	}
+	return index === void 0 ? FALLBACK_AGENT_ID : `agent_${index}`;
+}
+/** Built-in fallback registry used when `agents` is omitted / empty. */
+function fallbackDefinitions() {
+	return { [FALLBACK_AGENT_ID]: {
+		name: "Default Agent",
+		instructions: FALLBACK_AGENT_INSTRUCTIONS
+	} };
+}
+/**
+* Pick the effective model spec for an agent. Fallback ladder, in
+* order:
+*
+*   1. Per-agent `def.model` (string sugar or `DynamicArgument`).
+*   2. Plugin-level `config.defaultModel` (string sugar or
+*      `DynamicArgument`) - mirrors AppKit's `agents({ defaultModel })`.
+*   3. The auto-resolver that mints user-scoped tokens against
+*      `/serving-endpoints` via {@link buildModel}.
+*
+* String values are treated as `modelId` sugar and threaded through
+* `buildModel`'s override hook so the runtime fuzzy matcher and the
+* per-request `X-Mastra-Model` override layer on top of the static
+* choice. Non-string `DynamicArgument`s are passed through verbatim;
+* callers that need full control over `providerId` / `headers` /
+* `modelId` bypass the resolver pipeline entirely.
+*/
+function resolveModel(config, override) {
+	const effective = override ?? config.defaultModel;
+	if (effective === void 0) return ({ requestContext }) => buildModel(config, requestContext);
+	if (typeof effective === "string") {
+		const modelId = effective;
+		return ({ requestContext }) => buildModel(config, requestContext, { modelId });
+	}
+	return effective;
+}
+/**
+* Resolve a definition's `tools` field to a flat `MastraTools` record,
+* merging in plugin-level ambient tools (per-agent tools win on key
+* collision). Callback errors propagate verbatim so the original stack
+* survives - the caller already knows which agent was registering.
+*/
+async function resolveTools(defTools, plugins, ambientTools) {
+	if (!defTools) return { ...ambientTools };
+	const resolved = typeof defTools === "function" ? await defTools(plugins) : defTools;
+	return {
+		...ambientTools,
+		...resolved
+	};
+}
+/**
+* Build the {@link MastraPlugins} runtime proxy handed to
+* `tools(plugins)` callbacks.
+*
+* Implemented as a `Proxy` over the AppKit plugin context so
+* `plugins.<name>` resolves at first access. Any sibling plugin that
+* implements AppKit's standard `ToolProvider` interface
+* (`toolkit(opts?)` + `executeAgentTool(name, args, signal?)`) is
+* auto-adapted into Mastra tools. Unknown names return `undefined`,
+* matching AppKit's `Plugins` semantics so `plugins.foo?.toolkit()`
+* remains safe in environments where `foo` isn't registered.
+*
+* `genie` is special-cased to swap the generic AppKit toolkit (which
+* runs `executeAgentTool` and only emits a single final `tool-result`
+* chunk per call) for the streaming-aware tools built by
+* {@link buildGenieProvider}. The streaming variant forwards each
+* Genie wire event (status, SQL, row counts, errors) out through the
+* Mastra `ctx.writer`, so the UI gets `tool-output` chunks in real
+* time instead of staring at a spinner for the full Genie round-trip.
+*/
+function buildPluginsMap(config, context) {
+	const cache = /* @__PURE__ */ new Map();
+	return new Proxy({}, { get(_target, propName) {
+		if (typeof propName !== "string") return void 0;
+		if (cache.has(propName)) return cache.get(propName) ?? void 0;
+		const provider = resolveProvider(config, context, propName);
+		cache.set(propName, provider);
+		return provider ?? void 0;
+	} });
+}
+/**
+* Pick the right {@link MastraPluginToolkitProvider} for a sibling
+* plugin lookup. Returns the Genie agent-backed adapter when
+* the caller asks for `genie` AND at least one space is reachable
+* via {@link resolveGenieSpaces} (the explicit
+* `config.genieSpaces`, the registered AppKit `genie()` plugin's
+* `spaces` config, or the `DATABRICKS_GENIE_SPACE_ID` env var).
+* Falls back to the generic AppKit `ToolProvider` adapter for
+* every other plugin name. `config` is threaded through so the
+* Genie agent inherits the same model resolver / fallback
+* ladder the calling agents use.
+*
+* The Genie agent talks to Genie directly via `@dbx-tools/genie`
+* (`genieEventChat`) and the workspace
+* `statementExecution.getStatement` API. AppKit's stock `genie`
+* plugin is honored only for its resource manifest and `spaces`
+* config so existing `app.yaml` configs and `genie({ spaces })`
+* wiring keep working without change.
+*/
+function resolveProvider(config, context, propName) {
+	if (propName === "genie") {
+		const spaces = resolveGenieSpaces(config, context);
+		if (Object.keys(spaces).length === 0) return null;
+		return buildGenieToolkitProvider({
+			spaces,
+			config
+		});
+	}
+	const plugin = context?.getPlugins().get(propName);
+	return adaptPluginToolkit(plugin);
+}
+/**
+* Adapt an AppKit `ToolProvider` plugin instance into a
+* {@link MastraPluginToolkitProvider}. Returns `null` for any plugin
+* that doesn't implement both `toolkit` and `executeAgentTool` (e.g.
+* `server`, `lakebase` when used only as a Postgres pool, etc.).
+*/
+function adaptPluginToolkit(plugin) {
+	if (!plugin || typeof plugin !== "object") return null;
+	const p = plugin;
+	if (typeof p.toolkit !== "function" || typeof p.executeAgentTool !== "function") return null;
+	return { toolkit(opts) {
+		const entries = p.toolkit(opts);
+		const tools = {};
+		for (const [key, entry] of Object.entries(entries)) tools[key] = toolkitEntryToMastraTool(entry, p);
+		return tools;
+	} };
+}
+/**
+* Wrap a single {@link AppKitToolkitEntry} as a Mastra tool whose
+* `execute` dispatches back through `plugin.executeAgentTool(...)` so
+* AppKit's OBO auth (`asUser`) and telemetry spans stay intact. JSON
+* Schema parameters pass through unchanged - Mastra's `PublicSchema`
+* accepts `JSONSchema7` directly via `@mastra/schema-compat`.
+*/
+function toolkitEntryToMastraTool(entry, plugin) {
+	return createTool$1({
+		id: `${entry.pluginName}__${entry.localName}`,
+		description: entry.def.description,
+		...entry.def.parameters ? { inputSchema: entry.def.parameters } : {},
+		execute: async (input, context) => {
+			const signal = context?.abortSignal;
+			return plugin.executeAgentTool(entry.localName, input, signal);
+		}
+	});
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/mcp.ts
+/** MCP server version advertised when the caller doesn't pin one. */
+const DEFAULT_MCP_VERSION = "1.0.0";
+/**
+* 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.
+*/
+function buildMcpServer(opts) {
+	const { config, pluginName, displayName, agents, ambientTools } = opts;
+	if (!config.mcp) return null;
+	const settings = config.mcp === true ? {} : config.mcp;
+	const serverId = settings.serverId ?? pluginName;
+	const exposeAgents = settings.agents !== false;
+	const tools = {
+		...settings.tools === true ? ambientTools : {},
+		...settings.extraTools ?? {}
+	};
+	return {
+		serverId,
+		server: new MCPServer({
+			id: serverId,
+			name: settings.name ?? `${displayName} MCP`,
+			version: settings.version ?? DEFAULT_MCP_VERSION,
+			...settings.description ? { description: settings.description } : {},
+			...exposeAgents ? { agents } : {},
+			tools
+		}),
+		httpPath: `/mcp/${serverId}/mcp`,
+		ssePath: `/mcp/${serverId}/sse`,
+		messagePath: `/mcp/${serverId}/messages`
+	};
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/history.ts
+const log$2 = logUtils.logger("mastra/history");
+/** Default history page size; matches the Mastra storage default. */
+const DEFAULT_PER_PAGE = 20;
+/** Hard cap so a misbehaving client can't fetch the whole thread at once. */
+const MAX_PER_PAGE = 200;
+/**
+* Fetch a page of UI-formatted messages for a thread.
+*
+* Uses the agent's resolved `Memory` (`getMemory()`) so per-agent
+* storage namespaces (`mastra_<agentId>` schemas) and any future
+* memory-side filters apply automatically. When the agent has no
+* memory configured the response is a successful empty page so
+* callers don't have to special-case stateless agents.
+*
+* Pagination is descending-by-default: page 0 is the most recent
+* page, page 1 the page before that, etc. The returned `uiMessages`
+* are always re-sorted into chronological order (oldest -> newest)
+* so the client can prepend them above the existing transcript
+* without sorting locally.
+*/
+async function loadHistory(opts) {
+	const perPage = clampPerPage(opts.perPage);
+	const page = Math.max(0, Math.trunc(opts.page ?? 0));
+	const memory = await opts.agent.getMemory();
+	if (!memory) {
+		log$2.debug("recall:no-memory", {
+			agentId: opts.agent.id,
+			threadId: opts.threadId
+		});
+		return {
+			uiMessages: [],
+			page,
+			perPage,
+			total: 0,
+			hasMore: false
+		};
+	}
+	const startedAt = Date.now();
+	const result = await memory.recall({
+		threadId: opts.threadId,
+		...opts.resourceId ? { resourceId: opts.resourceId } : {},
+		page,
+		perPage,
+		orderBy: {
+			field: "createdAt",
+			direction: opts.ascending ? "ASC" : "DESC"
+		}
+	});
+	const uiMessages = toAISdkV5Messages(sortChronological(result.messages));
+	log$2.debug("recall:done", {
+		agentId: opts.agent.id,
+		threadId: opts.threadId,
+		page,
+		perPage,
+		returned: uiMessages.length,
+		total: result.total,
+		hasMore: result.hasMore,
+		elapsedMs: Date.now() - startedAt
+	});
+	return {
+		uiMessages,
+		page,
+		perPage,
+		total: result.total,
+		hasMore: result.hasMore
+	};
+}
+/**
+* Wipe every persisted message tied to a thread. Returns the count
+* of messages that were on the thread at delete time so the caller
+* can render a "cleared N messages" affordance without an
+* additional round-trip.
+*
+* Agents without a configured `Memory` resolve to a no-op (count
+* 0), matching {@link loadHistory}'s "stateless agents return an
+* empty page" stance so callers don't have to special-case them.
+* Threads that don't exist yet are also a successful no-op - the
+* operation is idempotent so the UI can fire-and-forget without
+* tracking thread existence.
+*/
+async function clearHistory(opts) {
+	const memory = await opts.agent.getMemory();
+	if (!memory) {
+		log$2.debug("clear:no-memory", {
+			agentId: opts.agent.id,
+			threadId: opts.threadId
+		});
+		return { cleared: 0 };
+	}
+	let cleared = 0;
+	try {
+		cleared = (await memory.recall({
+			threadId: opts.threadId,
+			page: 0,
+			perPage: 1
+		})).total;
+	} catch (err) {
+		log$2.debug("clear:probe-failed", {
+			agentId: opts.agent.id,
+			threadId: opts.threadId,
+			error: commonUtils.errorMessage(err)
+		});
+	}
+	const startedAt = Date.now();
+	try {
+		await memory.deleteThread(opts.threadId);
+	} catch (err) {
+		log$2.warn("clear:delete-soft-failed", {
+			agentId: opts.agent.id,
+			threadId: opts.threadId,
+			error: commonUtils.errorMessage(err)
+		});
+	}
+	log$2.info("clear:done", {
+		agentId: opts.agent.id,
+		threadId: opts.threadId,
+		cleared,
+		elapsedMs: Date.now() - startedAt
+	});
+	return { cleared };
+}
+/**
+* Register the `<path>` Mastra custom API route. Handles two
+* methods on the same mount:
+*
+*   - `GET`: return a page of AI SDK V5 `UIMessage`s for the
+*     caller's current thread ({@link loadHistory}).
+*   - `DELETE`: wipe every persisted message on the caller's
+*     thread ({@link clearHistory}). The session cookie that
+*     anchors the thread id is left alone so the user keeps the
+*     same thread - only the contents go away.
+*
+* Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
+* binding: pass `agent` for a fixed-agent mount, or include
+* `:agentId` in the path for dynamic routing. The plugin registers
+* both `/route/history` (default agent) and `/route/history/:agentId`.
+*
+* The handler reads `threadId` and `resourceId` from `RequestContext`
+* (populated upstream by `MastraServer.registerAuthMiddleware`), so
+* no cookie or user lookups happen here.
+*/
+function historyRoute(options) {
+	const { path } = options;
+	const fixedAgent = "agent" in options ? options.agent : void 0;
+	if (!fixedAgent && !path.includes(":agentId")) throw new Error("historyRoute path must include `:agentId` or `agent` must be passed explicitly");
+	const resolveContext = (c) => {
+		const mastra = c.get("mastra");
+		const requestContext = c.get("requestContext");
+		const agentId = fixedAgent ?? c.req.param("agentId");
+		if (!agentId) return { error: c.json({ error: "agentId is required" }, 400) };
+		const agent = mastra.getAgentById(agentId);
+		if (!agent) return { error: c.json({ error: `Unknown agent "${agentId}"` }, 404) };
+		const threadId = requestContext.get(MASTRA_THREAD_ID_KEY);
+		if (!threadId) return { error: c.json({ error: "thread id missing from request context" }, 400) };
+		return {
+			agentId,
+			agent,
+			threadId,
+			resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY)
+		};
+	};
+	return [registerApiRoute(path, {
+		method: "GET",
+		handler: async (c) => {
+			const ctx = resolveContext(c);
+			if ("error" in ctx) return ctx.error;
+			const payload = await loadHistory({
+				agent: ctx.agent,
+				threadId: ctx.threadId,
+				...ctx.resourceId ? { resourceId: ctx.resourceId } : {},
+				page: parseIntParam(c.req.query("page")),
+				perPage: parseIntParam(c.req.query("perPage"))
+			});
+			return c.json(payload);
+		}
+	}), registerApiRoute(path, {
+		method: "DELETE",
+		handler: async (c) => {
+			const ctx = resolveContext(c);
+			if ("error" in ctx) return ctx.error;
+			const { cleared } = await clearHistory({
+				agent: ctx.agent,
+				threadId: ctx.threadId
+			});
+			const payload = {
+				ok: true,
+				agentId: ctx.agentId,
+				threadId: ctx.threadId,
+				cleared
+			};
+			return c.json(payload);
+		}
+	})];
+}
+/** Coerce / clamp `perPage`; falls back to the page-size default. */
+function clampPerPage(value) {
+	if (value === void 0 || Number.isNaN(value)) return DEFAULT_PER_PAGE;
+	const n = Math.trunc(value);
+	if (n <= 0) return DEFAULT_PER_PAGE;
+	return Math.min(n, MAX_PER_PAGE);
+}
+/**
+* Sort messages oldest-first by `createdAt`, falling back to whatever
+* order the storage returned them in. The native `recall` call honors
+* `orderBy` but doesn't guarantee a stable secondary sort, so we
+* normalize here before handing the page to the AI SDK converter.
+*/
+function sortChronological(messages) {
+	return [...messages].sort((a, b) => {
+		return toEpoch(a.createdAt) - toEpoch(b.createdAt);
+	});
+}
+function toEpoch(value) {
+	if (value instanceof Date) return value.getTime();
+	if (typeof value === "string" || typeof value === "number") {
+		const parsed = new Date(value).getTime();
+		return Number.isNaN(parsed) ? 0 : parsed;
+	}
+	return 0;
+}
+/**
+* Coerce a Hono query value into a non-negative integer. Returns
+* `undefined` for empty / non-numeric / negative inputs so
+* {@link loadHistory} can apply its built-in defaults.
+*/
+function parseIntParam(value) {
+	if (!value) return void 0;
+	const n = Number(value);
+	if (!Number.isFinite(n) || n < 0) return void 0;
+	return Math.trunc(n);
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/memory.ts
+/**
+* Lakebase-backed Mastra memory wiring.
+*
+* Provides a {@link MemoryBuilder} that mints one `Memory` per agent
+* with two independent knobs:
+*
+* - **Storage** (threads / messages via `PostgresStore`): defaults to
+*   **per-agent** namespacing via `schemaName: "mastra_<agentId>"` so
+*   conversation history stays isolated between agents in the same
+*   database. `PostgresStore` auto-creates the schema with
+*   `CREATE SCHEMA IF NOT EXISTS` on init.
+* - **Memory** (semantic recall via `PgVector`): defaults to a single
+*   **shared** instance across every agent. Cross-agent recall on one
+*   index is almost always what users want; opt into per-agent recall
+*   by passing a {@link MastraMemoryConfigOverride} on the agent.
+*
+* Additionally, {@link MemoryBuilder.instanceStorage} returns a
+* **Mastra-instance-level** `PostgresStore` (schema `mastra_instance`)
+* used for workflow snapshots - the persistence layer
+* `agent.resumeStream()` reads from when waking a suspended
+* `requireApproval` tool call. Per-agent stores are not enough for
+* this: workflow runs are scoped to the Mastra instance, not an
+* individual agent's `Memory`.
+*
+* Plugin-level `config.storage` / `config.memory` act as the baseline
+* (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
+* is registered); per-agent settings cascade on top of that.
+*/
+const log$1 = logUtils.logger("mastra/memory");
+/**
+* Build a dedicated **service-principal** Lakebase pool for Mastra
+* memory from the lakebase plugin's resolved SP pg config.
+*
+* The plugin's `exports().pool` is a `RoutingPool` that switches to
+* the per-user (OBO) pool whenever a query runs inside an `asUser`
+* scope - exactly the context the mastra plugin establishes around
+* every chat turn. Memory (threads / messages + semantic recall) must
+* instead always act as the app service principal: it owns the
+* auto-created `mastra_*` schemas (a per-user role usually can't
+* `CREATE SCHEMA`) and is shared across users, so it cannot inherit a
+* request's OBO identity.
+*
+* `pgConfig` must be the plugin's `exports().getPgConfig()` evaluated
+* **outside** any `asUser` scope (i.e. during setup), so it carries
+* the SP connection target, OAuth token-refresh `password` callback,
+* and any `lakebase({ pool })` tuning overrides - all of which this
+* pool inherits. See the call site in `plugin.ts`.
+*/
+async function createServicePrincipalPool(pgConfig) {
+	const user = pgConfig.user ?? await getUsernameWithApiLookup();
+	return new Pool({
+		...pgConfig,
+		user
+	});
+}
+/**
+* True when any plugin-level or per-agent setting could need the
+* Lakebase pool. Used by `plugin.ts` to gate creation of the
+* service-principal pool and the {@link MemoryBuilder} that consumes
+* it; when false neither is built.
+*/
+function needsLakebase(config) {
+	if (settingNeedsSharedPool(config.storage)) return true;
+	if (settingNeedsSharedPool(config.memory)) return true;
+	return collectAgentDefinitions(config).some((d) => settingNeedsSharedPool(d.storage) || settingNeedsSharedPool(d.memory));
+}
+/**
+* Construct a per-agent {@link Memory} factory bound to the supplied
+* service-principal pool (see {@link createServicePrincipalPool}).
+* Caches the shared `PgVector` singleton (built on first need) so each
+* agent build is O(1) after the first.
+*/
+function createMemoryBuilder(config, servicePrincipalPool) {
+	return new MemoryBuilder(config, servicePrincipalPool);
+}
+/**
+* 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.
+*/
+var MemoryBuilder = class {
+	sharedVector;
+	constructor(config, servicePrincipalPool) {
+		this.config = config;
+		this.servicePrincipalPool = servicePrincipalPool;
+	}
+	/**
+	* 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() {
+		const setting = this.config.storage;
+		if (!setting) return void 0;
+		if (typeof setting === "object") return new PostgresStore(withId(setting, "mastra-store__instance"));
+		return new PostgresStore({
+			id: "mastra-store__instance",
+			schemaName: "mastra_instance",
+			pool: this.servicePrincipalPool
+		});
+	}
+	forAgent(agentId, def) {
+		const storageSetting = def.storage ?? this.config.storage;
+		const memorySetting = def.memory ?? this.config.memory;
+		const storage = this.buildStorage(agentId, storageSetting);
+		const vector = this.buildVector(memorySetting);
+		if (!storage && !vector) {
+			log$1.debug("agent:stateless", { agentId });
+			return;
+		}
+		log$1.debug("agent:configured", {
+			agentId,
+			storage: storage !== void 0,
+			vector: vector !== void 0,
+			vectorMode: vector === void 0 ? "off" : typeof memorySetting === "object" ? "dedicated" : "shared"
+		});
+		return new Memory({
+			...storage ? { storage } : {},
+			...vector ? {
+				vector,
+				embedder: fastembed
+			} : {},
+			options: {
+				lastMessages: 10,
+				...vector ? { semanticRecall: {
+					topK: 3,
+					messageRange: 2
+				} } : {}
+			}
+		});
+	}
+	buildStorage(agentId, setting) {
+		if (!setting) return void 0;
+		if (typeof setting === "boolean") return new PostgresStore({
+			id: `mastra-store__${agentId}`,
+			schemaName: `mastra_${agentId}`,
+			pool: this.servicePrincipalPool
+		});
+		return new PostgresStore(withId(setting, `mastra-store__${agentId}`));
+	}
+	/**
+	* 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.
+	*/
+	buildVector(setting) {
+		if (!setting) return void 0;
+		if (typeof setting === "boolean") return this.getSharedVector();
+		return buildPgVector(setting);
+	}
+	getSharedVector() {
+		if (!this.sharedVector) this.sharedVector = buildSharedPgVector(this.servicePrincipalPool);
+		return this.sharedVector;
+	}
+};
+/**
+* Build the shared `PgVector` that backs the default
+* `def.memory === true` case across every agent.
+*
+* `PgVector`'s constructor accepts only connection-style configs
+* (`HostConfig` / `ConnectionStringConfig` / `ClientConfig`); there is
+* no `{ pool }` shorthand the way `PostgresStore` has one. Worse, the
+* constructor synchronously kicks off a `cacheWarmupPromise` IIFE that
+* calls `this.pool.connect()` before returning, so we can't cleanly
+* hand it an inert config and patch the pool afterwards.
+*
+* The trick: pass illegal-but-validation-passing placeholders so the
+* warmup's `net.connect()` rejects synchronously with `RangeError`
+* (Node validates `0 <= port < 65536`). The IIFE's `catch {}` swallows
+* it, no DNS lookup or TCP attempt happens, and we then swap
+* `pgVector.pool` to the lakebase pool. Every subsequent `PgVector`
+* method reads `this.pool` at call time, so all real I/O goes through
+* the lakebase pool from then on. The placeholder pool is `.end()`'d
+* so its socket book-keeping is released.
+*/
+function buildSharedPgVector(pool) {
+	const vector = new PgVector({
+		id: `pg${randomUUID()}`,
+		host: "-1",
+		port: -1,
+		database: "_",
+		user: "_",
+		password: "_"
+	});
+	const placeholder = vector.pool;
+	vector.pool = pool;
+	placeholder.end().catch(() => void 0);
+	return vector;
+}
+/** Per-agent dedicated `PgVector` (rare; opt-in via object override). */
+function buildPgVector(setting) {
+	return new PgVector(withId(setting, `pg-vector__${randomUUID()}`));
+}
+/** True when this setting requires the shared Lakebase pool. */
+function settingNeedsSharedPool(setting) {
+	return setting === true;
+}
+/** Walk the three shapes of `config.agents` into a flat list. */
+function collectAgentDefinitions(config) {
+	const agents = config.agents;
+	if (!agents) return [];
+	if (Array.isArray(agents)) return agents;
+	if (typeof agents.instructions === "string") return [agents];
+	return Object.values(agents);
+}
+/** Fill in a default `id` when the caller didn't supply one. */
+function withId(value, fallback) {
+	return value.id ? value : {
+		...value,
+		id: fallback
+	};
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/observability.ts
+/**
+* Mastra observability wired through the same OTel pipeline AppKit's
+* built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
+*
+* How traces flow:
+*
+* 1. `@databricks/appkit` boots a global `NodeSDK` in
+*    `TelemetryManager.initialize()` (during `createApp`) when
+*    `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the process env.
+* 2. Every AppKit plugin span (e.g. the `agents` plugin's
+*    `executeStream`) is created via the global OTel tracer
+*    (`trace.getTracer(<plugin>)`), so it lands on that NodeSDK and
+*    is shipped through its OTLP exporter.
+* 3. The Mastra `OtelBridge` ALSO creates real OTel spans on the same
+*    global tracer for every Mastra operation (agent runs, model
+*    calls, tool invocations, workflow steps). They inherit the
+*    ambient OTel context, so when Mastra is invoked from inside an
+*    AppKit HTTP span the trace stays connected.
+*
+* Net effect: Mastra spans get exactly the treatment AppKit's
+* `agents` plugin gets. No custom OTLP pipeline lives in this
+* package; the OTLP endpoint, headers, and resource attributes are
+* driven by the standard OTel env vars
+* (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
+* `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, ...) and consumed
+* by AppKit's `TelemetryManager`. Set those once and both AppKit and
+* Mastra spans end up at the same backend.
+*
+* When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the bridge's spans go
+* to the global noop tracer, mirroring how the `agents` plugin
+* silently no-ops in the same situation.
+*/
+const log = logUtils.logger("mastra/observability");
+const DEFAULT_SERVICE_NAME = "mastra";
+/**
+* Build a Mastra `Observability` whose spans ride AppKit's global
+* OTel pipeline via `@mastra/otel-bridge`.
+*
+* Returns `undefined` only if someone explicitly opts out in the
+* future; today it always returns an `Observability` because the
+* bridge degrades gracefully (no-op tracer) when no global OTel SDK
+* is registered. Callers can spread `...(observability ? { observability } : {})`
+* either way to stay forward-compatible.
+*/
+async function buildObservability(options) {
+	const serviceName = options?.serviceName ?? await projectUtils.name() ?? DEFAULT_SERVICE_NAME;
+	const requestContextKeys = [...options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS];
+	const otelBase = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+	const otelTracesOverride = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+	const resolvedTracesUrl = otelTracesOverride ? otelTracesOverride : otelBase ? `${otelBase.replace(/\/+$/, "")}/v1/traces` : void 0;
+	log.info("Mastra observability wired through OTel bridge", {
+		serviceName,
+		requestContextKeys,
+		otelBase: otelBase ?? "<unset>",
+		resolvedTracesUrl: resolvedTracesUrl ?? "<noop; OTLP endpoint unset>"
+	});
+	return new Observability({ configs: { serviceName: {
+		serviceName,
+		bridge: new OtelBridge(),
+		requestContextKeys
+	} } });
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/server.ts
+/**
+* Express-layer plumbing for the Mastra plugin: a `MastraServer` that
+* stamps the per-request `RequestContext`, and a route-patch middleware
+* that lets the plugin's custom API routes (e.g. `historyRoute`) work
+* behind an Express mount point.
+*/
+/**
+* `@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`).
+*/
+var MastraServer$1 = class extends MastraServer {
+	log;
+	constructor(config, ...args) {
+		super(...args);
+		this.config = config;
+		this.log = logUtils.logger(config);
+	}
+	registerAuthMiddleware() {
+		super.registerAuthMiddleware();
+		this.app.use((req, res, next) => {
+			const requestContext = res.locals.requestContext;
+			this.configureRequestContextUser(requestContext);
+			this.configureRequestContextThreadId(req, res, requestContext);
+			this.configureRequestContextModelOverride(req, requestContext);
+			this.configureRequestContextRequestId(req, res, requestContext);
+			this.log.debug("auth:middleware", {
+				method: req.method,
+				path: req.path,
+				requestId: requestContext.get(MASTRA_REQUEST_ID_KEY),
+				threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
+				resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
+				userName: requestContext.get(MASTRA_USER_NAME_KEY),
+				userEmail: requestContext.get(MASTRA_USER_EMAIL_KEY),
+				modelOverride: requestContext.get("mastra__model_override")
+			});
+			next();
+		});
+	}
+	configureRequestContextUser(requestContext) {
+		if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))) return;
+		const executionContext = getExecutionContext();
+		const user = {
+			id: "userId" in executionContext ? executionContext.userId : executionContext.serviceUserId,
+			executionContext
+		};
+		requestContext.set(MASTRA_USER_KEY, user);
+		requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+		if ("isUserContext" in executionContext) {
+			if (executionContext.userName) requestContext.set(MASTRA_USER_NAME_KEY, executionContext.userName);
+			if (executionContext.userEmail) requestContext.set(MASTRA_USER_EMAIL_KEY, executionContext.userEmail);
+		}
+	}
+	/**
+	* 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, res, requestContext) {
+		if (requestContext.get(MASTRA_REQUEST_ID_KEY)) return;
+		const headerValue = req.headers["x-request-id"];
+		const requestId = (Array.isArray(headerValue) ? headerValue[0] : headerValue)?.trim() || randomUUID();
+		requestContext.set(MASTRA_REQUEST_ID_KEY, requestId);
+		res.setHeader("X-Request-Id", requestId);
+	}
+	configureRequestContextThreadId(req, res, requestContext) {
+		if (requestContext.get(MASTRA_THREAD_ID_KEY)) return;
+		const cookies = httpUtils.parseCookies(req.headers.cookie);
+		const cookieName = stringUtils.toIdentifierWithOptions({
+			delimiter: "_",
+			distinct: true
+		}, "appkit", this.config.name, "sessionId");
+		let sessionId = cookies[cookieName];
+		if (!sessionId) {
+			sessionId = randomUUID();
+			res.cookie(cookieName, sessionId, {
+				httpOnly: true,
+				sameSite: "lax",
+				secure: req.secure,
+				path: "/"
+			});
+		}
+		requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
+	}
+	configureRequestContextModelOverride(req, requestContext) {
+		if (resolveServingConfig(this.config).allowOverride) {
+			const override = extractModelOverride({
+				headers: req.headers,
+				query: req.query,
+				body: req.body
+			});
+			if (override) requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
+		}
+	}
+};
+/**
+* Patches around `@mastra/express`'s custom-route dispatcher so the
+* plugin's custom API routes (e.g. `historyRoute`) work when
+* `MastraServer` is hosted on an Express subapp mounted under a parent
+* path (e.g. `/api/mastra`).
+*
+* The adapter's `registerCustomApiRoutes` matches against `req.path`
+* (mount-relative, correct) but dispatches to its internal Hono
+* mini-app using `req.originalUrl`, which still contains the parent
+* mount prefix. The Hono app registers the literal route paths
+* (for example `/route/history`), so the absolute URL never matches
+* until we overwrite `originalUrl` for `/route` and `/route/*` to the
+* mount-relative path.
+*/
+function attachRoutePatchMiddleware(app) {
+	app.use((req, _res, next) => {
+		if (!(req.path === "/route" || req.path.startsWith("/route/"))) return next();
+		req.originalUrl = req.path;
+		next();
+	});
+}
+
+//#endregion
+//#region packages/appkit-mastra/src/plugin.ts
+/**
+* AppKit plugin that builds one or more Mastra `Agent` instances and
+* mounts the `@mastra/express` server. Clients drive the conversation
+* over the standard Mastra agent stream (`@mastra/client-js`'s
+* `getAgent(id).stream()`), so there's no bespoke chat transport to
+* keep in sync.
+*
+* - Agents: registered through `config.agents` at plugin creation
+*   ({@link MastraAgentDefinition}). Each entry's `tools` field accepts
+*   either a plain record or a `(plugins) => tools` callback that gets
+*   a typed sibling-plugin index ({@link MastraPlugins}). Omit
+*   `config.agents` to get a single built-in `default` analyst.
+* - Model: each agent call resolves a `MastraModelConfig` via
+*   {@link buildModel} from `./model.js`. Per-agent `model` overrides
+*   (`AgentConfig["model"]` or a `modelId` string) flow through
+*   {@link buildAgents}.
+* - Memory / storage: per-agent, built by {@link createMemoryBuilder}
+*   from `./memory.js`. Both auto-default to `true` when the
+*   `lakebase` plugin is registered (unless the caller passed
+*   `false` or a custom config). Storage namespaces per agent via
+*   `schemaName: "mastra_<agentId>"`; the vector store is a single
+*   shared singleton across every agent.
+* - Server: the Express subapp wiring lives in `./server.js`.
+* - HTTP: AppKit mounts this plugin under `/api/mastra`. Alongside the
+*   Mastra agent routes, the plugin registers `/route/history`
+*   (load + clear thread history), `/models`, `/suggestions`, and the
+*   generic `/embed/:type/:id` resolver for inline chart / data
+*   markers.
+* - MCP: opt in with `config.mcp` to expose the agents (and optionally
+*   tools) as a Mastra `MCPServer`. It is registered on the `Mastra`
+*   instance via `mcpServers`, so `@mastra/express` serves the stock
+*   MCP transport routes (`/mcp/<serverId>/...`) under the mount. See
+*   `./mcp.js`.
+*/
+const GENIE_MANIFEST = appkitUtils.data(genie).plugin.manifest;
+const LAKEBASE_MANIFEST = appkitUtils.data(lakebase).plugin.manifest;
+/**
+* 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`).
+*/
+var MastraPlugin = class MastraPlugin extends Plugin {
+	static manifest = {
+		name: "mastra",
+		displayName: "Mastra",
+		description: "Builds a Mastra Agent with user-scoped workspace auth (asUser) and optional Postgres-backed Mastra Memory via the `lakebase` plugin.",
+		stability: "beta",
+		resources: {
+			required: [],
+			optional: [...GENIE_MANIFEST.resources.required, ...LAKEBASE_MANIFEST.resources.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) {
+		const resources = [];
+		const enabledManifests = [];
+		if (needsLakebase(config)) enabledManifests.push(LAKEBASE_MANIFEST);
+		for (const m of enabledManifests) for (const resource of m.resources.required) resources.push({
+			...resource,
+			required: true
+		});
+		return resources;
+	}
+	log = logUtils.logger(this);
+	built = null;
+	mastra = null;
+	mastraApp = null;
+	mastraServer = null;
+	/**
+	* 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.
+	*/
+	mcp = null;
+	/**
+	* 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.
+	*/
+	servicePrincipalPool = null;
+	async setup() {
+		this.context?.onLifecycle("setup:complete", async () => {
+			this.applyLakebaseAutoDefaults();
+			this.log.info("setup:complete");
+			await this.buildAgentAndServer();
+		});
+	}
+	/**
+	* 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.
+	*/
+	applyLakebaseAutoDefaults() {
+		if (!(appkitUtils.instance(this.context, lakebase) !== void 0)) return;
+		if (this.config.storage === void 0) this.config.storage = true;
+		if (this.config.memory === void 0) this.config.memory = true;
+	}
+	/**
+	* 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() {
+		super.abortActiveOperations();
+		if (this.servicePrincipalPool) {
+			this.log.info("closing memory SP pool");
+			const pool = this.servicePrincipalPool;
+			this.servicePrincipalPool = null;
+			pool.end().catch((err) => {
+				this.log.error("error closing memory SP pool", { error: commonUtils.errorMessage(err) });
+			});
+		}
+	}
+	exports() {
+		return {
+			list: () => Object.keys(this.built?.agents ?? {}),
+			get: (id) => this.built?.agents[id] ?? null,
+			getDefault: () => (this.built && this.built.agents[this.built.defaultAgentId]) ?? null,
+			getMastra: () => this.mastra,
+			getMcp: () => this.mcp ? {
+				serverId: this.mcp.serverId,
+				http: `/api/${this.name}${this.mcp.httpPath}`,
+				sse: `/api/${this.name}${this.mcp.ssePath}`,
+				messages: `/api/${this.name}${this.mcp.messagePath}`
+			} : null,
+			getMastraServer: () => this.mastraServer,
+			listModels: () => this.listModels(),
+			clearModelsCache: (host) => clearServingEndpointsCache(host)
+		};
+	}
+	clientConfig() {
+		return {
+			basePath: `/api/${this.name}`,
+			defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
+			agents: Object.keys(this.built?.agents ?? {})
+		};
+	}
+	injectRoutes(router) {
+		router.get(MASTRA_ROUTES.models, (req, res, next) => {
+			this.userScopedSelf(req).listModels().then((endpoints) => res.json({ endpoints })).catch(next);
+		});
+		const embedResolvers = {
+			chart: (req, id, signal) => {
+				const timeoutMs = parseTimeoutMs(req.query["timeoutMs"]);
+				return fetchChart(id, {
+					...timeoutMs !== void 0 ? { timeoutMs } : {},
+					signal
+				});
+			},
+			data: (req, id, signal) => {
+				const limit = parseStatementLimit(req.query["limit"]);
+				return this.userScopedSelf(req).fetchStatement(id, {
+					...limit !== void 0 ? { limit } : {},
+					signal
+				});
+			}
+		};
+		router.get(`${MASTRA_ROUTES.embed}/:type/:id`, (req, res, next) => {
+			const type = req.params["type"] ?? "";
+			const id = req.params["id"];
+			const resolve = embedResolvers[type];
+			if (!resolve) {
+				res.status(404).json({ error: `unsupported embed type: ${type}` });
+				return;
+			}
+			if (!id) {
+				res.status(400).json({ error: "id is required" });
+				return;
+			}
+			const controller = new AbortController();
+			req.on("close", () => controller.abort());
+			resolve(req, id, controller.signal).then((entry) => {
+				if (entry === void 0) {
+					res.status(404).json({ error: `${type} not found` });
+					return;
+				}
+				res.json(entry);
+			}).catch(next);
+		});
+		const handleSuggestions = (req, res) => {
+			const controller = new AbortController();
+			req.on("close", () => controller.abort());
+			this.userScopedSelf(req).fetchSuggestions(controller.signal).then((questions) => res.json({ questions })).catch((err) => {
+				this.log.warn("suggestions:error", { error: commonUtils.errorMessage(err) });
+				res.json({ questions: [] });
+			});
+		};
+		router.get(MASTRA_ROUTES.suggestions, handleSuggestions);
+		router.get(`${MASTRA_ROUTES.suggestions}/:agentId`, handleSuggestions);
+		router.use((req, res, next) => {
+			if (!this.mastraApp) return res.status(503).end();
+			return this.userScopedSelf(req).dispatchMastra(req, res, next);
+		});
+	}
+	/**
+	* 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.
+	*/
+	dispatchMastra(req, res, next) {
+		this.mastraApp(req, res, next);
+	}
+	/**
+	* 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.
+	*/
+	async fetchSuggestions(signal) {
+		const spaces = resolveGenieSpaces(this.config, this.context);
+		if (Object.keys(spaces).length === 0) return [];
+		const client = getExecutionContext().client;
+		return collectSpaceSuggestions({
+			spaces,
+			client,
+			...signal ? { signal } : {}
+		});
+	}
+	/**
+	* 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.
+	*/
+	async fetchStatement(statementId, options = {}) {
+		const client = getExecutionContext().client;
+		const limit = Math.min(options.limit ?? STATEMENT_ROW_CAP, STATEMENT_ROW_CAP);
+		try {
+			const data = await fetchStatementData(client, statementId, {
+				limit,
+				...options.signal ? { signal: options.signal } : {}
+			});
+			return {
+				columns: data.columns,
+				rows: data.rows,
+				rowCount: data.rowCount,
+				truncated: data.rows.length < data.rowCount
+			};
+		} catch (err) {
+			if (apiUtils.isNotFoundError(err)) return void 0;
+			throw err;
+		}
+	}
+	/**
+	* 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).
+	*/
+	userScopedSelf(req) {
+		return req.header("x-forwarded-access-token") ? this.asUser(req) : this;
+	}
+	/**
+	* Implementation backing both the `/models` route and the
+	* `listModels` export. Runs inside the AppKit user-context proxy so
+	* `getExecutionContext()` returns the OBO-scoped client.
+	*/
+	async listModels() {
+		const client = getExecutionContext().client;
+		return listServingEndpoints(client, (await client.config.getHost()).toString(), { ttlMs: resolveServingConfig(this.config).ttlMs });
+	}
+	async buildAgentAndServer() {
+		if (needsLakebase(this.config)) this.servicePrincipalPool = await createServicePrincipalPool(appkitUtils.require(this.context, lakebase, this.config).exports().getPgConfig());
+		const memoryBuilder = this.servicePrincipalPool ? createMemoryBuilder(this.config, this.servicePrincipalPool) : void 0;
+		this.log.debug("build:start", {
+			lakebase: memoryBuilder !== void 0,
+			stripStaleCharts: this.config.stripStaleCharts !== false
+		});
+		this.built = await buildAgents({
+			config: this.config,
+			context: this.context,
+			memoryBuilder,
+			log: this.log
+		});
+		const instanceStorage = memoryBuilder?.instanceStorage();
+		const observability = await buildObservability({ serviceName: this.name });
+		this.mcp = buildMcpServer({
+			config: this.config,
+			pluginName: this.name,
+			displayName: MastraPlugin.manifest.displayName,
+			agents: this.built.agents,
+			ambientTools: this.built.ambientTools
+		});
+		this.mastra = new Mastra({
+			agents: this.built.agents,
+			...instanceStorage ? { storage: instanceStorage } : {},
+			...observability ? { observability } : {},
+			...this.mcp ? { mcpServers: { [this.mcp.serverId]: this.mcp.server } } : {}
+		});
+		this.mastraApp = express();
+		attachRoutePatchMiddleware(this.mastraApp);
+		this.mastraServer = new MastraServer$1(this.config, {
+			app: this.mastraApp,
+			mastra: this.mastra,
+			prefix: "",
+			customApiRoutes: [...historyRoute({
+				path: MASTRA_ROUTES.history,
+				agent: this.built.defaultAgentId
+			}), ...historyRoute({ path: `${MASTRA_ROUTES.history}/:agentId` })]
+		});
+		await this.mastraServer.init();
+		this.log.debug("build:done", {
+			agents: Object.keys(this.built.agents),
+			defaultAgent: this.built.defaultAgentId,
+			routes: [
+				"/route/history",
+				"/models",
+				"/suggestions",
+				"/embed/:type/:id"
+			],
+			instanceStorage: instanceStorage !== void 0,
+			observability: observability !== void 0 ? "mlflow" : "off",
+			mcp: this.mcp ? `/api/${this.name}${this.mcp.httpPath}` : "off"
+		});
+	}
+};
+/**
+* Parse the optional `?timeoutMs=<n>` query parameter from a
+* `GET /embed/chart/:id` request. Accepts a positive integer up
+* to 5 minutes (clamped) and rejects everything else as
+* `undefined` so {@link fetchChart} falls back to its default.
+* Express produces `string | string[] | undefined`; we normalize
+* to the first scalar before parsing.
+*/
+function parseTimeoutMs(raw) {
+	const v = Array.isArray(raw) ? raw[0] : raw;
+	if (typeof v !== "string") return void 0;
+	const n = Number(v);
+	if (!Number.isFinite(n) || n <= 0) return void 0;
+	return Math.min(Math.floor(n), 5 * 6e4);
+}
+/**
+* Parse the optional `?limit=<n>` query parameter from a
+* `GET /embed/data/:id` request. Accepts a non-negative
+* integer and lets the route clamp to `STATEMENT_ROW_CAP`;
+* rejects anything else as `undefined` so the route falls back
+* to the server-side cap.
+*/
+function parseStatementLimit(raw) {
+	const v = Array.isArray(raw) ? raw[0] : raw;
+	if (typeof v !== "string") return void 0;
+	const n = Number(v);
+	if (!Number.isFinite(n) || n < 0) return void 0;
+	return Math.floor(n);
+}
+const mastra = toPlugin(MastraPlugin);
+
+//#endregion
+export { DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, GENIE_INSTRUCTIONS, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraPlugin, TRACE_REQUEST_CONTEXT_KEYS, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, tool };