@dbx-tools/appkit-mastra 0.1.25 → 0.1.27

package/dist/src/config.d.ts

@@ -191,7 +191,7 @@ export interface MastraPluginConfig extends BasePluginConfig {
      * processor that strips `chartId` fields from prior assistant
      * tool-invocation results before they reach the model. This
      * prevents the model from reusing turn-scoped chartIds it sees
-     * in memory recall (which would leave `[[chart:<id>]]` markers
+     * in memory recall (which would leave `[chart:<id>]` markers
      * pointing at writer events that no longer exist).
      *
      * Set to `false` to opt out - useful if a non-default agent
@@ -266,22 +266,25 @@ export interface MastraPluginConfig extends BasePluginConfig {
      */
     genieSpaceCacheTtlMs?: number;
     /**
-     * Maximum LLM steps the Genie agent gets per turn.
-     * Each step is one round-trip to the underlying model
-     * (`get_space_description`, each `ask_genie` call, and the
-     * mandatory `submit_summary` closer all consume one step).
+     * Maximum LLM steps each agent gets per turn. One step = one
+     * round-trip to the underlying model (a tool call consumes a
+     * step, the final-text reply consumes one too). Applies to
+     * every agent registered through {@link MastraPluginConfig.agents}
+     * - per-agent overrides aren't surfaced yet because the same
+     * ceiling has been sufficient across every workload we've run.
      *
-     * Defaults to 16, which fits ~10 `ask_genie` calls plus
-     * grounding plus the summary closer - matches the
-     * decomposition pattern the Genie agent instructions prescribe
-     * ("2-6 ask_genie calls for any non-trivial question").
-     * Mastra's own `agent.generate` default of 5 would cut the
-     * Genie agent off after 2-3 Genie calls, so explicitly raising
-     * the ceiling here is what lets the agent-mode loop play out.
+     * Defaults to {@link DEFAULT_AGENT_MAX_STEPS} (25), 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. Mastra's own `agent.generate` default of 5 would
+     * cut multi-step orchestration off after 2-3 tool calls, so
+     * explicitly raising the ceiling here is what lets the
+     * agent-mode loop play out.
      *
-     * Lower this when an unusually slow or expensive model makes
-     * long turns unaffordable; raise it for exploratory workloads
-     * that need to drill into a dataset.
+     * Lower when an unusually slow or expensive model makes long
+     * turns unaffordable; raise for exploratory workloads that need
+     * to drill deep into a dataset within a single turn.
      */
-    genieAgentMaxSteps?: number;
+    agentMaxSteps?: number;
 }

package/dist/src/genie.d.ts

@@ -1,46 +1,61 @@
 /**
- * Genie agent for Mastra.
+ * Genie tools for Mastra.
  *
- * Each configured Genie space exposes a single Mastra tool to the
- * calling agent (`genie` for the `"default"` alias, `genie_<alias>`
- * otherwise). When invoked, the tool runs end-to-end:
+ * Each configured Genie space is surfaced as a small set of flat
+ * Mastra tools the calling agent can drive directly - no inner
+ * orchestrator agent. The central agent decomposes user questions,
+ * picks which Genie space to ask, and composes the final reply.
  *
- *   1. Pulls the per-request {@link WorkspaceClient} off
- *      `ctx.requestContext` (stamped by `MastraServer`) and emits a
- *      `started` writer event so the host UI can show progress
- *      immediately, before any LLM round-trip.
- *   2. Spins up a per-call inner Mastra `Agent` with three tools:
- *        - `ask_genie`: drives one `genieEventChat` turn, fetches
- *          the matching statement's rows when the turn ran SQL,
- *          and forwards every wire event (status, thinking, sql,
- *          rows) through `ctx.writer` for streaming UI updates.
- *        - `get_space_description`: cheap title / description /
- *          warehouse id lookup for grounding.
- *        - `get_space_serialized`: full `GenieSpace` JSON for
- *          column-level grounding when the description isn't
- *          enough.
- *   3. Runs the inner agent with `structuredOutput` (Mastra's
- *      two-pass mode + `jsonPromptInjection`) to coerce the
- *      agent's final answer into a tagged
- *      `[{type:"text"|"data", ...}]` array. The two-pass design
- *      avoids Databricks Model Serving's `response_format` +
- *      `tools` collision; prompt injection sidesteps the
- *      separate `response_format` + streaming collision in the
- *      structuring agent.
- *   4. Charts every `data` item in parallel via
- *      {@link runChartPlanner}, maps `text` items to the shared
- *      {@link GenieSummaryItem} `string` variant, and returns the
- *      hydrated {@link GenieAgentResult}.
+ * Per-space tools (suffixed with `_<alias>` for non-default
+ * aliases):
  *
- * The inner 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 `spaces` config so existing
- * AppKit-style wiring keeps working without change.
+ *   - `ask_genie`: drives one `genieEventChat` turn and
+ *     forwards every wire event (status, thinking, sql, rows)
+ *     through `ctx.writer` for streaming UI updates. Returns
+ *     the terminal `GenieMessage` only - rows are NOT fetched
+ *     eagerly.
+ *   - `get_space_description`: cheap title / description /
+ *     warehouse id lookup for grounding.
+ *   - `get_space_serialized`: full `GenieSpace` JSON for
+ *     column-level grounding when the description isn't enough.
+ *
+ * Space-agnostic shared tools (registered once, regardless of
+ * how many spaces are wired):
+ *
+ *   - `get_statement`: opt-in lookup of a Genie statement's rows
+ *     by `statement_id` (with a row `limit`). The agent calls
+ *     this only when it needs to read values to reason about
+ *     them; if the data is just being displayed, it embeds a
+ *     `[data:<statement_id>]` marker in prose instead and lets
+ *     the host UI resolve it.
+ *   - `prepare_chart`: mints a short `chartId`, kicks off a
+ *     background task that fetches the statement's rows and
+ *     runs the chart-planner, and caches the resolved Echarts
+ *     spec under the id (1h TTL). Returns the `chartId`
+ *     synchronously so the agent embeds `[chart:<chartId>]`
+ *     markers in prose without blocking on chart generation;
+ *     the host UI fetches the cached chart by id once it's
+ *     ready (see {@link fetchChart}).
+ *
+ * Each tool's `execute` pulls the per-request
+ * {@link WorkspaceClient} off `ctx.requestContext` (stamped by
+ * `MastraServer` under {@link MASTRA_USER_KEY}) and the per-call
+ * `writer` / `abortSignal` off `ctx`, so the tools are stateless
+ * across requests and the central agent owns the loop.
+ *
+ * The tools talk to Genie directly via `@dbx-tools/genie`
+ * (`genieEventChat`); statement-row fetching is delegated to
+ * {@link fetchStatementData} from `./statement.js`, which wraps
+ * the workspace `statementExecution.getStatement` API. AppKit's
+ * stock `genie` plugin is honored only for its `spaces` config
+ * so existing AppKit-style wiring keeps working without change.
+ *
+ * Suggested orchestration prompt for the central agent lives in
+ * {@link GENIE_INSTRUCTIONS}; compose it into the agent's own
+ * `instructions` when you want the canonical "how to drive the
+ * Genie tools" guidance.
  */
-import { type ChartEvent } from "@dbx-tools/appkit-mastra-shared";
 import { appkitUtils } from "@dbx-tools/shared";
-import type { RequestContext } from "@mastra/core/request-context";
 import type { MastraTools } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
 /** Default alias used when a single unnamed Genie space is wired up. */
@@ -50,76 +65,40 @@ export interface GenieSpaceConfig {
     /** Genie `space_id`. Required; resolves via `client.genie.getSpace`. */
     spaceId: string;
     /**
-     * Optional human-readable description appended to the Genie
-     * tool's description so the calling LLM has hints about
-     * *what data* this space covers (e.g. "orders, returns,
+     * Optional human-readable description appended to the per-space
+     * tool descriptions so the calling LLM has hints about *what
+     * data* this space covers (e.g. "orders, returns,
      * fulfillment"). When omitted, only the space's own
-     * `description` (fetched on first use) is shown.
+     * `description` (fetched on first use of `get_space_description`)
+     * is shown.
      */
     hint?: string;
 }
 /** Map of alias -> space config. Accepts either explicit objects or bare space ids. */
 export type GenieSpacesConfig = Record<string, GenieSpaceConfig | string>;
 /**
- * Get the chart inventory map for this request, creating it on
- * first access. Subsequent reads return the same map so callers
- * mutate in place. The map is request-scoped (collected with the
- * `RequestContext` at end of request), so there's no per-process
- * leak.
- */
-export declare function chartInventoryFromContext(requestContext: RequestContext): Map<string, ChartEvent>;
-/**
- * Options for {@link createGenieTool}. Only carries config that
- * doesn't vary per request - the per-request {@link WorkspaceClient},
- * `RequestContext`, writer, and abort signal flow through the
- * tool's `execute(_, ctx)` and are not captured here.
- */
-export interface CreateGenieToolOptions {
-    /** Genie space id this tool targets. */
-    spaceId: string;
-    /** Plugin config; resolves the LLM and chart planner agent. */
-    config: MastraPluginConfig;
-    /** Override the registered tool id. Defaults to `"genie"`. */
-    toolId?: string;
-    /** Override the tool description shown to the calling LLM. */
-    toolDescription?: string;
-    /**
-     * Override the inner agent's max tool-loop steps. Defaults to
-     * {@link DEFAULT_MAX_STEPS}.
-     */
-    maxSteps?: number;
-}
-/**
- * Build the calling agent's Genie tool. The returned Mastra tool
- * runs end-to-end on each invocation:
+ * Suggested orchestration prompt for the central agent that owns
+ * the Genie tools. Compose into your agent's `instructions` to
+ * get the canonical "decompose questions, ask Genie focused
+ * sub-questions, place data / chart markers in prose" behavior:
  *
- *   1. Pull the per-request `WorkspaceClient` off
- *      `ctx.requestContext` (stamped by `MastraServer` under
- *      {@link MASTRA_USER_KEY}) and emit a `started` writer
- *      event so the host UI shows progress immediately.
- *   2. Spin up the inner Mastra agent + three tools, fresh per
- *      call so the row cache stays invocation-scoped.
- *   3. Run the agent with `structuredOutput` against
- *      {@link agentSummarySchema}. Mastra's two-pass design keeps
- *      the inner loop tools-only (no `response_format`), so the
- *      Databricks Model Serving `response_format`+`tools`
- *      collision never fires.
- *   4. Walk the returned `[text|data][]`, map `text` items to
- *      shared `GenieSummaryItem.string`, and chart every `data`
- *      item in parallel via {@link runChartPlanner} to a
- *      `GenieSummaryItem.visualize`. Items referencing a missing
- *      `statementId` are dropped with a warn log; chart-planner
- *      failures leave `dataset.chart` unset so the host UI falls
- *      back to a table.
- */
-export declare function createGenieTool(opts: CreateGenieToolOptions): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, string, unknown>;
-/**
- * Default tool id for a wired Genie alias. The well-known
- * `default` alias collapses to `genie`; every other alias gets a
- * `genie_` prefix so multi-space registrations stay
- * disambiguated.
+ * ```ts
+ * createAgent({
+ *   instructions: `${myAgentInstructions}\n\n${GENIE_INSTRUCTIONS}`,
+ *   tools(plugins) {
+ *     return { ...plugins.genie?.toolkit() };
+ *   },
+ * });
+ * ```
+ *
+ * The prompt references the bare tool names (`ask_genie`,
+ * `get_space_description`, `get_space_serialized`,
+ * `get_statement`, `prepare_chart`) used for the single-space
+ * default alias. Multi-space deployments should write their own
+ * variant that names the suffixed per-space tools
+ * (e.g. `ask_genie_sales`).
  */
-export declare function defaultGenieToolName(alias: string): string;
+export declare const GENIE_INSTRUCTIONS: string;
 /**
  * Normalize the {@link GenieSpacesConfig} record. Bare-string
  * entries (`{ default: "01ef..." }`) get wrapped as
@@ -154,14 +133,19 @@ export declare function normalizeGenieSpaces(spaces: GenieSpacesConfig | Record<
  */
 export declare function resolveGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): Record<string, GenieSpaceConfig>;
 /**
- * Build one Mastra tool per configured Genie space. Each tool is
- * a thin {@link createGenieTool} wrapper with the alias-derived
- * id and a hint-flavored description so the calling LLM knows
- * which space covers what data.
+ * Build the flat Mastra tools record for every configured Genie
+ * space. Two shared, space-agnostic tools (`get_statement`,
+ * `prepare_chart`) are registered once regardless of how many
+ * spaces are wired; the per-space tools (`ask_genie`,
+ * `get_space_description`, `get_space_serialized`) are suffixed
+ * with `_<alias>` for non-default aliases so multi-space
+ * deployments stay disambiguated.
  *
- * Returns a record keyed by tool id, ready to spread into an
- * `Agent`'s `tools` map (or surfaced via
- * `plugins.genie?.toolkit()`).
+ * Returns a record keyed by tool id, ready to spread into the
+ * central `Agent`'s `tools` map (or surfaced via the
+ * `plugins.genie?.toolkit()` callback). Returns an empty record
+ * when `spaces` resolves to zero entries so the caller can spread
+ * safely.
  */
 export declare function buildGenieTools(opts: {
     spaces: GenieSpacesConfig | Record<string, GenieSpaceConfig>;
@@ -170,7 +154,7 @@ export declare function buildGenieTools(opts: {
 /**
  * Plugin-toolkit adapter so the `plugins.genie?.toolkit()` lookup
  * inside an agent's `tools(plugins)` callback returns the
- * Genie agent-backed tools instead of throwing on missing plugin.
+ * flat Genie tools record instead of throwing on missing plugin.
  * Mirrors AppKit's `PluginToolkitProvider` shape.
  */
 export declare function buildGenieToolkitProvider(opts: {