@dbx-tools/appkit-mastra 0.1.12 → 0.1.18

package/README.md

@@ -223,7 +223,7 @@ Genie tool-result shape (LLM-bound):
 ```
 
 `datasets[]` is metadata only - column names, row count, the SQL
-Genie ran. The actual rows ride a separate `kind: "chart"` writer
+Genie ran. The actual rows ride a separate `type: "chart"` writer
 event so the LLM never has them in context (token cost stays flat
 regardless of dataset size). The model references each dataset by
 its `chartId` via the `[[chart:<chartId>]]` marker to display the
@@ -232,10 +232,10 @@ client resolves those markers.
 
 Genie data flow:
 
-- The writer emits `kind: "started" | "status" | "sql" |
+- The writer emits `type: "started" | "status" | "sql" |
   "suggested" | "error"` events for the live loading pill. SQL
   text is shown via a small Shiki-highlighted block.
-- The writer **also** emits two `kind: "chart"` events per
+- The writer **also** emits two `type: "chart"` events per
   executed SQL statement, sharing the same `chartId`: the first
   carries `{chartId, title, description?, data}` (rows converted
   to objects keyed by column name with best-effort numeric
@@ -263,41 +263,36 @@ upstream. Input is `{ title, description?, data: Row[] }` where
 `data` is an array of objects keyed by column name (a SQL row
 set, an API response, a hand-built array, etc.).
 
-#### How it works (shared pipeline with Genie)
+#### How it works
 
-Both `render_data` and Genie's `drainGenieStream` route through
-one helper, `emitChartWithPlanning`, so the wire format and
-trace shape are consistent everywhere:
+`render_data` is a thin wrapper around `runChartPlanner`, a
+pure async function that takes a dataset and returns a fully-
+resolved Echarts `EChartsOption`. No id-then-promise dance, no
+background work: the planner runs inline, and the tool emits a
+single chart event with everything attached.
 
 1. Mint a short `chartId` (8 hex chars).
-2. Push a `{ kind: "chart", chartId, title, description?, data }`
-   event to `ctx.writer` immediately. The chat client mounts a
-   `<ChartSlot>` showing a "Rendering chart" skeleton.
-3. Kick off the chart-planner agent
-   (`modelForTier(ModelTier.Fast)`) with the dataset in the
-   background. The agent's `structuredOutput` schema is a compact
-   "chart plan" (chart type + axis labels + categories +
-   series); the helper expands the plan into an Echarts
-   `EChartsOption` JSON.
-4. When the planner resolves, push a follow-up
-   `{ kind: "chart", chartId, option }` event. The client's
-   `<ChartSlot>` merges it with the dataset event (last write
-   wins per field) and swaps in `<ReactECharts>`.
-5. If the planner fails, no follow-up event fires. Once the
-   parent tool finishes, the slot transitions to a "couldn't
-   render chart" fallback frame.
-
-The parent tool (`render_data` or Genie) `await`s the planner
-promise(s) before its `execute` returns, so chart latency shows
-up under the tool's trace span. The dataset event fires
-**immediately**, though, so the calling LLM gets back the
-`chartId` synchronously and the chat client has a layout slot
-ready before the planner resolves.
-
-The LLM-bound payload is just `{ chartId }` (for `render_data`)
-or `datasets[]` metadata (for Genie); row data and option JSON
-never reach the LLM, so token cost stays flat regardless of
-dataset size.
+2. `await runChartPlanner({ title, description?, data })`. The
+   planner is its own Mastra `Agent` (`modelForTier(ModelTier.Fast)`)
+   whose `structuredOutput` schema is a compact "chart plan"
+   (chart type + axis labels + categories + series); the helper
+   expands the plan into an `EChartsOption` JSON.
+3. Push one `{ type: "chart", chartId, title, description?, data,
+   option }` event to `ctx.writer`. The chat client's
+   `<ChartSlot>` mounts straight to the rendered Echarts
+   visualisation - no skeleton frame, because the option arrives
+   in the same event as the dataset.
+4. If the planner throws, the tool emits a `type: "error"` writer
+   event instead. The slot transitions to a "couldn't render
+   chart" fallback frame.
+
+Planner latency lands under the tool's trace span (it's
+`await`ed directly), and the LLM-bound payload is just
+`{ chartId }` so the model's context stays flat regardless of
+dataset size. The Genie agent reuses `runChartPlanner` the
+same way to embed charts in its structured summary, so the
+backbone is shared without coupling the two paths to a
+fire-and-forget writer contract.
 
 #### Inline placement contract
 
