@dbx-tools/appkit-mastra 0.1.0

package/src/agents.ts

@@ -0,0 +1,675 @@
+/**
+ * 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
+ * `chatRoute` agent for demos.
+ */
+
+import { genie } from "@databricks/appkit";
+import { logUtils, pluginUtils, stringUtils } from "@dbx-tools/appkit-shared";
+import { Agent } from "@mastra/core/agent";
+import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import type { Tool } from "@mastra/core/tools";
+import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
+
+import type { MastraPluginConfig } from "./config.js";
+import { buildGenieProvider } from "./genie.js";
+import type { MemoryBuilder } from "./memory.js";
+import { buildModel } from "./model.js";
+
+/**
+ * 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 stringUtils.toUniqueSlug}: slug + always-on
+ * SHA-1 suffix so two tools with the same leading words don't
+ * collide in traces. Stable across runs.
+ */
+function deriveToolId(description: string): string {
+  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.
+ */
+export function createAgent<T extends MastraAgentDefinition>(def: T): T {
+  return def;
+}
+
+/**
+ * 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>;
+
+/**
+ * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
+ * plugin uses for `AgentDefinition`. The registry key under
+ * `config.agents` is what `chatRoute` matches on; `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 `schemaName: "mastra_<agentId>"` so threads and
+   *   messages stay isolated between agents in the same database.
+   * - `false`: disable storage for this agent only (purely in-memory).
+   * - `true`: enable with the per-agent default schema.
+   * - {@link MastraStorageConfigOverride} object: dedicated
+   *   `PostgresStore` config (custom schema, connection, etc.).
+   */
+  storage?: boolean | MastraStorageConfigOverride;
+}
+
+/**
+ * Distributive `Omit` so unions in `PostgresStoreConfig` /
+ * `PgVectorConfig` keep their discriminants after the override types
+ * strip `id`. The built-in `Omit` collapses unions to one shape with
+ * common fields only, which loses the connection-style discriminants.
+ */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
+/**
+ * `PostgresStoreConfig` minus `id` - per-agent overrides accept any
+ * Mastra-supported storage shape. `id` is filled in automatically
+ * from the agent registry key so traces stay stable.
+ */
+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;
+}
+
+/** Fallback agent id used when `config.agents` is omitted entirely. */
+export const FALLBACK_AGENT_ID = "default";
+
+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:
+
+- Plain prose. Use hyphens (-) only. Never use em dashes (—) or en dashes (–).
+- Never use emojis.
+- Skip openers like "Great question", "Absolutely", "I'd be happy to help".
+- Skip closers like "Let me know if you have any questions".
+- Skip self-disclaimers ("I should mention", "It's important to note").
+- Answer directly. No preamble before the actual answer.
+- Use lists and headers only when they clarify a multi-part answer; not for short replies.
+- Quote numbers, code, identifiers, and tool output verbatim. Never paraphrase them.`;
+
+/**
+ * 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}`;
+}
+
+/**
+ * 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: pluginUtils.PluginContextLike | undefined;
+  memoryBuilder?: MemoryBuilder;
+  log: logUtils.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(context);
+  const ambientTools = config.tools ?? {};
+  const style = resolveStyleInstructions(config);
+  const agents: Record<string, Agent> = {};
+
+  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 !== undefined ? { description: def.description } : {}),
+      instructions: composeInstructions(def.instructions, style),
+      model: resolveModel(config, def.model),
+      tools,
+      ...(memory ? { memory } : {}),
+    });
+  }
+
+  if (!agents[defaultAgentId]) {
+    throw new Error(
+      `mastra: defaultAgent "${defaultAgentId}" not found in registered agents (${ids.join(", ") || "none"})`,
+    );
+  }
+
+  log.info("agents registered", { ids, defaultAgentId });
+  return { agents, defaultAgentId };
+}
+
+/**
+ * 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 = stringUtils.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 };
+}
+
+/**
+ * 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(
+  context: pluginUtils.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(context, propName);
+      cache.set(propName, provider);
+      return provider ?? undefined;
+    },
+  });
+}
+
+/**
+ * Pick the right {@link MastraPluginToolkitProvider} for a sibling
+ * plugin lookup. Returns the streaming-aware Genie adapter when the
+ * caller asks for `genie`; falls back to the generic AppKit
+ * `ToolProvider` adapter for every other plugin name.
+ */
+function resolveProvider(
+  context: pluginUtils.PluginContextLike | undefined,
+  propName: string,
+): MastraPluginToolkitProvider | null {
+  if (propName === "genie") {
+    const geniePlugin = pluginUtils.instance(context, genie);
+    if (!geniePlugin) return null;
+    return buildGenieProvider(geniePlugin) 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);
+    },
+  });
+}