@dbx-tools/appkit-mastra 0.1.13 → 0.1.14

package/dist/src/agents.js

@@ -1,403 +0,0 @@
-/**
- * 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 { createTool } from "@mastra/core/tools";
-import { buildRenderDataTool } from "./chart.js";
-import { buildGenieProvider } from "./genie.js";
-import { buildModel } from "./model.js";
-import { stripStaleChartsProcessor } from "./processors/strip-stale-charts.js";
-/** 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) {
-    const id = opts.id ?? deriveToolId(opts.description);
-    return createTool({
-        id,
-        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.
- */
-export function createAgent(def) {
-    return def;
-}
-/** 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:",
-    "",
-    "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.
- */
-export 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);
-    // System-default ambient tools every agent gets out of the box.
-    // Currently just `render_data` for inline visualizations; the
-    // user can shadow it 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 = {
-        render_data: buildRenderDataTool(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 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 !== undefined ? { description: def.description } : {}),
-            instructions: composeInstructions(def.instructions, style),
-            model: resolveModel(config, def.model),
-            tools,
-            ...(memory ? { memory } : {}),
-            ...(inputProcessors.length > 0 ? { inputProcessors } : {}),
-        });
-    }
-    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) {
-    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;
-    }
-    // Single-definition shorthand: an agent always has `instructions: string`,
-    // a record-of-agents never has that field directly.
-    if (typeof input.instructions === "string") {
-        const def = input;
-        const key = deriveAgentKey(def);
-        return { [key]: 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 === undefined ? 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 === 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, 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 = new Map();
-    return new Proxy({}, {
-        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 streaming-aware Genie adapter when the
- * caller asks for `genie`; falls back to the generic AppKit
- * `ToolProvider` adapter for every other plugin name. `config` is
- * threaded through so Genie's tool can run the chart planner
- * inline against the same model resolver / fallback ladder the
- * agents use.
- */
-function resolveProvider(config, context, propName) {
-    if (propName === "genie") {
-        const geniePlugin = pluginUtils.instance(context, genie);
-        if (!geniePlugin)
-            return null;
-        return buildGenieProvider(geniePlugin, { 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({
-        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);
-        },
-    });
-}

package/dist/src/chart.d.ts

@@ -1,170 +0,0 @@
-/**
- * Chart-rendering primitives.
- *
- * Three surfaces, one shared brain:
- *
- * - {@link buildRenderDataTool}: a Mastra tool the model calls
- *   ("here is a dataset, render it as a chart"). The tool's
- *   `execute` emits a `kind: "chart"` event with the raw rows to
- *   `ctx.writer` synchronously, kicks off the chart-planner agent,
- *   and `await`s the planner promise before returning so the
- *   planner's latency is attributed to this tool's trace span.
- *   The LLM-bound output is just `{ chartId }`, so its context
- *   stays flat regardless of dataset size.
- *
- * - {@link emitChartWithPlanning}: the underlying helper that both
- *   `render_data` and Genie's `drainGenieStream` call. Mints the
- *   `chartId`, fires the dataset event immediately, runs the
- *   planner in the background, and returns `{ chartId,
- *   plannerPromise }` so callers can choose to await for trace
- *   shape or fire-and-forget.
- *
- * - {@link runChartPlanner}: the chart-planner Agent + ECOption
- *   expansion as a plain async function. Used internally by
- *   {@link emitChartWithPlanning}; producers shouldn't reach for
- *   it directly so chart events keep a single wire-format
- *   contract.
- *
- * The model wires the chart into its reply by emitting the marker
- * `[[chart:<chartId>]]` on its own line in markdown. The chat
- * client splits the assistant text on these markers and drops a
- * `<ChartSlot>` in at the position the model placed it; the slot
- * shows a skeleton until the second `kind: "chart"` event (with
- * the resolved `EChartsOption`) arrives, then swaps in the
- * rendered Echarts visualisation.
- */
-import type { RequestContext } from "@mastra/core/request-context";
-import { z } from "zod";
-import type { MastraPluginConfig } from "./config.js";
-/**
- * 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.
- */
-declare const chartPlanSchema: z.ZodObject<{
-    chartType: z.ZodEnum<{
-        bar: "bar";
-        line: "line";
-        area: "area";
-        scatter: "scatter";
-        pie: "pie";
-    }>;
-    title: z.ZodOptional<z.ZodString>;
-    xAxisLabel: z.ZodOptional<z.ZodString>;
-    yAxisLabel: z.ZodOptional<z.ZodString>;
-    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    series: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        data: z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
-            name: z.ZodString;
-            value: z.ZodNumber;
-        }, z.core.$strip>]>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type ChartPlan = z.infer<typeof chartPlanSchema>;
-/** Inputs to {@link runChartPlanner}. */
-export interface RunChartPlannerOptions {
-    config: MastraPluginConfig;
-    requestContext?: RequestContext;
-    title: string;
-    description?: string;
-    data: ReadonlyArray<Record<string, unknown>>;
-}
-/** Output of {@link runChartPlanner}: a fully-formed Echarts spec. */
-export interface RunChartPlannerResult {
-    option: Record<string, unknown>;
-    chartType: ChartPlan["chartType"];
-}
-/**
- * Run the chart planner against the given dataset and return a
- * full Echarts `EChartsOption` JSON. Used by
- * {@link emitChartWithPlanning}; tools and producers shouldn't
- * call this directly (use the helper instead so chart events
- * follow the same wire-format contract everywhere).
- */
-export declare function runChartPlanner(opts: RunChartPlannerOptions): Promise<RunChartPlannerResult>;
-/**
- * Minimal `ToolStream`-shaped writer surface. Defined locally so
- * helpers can take any object with a `.write` method without
- * importing Mastra's full `ToolStream` (which would also drag in
- * agent / tool types this module doesn't otherwise need).
- */
-interface MinimalWriter {
-    write: (chunk: unknown) => unknown;
-}
-/** Inputs to {@link emitChartWithPlanning}. */
-export interface EmitChartWithPlanningOptions {
-    /** Mastra `ctx.writer`; missing or closed writers are tolerated. */
-    writer?: MinimalWriter;
-    /** Plugin config; used to resolve the planner's model. */
-    config: MastraPluginConfig;
-    /** Per-request context (OBO auth). */
-    requestContext?: RequestContext;
-    /** Title shown above the rendered chart. Required. */
-    title: string;
-    /** Optional one-line intent biasing the planner. */
-    description?: string;
-    /** Tabular dataset to chart (one object per row). */
-    data: ReadonlyArray<Record<string, unknown>>;
-}
-/** Output of {@link emitChartWithPlanning}. */
-export interface EmitChartWithPlanningResult {
-    /** Short id matching the marker `[[chart:<chartId>]]`. */
-    chartId: string;
-    /**
-     * Promise that resolves once the planner has finished and the
-     * `kind: "chart"` event with the option has been emitted (or
-     * once the planner has failed silently). Callers that want
-     * trace observability should `await` this before returning
-     * from their tool's `execute`; callers that want pure
-     * fire-and-forget can ignore it.
-     */
-    plannerPromise: Promise<void>;
-}
-/**
- * Shared chart-emission primitive used by both the `render_data`
- * tool and Genie's `drainGenieStream`. Keeps both producers on
- * one wire-format contract so the chat client only ever has to
- * understand a single chart event shape.
- *
- * Behaviour:
- *
- * 1. Generates a short `chartId` (8 hex chars).
- * 2. Immediately emits `{ kind: "chart", chartId, title,
- *    description?, data }` via the writer so the chat client can
- *    mount its `<ChartSlot>` with the rows in hand.
- * 3. Kicks off the chart-planner agent in the background. On
- *    success, emits a second `{ kind: "chart", chartId, option }`
- *    event - same `chartId`, just the spec - so the client merges
- *    the two into one rendered chart. On failure, no follow-up
- *    event fires; the client falls back to whatever it can do
- *    with the dataset alone (typically a "render failed" frame
- *    after the parent tool finishes).
- *
- * Returns `chartId` synchronously so the caller can include it in
- * the tool result (model uses it in `[[chart:<chartId>]]`
- * markers), and `plannerPromise` so the caller can choose
- * trace-spanning vs. snappy-return semantics.
- */
-export declare function emitChartWithPlanning(opts: EmitChartWithPlanningOptions): Promise<EmitChartWithPlanningResult>;
-/**
- * Build the `render_data` tool bound to the given plugin config.
- *
- * The tool is a thin wrapper around {@link emitChartWithPlanning}:
- * a single `kind: "chart"` writer event ships the raw rows to
- * the client immediately, the chart-planner agent runs alongside
- * (so the calling LLM stays unblocked while the planner thinks),
- * and a follow-up `kind: "chart"` event with the resolved
- * `EChartsOption` lands when it's ready. The tool's `execute`
- * awaits the planner promise so the planner work shows up under
- * the tool's trace span; the LLM still gets back just
- * `{ chartId }`, so its context stays small regardless of dataset
- * size.
- */
-export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "render_data", unknown>;
-export {};