@@ -546,10 +541,10 @@ curl -s http://localhost:8000/api/mastra/models | jq
 Same payload from a sibling plugin or script (no HTTP round-trip):
 
 ```ts
-import { pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils } from "@dbx-tools/shared";
 import { mastra } from "@dbx-tools/appkit-mastra";
 
-const m = pluginUtils.require(this.context, mastra).exports();
+const m = appkitUtils.require(this.context, mastra).exports();
 const endpoints = await m.asUser(req).listModels(); // user-scoped
 m.clearModelsCache(); // force the next call to re-fetch
 ```
@@ -582,10 +577,10 @@ the moment the `lakebase` plugin is registered. Bare `mastra()` next to
 zero extra config required.
 
 
-| Knob      | Default when `lakebase()` is registered                                                                           | What it backs                                              |
-| --------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `storage` | **Per-agent** `PostgresStore` namespaced by `schemaName: "mastra_<agentId>"` so threads + messages stay isolated. | Mastra threads, messages, working memory.                  |
-| `memory`  | **Shared singleton** `PgVector` across every agent (cross-agent semantic recall on one index).                    | RAG-style recall over past messages via FastEmbed vectors. |
+| Knob      | Default when `lakebase()` is registered                                                                           | What it backs                                                                                  |
+| --------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `storage` | **Per-agent** `PostgresStore` namespaced by `schemaName: "mastra_<agentId>"` so threads + messages stay isolated, plus a Mastra-instance-level `PostgresStore` in schema `mastra_instance`. | Mastra threads, messages, working memory; Mastra-instance-level workflow snapshots (`requireApproval` / `agent.resumeStream()`). |
+| `memory`  | **Shared singleton** `PgVector` across every agent (cross-agent semantic recall on one index).                    | RAG-style recall over past messages via FastEmbed vectors.                                     |
 
 
 Override either at the plugin level, the agent level, or both. The agent
@@ -635,8 +630,15 @@ mastra({
 Notes:
 
 - `PostgresStore` runs `CREATE SCHEMA IF NOT EXISTS` on `init()`, so
-per-agent schemas spring into existence the first time an agent saves
-a message. No bundle / migration step required.
+per-agent schemas (and the shared `mastra_instance` schema) spring
+into existence the first time the agent saves anything. No bundle /
+migration step required.
+- The `mastra_instance` schema exists so that Mastra-instance-level
+artifacts (workflow snapshots used by `agent.resumeStream()`,
+`requireApproval` flows, etc.) live in their own namespace and never
+collide with per-agent thread / message tables. Disable the instance
+store by setting `storage: false` at plugin level - approval-gated
+tool calls will then error on resume.
 - Disabling `lakebase()` from your plugin list while leaving `storage` /
 `memory` truthy fails fast at setup with a clear "lakebase plugin not
 registered" error.
@@ -651,10 +653,10 @@ Other plugins / route handlers can introspect the registry via the
 `exports()` surface, modeled on AppKit's:
 
 ```ts
-import { pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils } from "@dbx-tools/shared";
 import { mastra } from "@dbx-tools/appkit-mastra";
 
-const m = pluginUtils.require(this.context, mastra).exports();
+const m = appkitUtils.require(this.context, mastra).exports();
 m.list(); // ["analyst", "helper"]
 m.get("analyst"); // Agent | null
 m.getDefault(); // Agent | null

package/dist/src/agents.d.ts

@@ -12,7 +12,7 @@
  * built-in analyst so the bare `mastra()` call still mounts a working
  * `chatRoute` agent for demos.
  */
-import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
+import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import { Agent } from "@mastra/core/agent";
 import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
 import type { Tool } from "@mastra/core/tools";
@@ -300,7 +300,7 @@ export declare const DEFAULT_STYLE_INSTRUCTIONS: string;
  */
 export declare function buildAgents(opts: {
     config: MastraPluginConfig;
-    context: pluginUtils.PluginContextLike | undefined;
+    context: appkitUtils.PluginContextLike | undefined;
     memoryBuilder?: MemoryBuilder;
     log: logUtils.Logger;
 }): Promise<BuiltAgents>;

package/dist/src/agents.js

@@ -12,13 +12,12 @@
  * 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 { appkitUtils, logUtils, stringUtils } from "@dbx-tools/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 { buildGenieToolkitProvider, resolveGenieSpaces } from "./genie.js";
+import { buildModel, FALLBACK_MODEL_IDS } 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";
@@ -196,13 +195,52 @@ export async function buildAgents(opts) {
             ...(memory ? { memory } : {}),
             ...(inputProcessors.length > 0 ? { inputProcessors } : {}),
         });
+        // 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"})`);
     }
