@dbx-tools/appkit-mastra 0.1.112 → 0.3.1

package/src/agents.ts

@@ -0,0 +1,858 @@
+/**
+ * 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.
+ */
+
+import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
+import { Agent } from "@mastra/core/agent";
+import type { Tool } from "@mastra/core/tools";
+import { createTool } from "@mastra/core/tools";
+import type { Workspace } from "@mastra/core/workspace";
+import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
+
+import { buildRenderDataTool } from "./chart";
+import type { MastraPluginConfig } from "./config";
+import { buildGenieToolkitProvider, resolveGenieSpaces } from "./genie";
+import type { MemoryBuilder } from "./memory";
+import { buildModel } from "./model";
+import { fallback } from "@dbx-tools/model";
+import { ResultProcessor, stripStaleChartsProcessor } from "./processors";
+import { buildSummarizeTool } from "./summarize";
+import { createWorkspace } from "./workspaces";
+import { log, object, string } from "@dbx-tools/shared-core";
+import { plugin } from "@dbx-tools/appkit";
+
+/**
+ * Tool record accepted by every Mastra `Agent.tools` field and by the
+ * `tools(plugins)` callback on {@link MastraAgentDefinition}.
+ *
+ * Alias of Mastra's `ToolsInput`, so it already accepts:
+ *
+ * - Mastra tools built with {@link createTool} (or `new Tool(...)`)
+ * - Mastra tools built with the AppKit-shaped {@link tool} wrapper
+ *   below
+ * - Vercel AI SDK tools (`tool({ ... })` from `ai`)
+ * - Provider-defined tools (e.g. `openai.tools.webSearch(...)`)
+ *
+ * Existing tool libraries drop in as-is - nothing in this package
+ * forces a rebuild.
+ */
+export type MastraTools = ToolsInput;
+
+/** Re-export of Mastra's native `createTool` for full-feature access. */
+export { createTool } from "@mastra/core/tools";
+
+/**
+ * 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.).
+ */
+export function tool(opts: AppKitToolOptions): Tool {
+  const id = opts.id ?? deriveToolId(opts.description);
+  return createTool({
+    id,
+    description: opts.description,
+    ...(opts.schema ? { inputSchema: opts.schema as never } : {}),
+    execute: opts.execute as never,
+  });
+}
+
+/**
+ * Input shape for the AppKit-style {@link tool} factory. A trimmed
+ * subset of Mastra's `createTool` options that mirrors the
+ * `@databricks/appkit/beta` `tool({ description, schema, execute })`
+ * signature.
+ *
+ * Generics are intentionally absent - inference flows through the
+ * caller's `schema` (typically a Zod object), and the `execute` body
+ * destructures naturally from that. Reach for {@link createTool} when
+ * you need the fully-typed input/output schemas wired explicitly.
+ */
+export interface AppKitToolOptions {
+  /** Optional stable identifier; auto-derived from `description` when omitted. */
+  id?: string;
+  /** Human-readable description shown to the model. Required. */
+  description: string;
+  /**
+   * Optional input schema (any Standard Schema instance, e.g. Zod).
+   * Maps to Mastra's `inputSchema`; passed through to the model
+   * verbatim.
+   */
+  schema?: unknown;
+  /**
+   * Execute body. First arg is the parsed input (typed off `schema`
+   * when supplied), second arg is the full Mastra execution context
+   * (request context, abort signal, mastra instance) if you need it.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  execute: (input: any, context?: unknown) => unknown;
+}
+
+/**
+ * Build a deterministic Mastra tool id from a description.
+ * Delegates to {@link string.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: string): string {
+  return string.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.
+ */
+export function createAgent<T extends MastraAgentDefinition>(def: T): T {
+  const workspace = def.workspace ?? createWorkspace();
+  return { ...def, workspace };
+}
+
+/**
+ * Filter / rename options accepted by every plugin's `.toolkit()`
+ * method. Mirrors AppKit's `ToolkitOptions` verbatim so options pass
+ * through unchanged - the underlying AppKit plugin does the filtering
+ * and we just adapt the resulting entries into Mastra tools.
+ */
+export interface ToolkitOptions {
+  /**
+   * Key prefix prepended to every tool name. AppKit's default is
+   * `${pluginName}.` when omitted; pass an explicit `""` to drop it.
+   */
+  prefix?: string;
+  /** Allowlist of local tool names. */
+  only?: string[];
+  /** Denylist of local tool names. */
+  except?: string[];
+  /** Remap specific local names to different keys. */
+  rename?: Record<string, string>;
+}
+
+/**
+ * Toolkit provider shape every entry in the {@link MastraPlugins} map
+ * exposes. Identical to AppKit's `PluginToolkitProvider` - any AppKit
+ * plugin that implements the standard `ToolProvider` interface
+ * (`getAgentTools` + `executeAgentTool` + `toolkit`) is reachable
+ * through this surface automatically.
+ */
+export interface MastraPluginToolkitProvider {
+  /**
+   * Returns a Mastra-shaped tools record adapted from the plugin's
+   * agent tools. Each tool dispatches back through the plugin's
+   * `executeAgentTool` so OBO auth and telemetry spans stay intact.
+   */
+  toolkit(opts?: ToolkitOptions): MastraTools;
+}
+
+/**
+ * Plugin map handed to the function form of
+ * {@link MastraAgentDefinition.tools}. Mirrors AppKit's `Plugins`
+ * type exactly: a string-keyed record where every value exposes
+ * `.toolkit(opts)`.
+ *
+ * Implemented as a runtime Proxy that auto-discovers any registered
+ * AppKit plugin implementing the standard `ToolProvider` interface
+ * (`analytics`, `files`, `lakebase`, `genie`, plus any third-party
+ * plugin that does the same). Unknown names resolve to `undefined`
+ * at runtime, so guard with `?.` and `?? {}` when spreading from a
+ * plugin that may not be registered in every environment.
+ *
+ * @example
+ * ```ts
+ * createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       ...plugins.analytics.toolkit(),
+ *       ...plugins.files.toolkit({ only: ["uploads.read"] }),
+ *       get_weather: tool({
+ *         description: "Weather",
+ *         schema: z.object({ city: z.string() }),
+ *         execute: async ({ city }) => `Sunny in ${city}`,
+ *       }),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export type MastraPlugins = Record<string, MastraPluginToolkitProvider>;
+
+/** Function form of {@link MastraAgentDefinition.tools}. */
+export type MastraToolsFn = (plugins: MastraPlugins) => MastraTools | Promise<MastraTools>;
+
+/** Function form of {@link MastraAgentDefinition.workspace}. */
+export type MastraAgentWorkspaceResolver = () => Workspace | undefined;
+
+/**
+ * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
+ * plugin uses for `AgentDefinition`. The registry key under
+ * `config.agents` is the `agentId` the client streams against; `name`
+ * is purely informational (defaults to the key).
+ */
+export interface MastraAgentDefinition {
+  /** Display name used as `Agent.name`. Defaults to the registry key. */
+  name?: string;
+  /** Optional long-form description; surfaced as `Agent.description`. */
+  description?: string;
+  /** System prompt body. */
+  instructions: string;
+  /**
+   * Per-agent model override.
+   *
+   * - `undefined` (default): falls back to the workspace
+   *   `/serving-endpoints` resolver that {@link buildModel} configures
+   *   from the per-request `WorkspaceClient`.
+   * - `string`: shorthand for "use the default resolver but swap the
+   *   `modelId`" (e.g. `"databricks-meta-llama-3-3-70b-instruct"`).
+   * - Any other Mastra `DynamicArgument<MastraModelConfig>`: passed
+   *   straight through to `Agent.model`. Use this when you need full
+   *   control over auth or providerId.
+   */
+  model?: AgentConfig["model"] | string;
+  /**
+   * Per-agent tool record. Either a plain map or a callback that
+   * receives the typed {@link MastraPlugins} sibling-plugin index and
+   * returns a map. The callback runs exactly once at agent setup; the
+   * result is cached for the agent's lifetime.
+   */
+  tools?: MastraTools | MastraToolsFn;
+  /**
+   * Per-agent semantic recall (PgVector) override. Cascades from
+   * `config.memory`; the agent value wins when set.
+   *
+   * - `undefined` (default): inherit `config.memory`. When that's
+   *   enabled, the agent **shares the plugin-level singleton `PgVector`
+   *   instance** (cross-agent semantic recall across the same index).
+   * - `false`: disable semantic recall for this agent only.
+   * - `true`: enable using the shared singleton (same as default when
+   *   plugin memory is enabled; useful to opt in when plugin disabled).
+   * - {@link MastraMemoryConfig} object: dedicated `PgVector` for this
+   *   agent (private recall index). Bypasses the shared singleton.
+   */
+  memory?: boolean | MastraMemoryConfigOverride;
+  /**
+   * Per-agent thread/message storage (`PostgresStore`) override.
+   * Cascades from `config.storage`; the agent value wins when set.
+   *
+   * - `undefined` (default): inherit `config.storage`. When that's
+   *   enabled, the agent gets its **own per-agent `PostgresStore`**
+   *   keyed by {@link agentStorageSchemaName} so threads and
+   *   messages stay isolated between agents in the same database.
+   * - `false`: disable storage for this agent only (purely in-memory).
+   * - `true`: enable with the per-agent default schema.
+   * - {@link MastraStorageConfigOverride} object: dedicated
+   *   `PostgresStore` config (custom schema, connection, etc.).
+   */
+  storage?: boolean | MastraStorageConfigOverride;
+  /**
+   * Mastra {@link Workspace} for this agent (filesystem, sandbox, or other
+   * providers). Assistant skills from Databricks workspace paths are wired
+   * via {@link createWorkspace}.
+   */
+  workspace?: Workspace | MastraAgentWorkspaceResolver;
+}
+
+/**
+ * Distributive `Omit` so unions in `PostgresStoreConfig` /
+ * `PgVectorConfig` keep their discriminants after the override types
+ * strip `id`. The built-in `Omit` collapses unions to one shape with
+ * common fields only, which loses the connection-style discriminants.
+ */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+
+/**
+ * `PostgresStoreConfig` minus `id` - per-agent overrides accept any
+ * Mastra-supported storage shape. `id` is filled in automatically
+ * from the agent registry key so traces stay stable.
+ */
+export type MastraStorageConfigOverride = DistributiveOmit<PostgresStoreConfig, "id"> & {
+  id?: string;
+};
+
+/**
+ * `PgVectorConfig` minus `id` - per-agent overrides accept any
+ * Mastra-supported vector shape. `id` is filled in automatically
+ * from the agent registry key.
+ */
+export type MastraMemoryConfigOverride = DistributiveOmit<PgVectorConfig, "id"> & {
+  id?: string;
+};
+
+/** Output of {@link buildAgents}: resolved agents plus the default id. */
+export interface BuiltAgents {
+  agents: Record<string, Agent>;
+  defaultAgentId: string;
+  /**
+   * Ambient tools shared across every agent (the built-in system tools
+   * spread with `config.tools`). Surfaced so the optional MCP server
+   * can re-expose them when {@link MastraMcpConfig.tools} is enabled.
+   */
+  ambientTools: MastraTools;
+}
+
+/** Fallback agent id used when `config.agents` is omitted entirely. */
+export 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.
+ */
+export 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).
+ */
+export 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: MastraPluginConfig): string | null {
+  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: string, style: string | null): string {
+  if (!style) return agentInstructions;
+  return `${agentInstructions.trimEnd()}\n\n${style}`;
+}
+
+/**
+ * Generated description for an agent whose definition omits one. Kept
+ * generic (the agent's own name is the only reliable signal at build
+ * time) so it reads sensibly as the `ask_<id>` MCP tool's description
+ * and in agent metadata.
+ */
+function defaultAgentDescription(name: string): string {
+  return `Conversational AI agent "${name}".`;
+}
+
+/**
+ * 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.
+ */
+export async function buildAgents(opts: {
+  config: MastraPluginConfig;
+  context: plugin.PluginContextLike | undefined;
+  memoryBuilder?: MemoryBuilder;
+  log: log.Logger;
+}): Promise<BuiltAgents> {
+  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);
+  // System-default ambient tools every agent gets out of the box:
+  // `render_data` for inline visualizations and `summarize` for
+  // offloading text condensing to the fast / small chat tier. The
+  // user can shadow either by including a same-named tool in their own
+  // `config.tools` or per-agent `tools`. Order in {@link resolveTools}
+  // is `system -> user-ambient -> per-agent`, last write wins.
+  const systemTools: MastraTools = {
+    render_data: buildRenderDataTool(config),
+    summarize: buildSummarizeTool(config),
+  };
+  const ambientTools = {
+    ...systemTools,
+    ...(config.tools ?? {}),
+  };
+  const style = resolveStyleInstructions(config);
+  // Default-on protection against the model copying turn-scoped
+  // chartIds from prior assistant tool results into the new
+  // turn's `[chart:<id>]` markers. Opt out per-plugin via
+  // `config.stripStaleCharts: false`.
+  const outputProcessors = [new ResultProcessor()];
+  const inputProcessors = [
+    ...(config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor]),
+  ];
+  const agents: Record<string, Agent> = {};
+  const approvalGatedByAgent: Array<{ agentId: string; toolIds: string[] }> = [];
+
+  for (const [id, def] of Object.entries(definitions)) {
+    const tools = await resolveTools(def.tools, plugins, ambientTools);
+    const workspace = resolveAgentWorkspace(def.workspace);
+    const gated = approvalGatedToolIds(tools);
+    if (gated.length > 0) approvalGatedByAgent.push({ agentId: id, toolIds: gated });
+    const memory = memoryBuilder?.forAgent(id, def);
+    agents[id] = new Agent({
+      id,
+      name: def.name ?? id,
+      // Always carry a non-empty description: it's surfaced to MCP
+      // clients (which reject a description-less agent) and in agent
+      // metadata. Fall back to a generated one when the definition
+      // omits it.
+      description: def.description?.trim() || defaultAgentDescription(def.name ?? id),
+      instructions: composeInstructions(def.instructions, style),
+      model: resolveModel(config, def.model),
+      defaultOptions: {
+        maxSteps: config.agentMaxSteps ?? DEFAULT_AGENT_MAX_STEPS,
+      },
+      tools,
+      ...(memory ? { memory } : {}),
+      ...(workspace ? { workspace } : {}),
+      inputProcessors,
+      outputProcessors,
+    });
+    // Surface the effective default model per agent so operators can
+    // see at a glance which endpoint each agent points at without
+    // having to fire a request and inspect a trace. The value is the
+    // *static* default; per-request overrides (header / query /
+    // body) and the workspace-catalogue fuzzy match still apply at
+    // call time.
+    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"})`,
+    );
+  }
+
+  assertApprovalGatedToolsHaveStorage(approvalGatedByAgent, memoryBuilder);
+
+  log.info("agents ready", { ids, defaultAgentId });
+  return { agents, defaultAgentId, ambientTools };
+}
+
+/**
+ * Tool ids on `tools` that are approval-gated (`requireApproval: true`).
+ * Keys are used as a fallback when a tool omits an explicit `id`.
+ */
+export function approvalGatedToolIds(tools: MastraTools): string[] {
+  if (!tools || typeof tools !== "object") return [];
+  return [
+    ...object
+      .sequence(Object.entries(tools))
+      .filter(([, tool]) => isApprovalGatedTool(tool))
+      .map(([key, tool]) => resolveToolId(tool, key)),
+  ];
+}
+
+/** True when a Mastra / AI SDK tool pauses for human approval before execute. */
+function isApprovalGatedTool(tool: unknown): boolean {
+  if (!tool || typeof tool !== "object") return false;
+  return (tool as { requireApproval?: boolean }).requireApproval === true;
+}
+
+function resolveToolId(tool: unknown, fallbackKey: string): string {
+  if (tool && typeof tool === "object" && typeof (tool as { id?: string }).id === "string") {
+    return (tool as { id: string }).id;
+  }
+  return fallbackKey;
+}
+
+/**
+ * Approval-gated tools suspend the agent loop until a human approves.
+ * Mastra persists those suspended runs in Mastra-instance-level storage
+ * (`memoryBuilder.instanceStorage()`), not per-agent memory - so boot
+ * must fail fast when such a tool is registered without storage.
+ */
+function assertApprovalGatedToolsHaveStorage(
+  gated: Array<{ agentId: string; toolIds: string[] }>,
+  memoryBuilder: MemoryBuilder | undefined,
+): void {
+  if (gated.length === 0) return;
+  if (memoryBuilder?.instanceStorage()) return;
+
+  const detail = gated
+    .map(({ agentId, toolIds }) => `${agentId}: ${toolIds.join(", ")}`)
+    .join("; ");
+  throw new Error(
+    "mastra: approval-gated tools require plugin storage (PostgresStore) to persist suspended runs. " +
+      `Affected agents/tools: ${detail}. ` +
+      "Register lakebase() before mastra() so storage auto-enables, or pass storage: true explicitly.",
+  );
+}
+
+/**
+ * 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.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: MastraPluginConfig, def: MastraAgentDefinition): string {
+  const effective = def.model ?? config.defaultModel;
+  if (typeof effective === "string") return effective;
+  if (effective !== undefined) return "<dynamic>";
+  return (
+    process.env.DATABRICKS_SERVING_ENDPOINT_NAME ??
+    config.defaultModelFallbacks?.[0] ??
+    fallback.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: MastraPluginConfig): Record<string, MastraAgentDefinition> {
+  const input = config.agents;
+  if (!input) return fallbackDefinitions();
+
+  if (Array.isArray(input)) {
+    if (input.length === 0) return fallbackDefinitions();
+    const out: Record<string, MastraAgentDefinition> = {};
+    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;
+  }
+
+  // Single-definition shorthand: an agent always has `instructions: string`,
+  // a record-of-agents never has that field directly.
+  if (typeof (input as MastraAgentDefinition).instructions === "string") {
+    const def = input as MastraAgentDefinition;
+    const key = deriveAgentKey(def);
+    return { [key]: def };
+  }
+
+  const record = input as Record<string, MastraAgentDefinition>;
+  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: MastraAgentDefinition, index?: number): string {
+  if (def.name) {
+    const slug = string.toIdentifier(def.name);
+    if (slug) return slug;
+  }
+  return index === undefined ? FALLBACK_AGENT_ID : `agent_${index}`;
+}
+
+/** Built-in fallback registry used when `agents` is omitted / empty. */
+function fallbackDefinitions(): Record<string, MastraAgentDefinition> {
+  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: MastraPluginConfig,
+  override: MastraAgentDefinition["model"],
+): AgentConfig["model"] {
+  const effective = override ?? config.defaultModel;
+  if (effective === undefined) {
+    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: MastraAgentDefinition["tools"],
+  plugins: MastraPlugins,
+  ambientTools: MastraTools,
+): Promise<MastraTools> {
+  if (!defTools) return { ...ambientTools };
+  const resolved = typeof defTools === "function" ? await defTools(plugins) : defTools;
+  return { ...ambientTools, ...resolved };
+}
+
+function resolveAgentWorkspace(
+  workspace: MastraAgentDefinition["workspace"],
+): Workspace | undefined {
+  if (!workspace) return undefined;
+  return typeof workspace === "function" ? workspace() : workspace;
+}
+
+/**
+ * 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: MastraPluginConfig,
+  context: plugin.PluginContextLike | undefined,
+): MastraPlugins {
+  const cache = new Map<string, MastraPluginToolkitProvider | null>();
+  return new Proxy({} as MastraPlugins, {
+    get(_target, propName) {
+      if (typeof propName !== "string") return undefined;
+      if (cache.has(propName)) return cache.get(propName) ?? undefined;
+      const provider = resolveProvider(config, context, propName);
+      cache.set(propName, provider);
+      return provider ?? undefined;
+    },
+  });
+}
+
+/**
+ * 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: MastraPluginConfig,
+  context: plugin.PluginContextLike | undefined,
+  propName: string,
+): MastraPluginToolkitProvider | null {
+  if (propName === "genie") {
+    const spaces = resolveGenieSpaces(config, context);
+    if (Object.keys(spaces).length === 0) return null;
+    return buildGenieToolkitProvider({
+      spaces,
+      config,
+    }) as MastraPluginToolkitProvider;
+  }
+  const plugin = context?.getPlugins().get(propName);
+  return adaptPluginToolkit(plugin);
+}
+
+/**
+ * AppKit `ToolProvider` shape we duck-type against any registered
+ * plugin. Defined structurally to avoid coupling to AppKit's internal
+ * type module layout.
+ */
+interface AppKitToolkitProvider {
+  toolkit?: (opts?: ToolkitOptions) => Record<string, AppKitToolkitEntry>;
+  executeAgentTool?: (name: string, args: unknown, signal?: AbortSignal) => Promise<unknown>;
+}
+
+/** Single entry returned by an AppKit plugin's `.toolkit(opts)` call. */
+interface AppKitToolkitEntry {
+  pluginName: string;
+  localName: string;
+  def: {
+    name: string;
+    description: string;
+    parameters: unknown;
+  };
+}
+
+/**
+ * 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: unknown): MastraPluginToolkitProvider | null {
+  if (!plugin || typeof plugin !== "object") return null;
+  const p = plugin as AppKitToolkitProvider;
+  if (typeof p.toolkit !== "function" || typeof p.executeAgentTool !== "function") {
+    return null;
+  }
+  return {
+    toolkit(opts?: ToolkitOptions): MastraTools {
+      const entries = p.toolkit!(opts);
+      const tools: MastraTools = {};
+      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: AppKitToolkitEntry, plugin: AppKitToolkitProvider): Tool {
+  return createTool({
+    id: `${entry.pluginName}__${entry.localName}`,
+    description: entry.def.description,
+    ...(entry.def.parameters ? { inputSchema: entry.def.parameters as never } : {}),
+    execute: async (input: unknown, context: unknown) => {
+      const signal = (context as { abortSignal?: AbortSignal } | undefined)?.abortSignal;
+      return plugin.executeAgentTool!(entry.localName, input, signal);
+    },
+  });
+}