-    log.info("agents registered", { ids, defaultAgentId });
+    log.info("agents ready", { ids, defaultAgentId });
     return { agents, defaultAgentId };
 }
+/**
+ * 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 !== undefined)
+        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
@@ -341,19 +379,33 @@ function buildPluginsMap(config, context) {
 }
 /**
  * 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.
+ * 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 legacy AppKit `genie` plugin's tools are no longer consulted
+ * at runtime - the Genie agent talks to Genie directly via
+ * `@dbx-tools/genie` (`genieEventChat`) and the workspace
+ * `statementExecution.getStatement` API. But the plugin's
+ * resource manifest and `spaces` config are still honored so
+ * existing `app.yaml` configs and `genie({ spaces })` wiring
+ * keep working without change.
  */
 function resolveProvider(config, context, propName) {
     if (propName === "genie") {
-        const geniePlugin = pluginUtils.instance(context, genie);
-        if (!geniePlugin)
+        const spaces = resolveGenieSpaces(config, context);
+        if (Object.keys(spaces).length === 0)
             return null;
-        return buildGenieProvider(geniePlugin, { config });
+        return buildGenieToolkitProvider({
+            spaces,
+            config,
+        });
     }
     const plugin = context?.getPlugins().get(propName);
     return adaptPluginToolkit(plugin);

package/dist/src/chart.d.ts

@@ -1,37 +1,30 @@
 /**
  * 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.
+ * Two surfaces, one shared brain:
  *
  * - {@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.
+ *   expansion as a plain async function. Takes a dataset and
+ *   returns a promise that resolves to a full `EChartsOption`
+ *   JSON plus the chosen `chartType`. No background work, no
+ *   writer side-effects, no id allocation - callers stitch the
+ *   result into whatever shape their producer needs.
+ *
+ * - {@link buildRenderDataTool}: a Mastra tool the model calls
+ *   ("here is a dataset, render it as a chart"). Mints a short
+ *   `chartId`, `await`s {@link runChartPlanner} so the planner
+ *   latency is attributed to this tool's trace span, emits one
+ *   `type: "chart"` writer event carrying the dataset + resolved
+ *   `option`, and returns `{ chartId }` to the model. The
+ *   LLM-bound output stays flat regardless of dataset size.
  *
  * 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.
+ * `<ChartSlot>` in at the position the model placed it. The slot
+ * resolves directly to the rendered Echarts visualisation - no
+ * skeleton state, because the option is in the same event as the
+ * dataset.
  */
 import type { RequestContext } from "@mastra/core/request-context";
 import { z } from "zod";
@@ -60,10 +53,10 @@ declare const chartPlanSchema: z.ZodObject<{
     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<{
+        data: z.ZodArray<z.ZodCatch<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
             name: z.ZodString;
             value: z.ZodNumber;
-        }, z.core.$strip>]>>;
+        }, z.core.$strip>]>>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type ChartPlan = z.infer<typeof chartPlanSchema>;
@@ -74,6 +67,12 @@ export interface RunChartPlannerOptions {
     title: string;
     description?: string;
     data: ReadonlyArray<Record<string, unknown>>;
+    /**
+     * Cooperative cancellation. Forwarded to the planner agent's
+     * `generate({ abortSignal })` call so concurrent renders can be
+     * aborted as a group when the parent Genie agent's signal fires.
+     */
+    signal?: AbortSignal;
 }
 /** Output of {@link runChartPlanner}: a fully-formed Echarts spec. */
 export interface RunChartPlannerResult {
@@ -82,89 +81,24 @@ export interface RunChartPlannerResult {
 }
 /**
  * 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).
+ * full Echarts `EChartsOption` JSON. Pure async function: no
+ * writer side-effects, no id minting, no background work.
+ * Producers (the `render_data` tool, the Genie agent,
+ * anything else that needs a chart) await this and stitch the
+ * result into whatever shape their wire contract needs.
  */
 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.
+ * The tool awaits {@link runChartPlanner} so the planner's
+ * latency is attributed to this tool's trace span, then emits
+ * one `type: "chart"` writer event carrying the dataset and the
+ * resolved `EChartsOption`. The LLM-bound output is just
+ * `{ chartId }` so the model's context stays flat regardless of
+ * dataset size. Planner failures are caught and surfaced as a
+ * `type: "error"` writer event so the slot can fall back to
+ * "couldn't render chart" without taking the parent agent down.
  */
 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 {};