@dbx-tools/appkit-mastra 0.1.25 → 0.1.27

package/README.md

@@ -102,18 +102,18 @@ The plugin is opinionated about what "no config" should mean. Everything
 below can be overridden, but the bare path works:
 
 
-| Scenario                                            | What you get                                                                                                                                                                                                                                                                         |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mastra()`                                          | One built-in `default` analyst agent, model from `/serving-endpoints`; memory + storage auto-on if the `lakebase` plugin is registered                                                                                                                                               |
-| `mastra({ agents: def })`                           | Single-agent shorthand - `def` is registered and marked as default                                                                                                                                                                                                                   |
-| `mastra({ agents: [def1, def2] })`                  | Array shorthand - keys come from each `def.name` (or `agent_<i>`); first one is default                                                                                                                                                                                              |
-| `mastra({ agents: { x: def, y: def }})`             | Record - keys are the registered ids; first key is the default                                                                                                                                                                                                                       |
-| No `defaultAgent` set                               | First registered agent wins                                                                                                                                                                                                                                                          |
+| Scenario                                            | What you get                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mastra()`                                          | One built-in `default` analyst agent, model from `/serving-endpoints`; memory + storage auto-on if the `lakebase` plugin is registered                                                                                                                                                                                               |
+| `mastra({ agents: def })`                           | Single-agent shorthand - `def` is registered and marked as default                                                                                                                                                                                                                                                                   |
+| `mastra({ agents: [def1, def2] })`                  | Array shorthand - keys come from each `def.name` (or `agent_<i>`); first one is default                                                                                                                                                                                                                                              |
+| `mastra({ agents: { x: def, y: def }})`             | Record - keys are the registered ids; first key is the default                                                                                                                                                                                                                                                                       |
+| No `defaultAgent` set                               | First registered agent wins                                                                                                                                                                                                                                                                                                          |
 | No `model` on an agent                              | Falls back to `config.defaultModel`, then `DATABRICKS_SERVING_ENDPOINT_NAME`, then walks `defaultModelFallbacks` (Thinking → Balanced → Fast tiers, Claude ↔ GPT ↔ Gemini interleaved within each, then open-weights) and picks the first endpoint actually present in the workspace |
-| No `name` on a definition                           | Uses the registry key as `Agent.name`                                                                                                                                                                                                                                                |
-| No `tools` on an agent                              | Inherits plugin-level `config.tools` ambient set (if any)                                                                                                                                                                                                                            |
-| No `storage` / `memory` and `lakebase()` registered | Both auto-default to `true`. Pass `false` (or a custom config object) on the plugin or an agent to opt out / override.                                                                                                                                                               |
-| `storage` / `memory` on an agent                    | Cascades from plugin: storage namespaces **per-agent** (`schemaName: "mastra_<agentId>"`), vector recall is **shared** across agents on one `PgVector` singleton.                                                                                                                    |
+| No `name` on a definition                           | Uses the registry key as `Agent.name`                                                                                                                                                                                                                                                                                                |
+| No `tools` on an agent                              | Inherits plugin-level `config.tools` ambient set (if any)                                                                                                                                                                                                                                                                            |
+| No `storage` / `memory` and `lakebase()` registered | Both auto-default to `true`. Pass `false` (or a custom config object) on the plugin or an agent to opt out / override.                                                                                                                                                                                                               |
+| `storage` / `memory` on an agent                    | Cascades from plugin: storage namespaces **per-agent** (`schemaName: "mastra_<agentId>"`), vector recall is **shared** across agents on one `PgVector` singleton.                                                                                                                                                                    |
 
 
 Every field on `MastraAgentDefinition`:
@@ -190,72 +190,79 @@ that implements the standard `getAgentTools()` + `executeAgentTool()` +
 `executeAgentTool`, so OBO auth (`asUser`) and telemetry spans stay
 intact.
 
-`plugins.genie` is special-cased: it talks to Genie directly via
-`@dbx-tools/genie` (`genieEventChat`) rather than calling AppKit's
-stock `genie` toolkit. Each invocation spins up a per-call inner
-Mastra `Agent` with three tools (`ask_genie`,
-`get_space_description`, `get_space_serialized`), runs it with
-`structuredOutput`, and produces a hydrated
-{@link GenieAgentResult}. AppKit's `genie()` plugin is honored
-only for its `spaces` config (and the matching
-`app.yaml`-declared resources). Tool ids are stable: `genie` for
-the default alias, `genie_<alias>` for additional aliases.
-
-Genie tool-result shape (LLM-bound) is the
-[`GenieAgentResult`](../appkit-mastra-shared/src/genie.ts) type:
+`plugins.genie` is special-cased: it returns a flat set of
+Mastra tools the central agent drives directly (no inner
+orchestrator agent). Two shared, space-agnostic tools register
+once regardless of how many spaces are wired:
+
+- `get_statement(statement_id, limit?)` - fetch rows for a
+  Genie statement. Use only when the agent needs to read values
+  to reason about them; otherwise embed `[data:<statement_id>]`.
+- `prepare_chart({statement_id, title?, description?})` - mint a
+  `chartId` (v4 UUID), kick off a background chart-planner task,
+  cache the resolved Echarts spec under the id for one hour.
+  Returns `{chartId}` synchronously so the agent can embed
+  `[chart:<chartId>]` in prose without blocking.
+
+Three per-space tools register per wired alias (`ask_genie`,
+`get_space_description`, `get_space_serialized` for the
+`default` alias; `ask_genie_<alias>`, etc. for additional
+aliases):
+
+- `ask_genie({question})` - drives one `genieEventChat` turn
+  and streams wire events (status / thinking / sql) through
+  `ctx.writer`. Returns `{message: GenieMessage}`; rows are
+  NOT fetched eagerly.
+- `get_space_description()` - cheap title / description /
+  warehouse id lookup.
+- `get_space_serialized()` - full `GenieSpace` JSON for
+  column-level grounding when the description isn't enough.
+
+AppKit's `genie()` plugin is honored only for its `spaces`
+config (and the matching `app.yaml`-declared resources). The
+tools talk to Genie directly via `@dbx-tools/genie`
+(`genieEventChat`) and the workspace
+`statementExecution.getStatement` API.
+
+The orchestration prompt (decompose, ask Genie focused
+sub-questions, place markers in prose) ships as the exported
+`GENIE_INSTRUCTIONS` string - compose it into your agent's
+`instructions` to get the canonical behavior:
 
 ```ts
-type GenieAgentResult = {
-  spaceId: string;
-  conversationId?: string;        // thread back to continue the same Genie thread
-  summary: Array<                 // ordered prose + visualize slots
-    | { type: "string"; text: string }
-    | {
-        type: "visualize";
-        statementId: string;
-        title?: string;
-        description?: string;
-        dataset: {
-          data: { columns: string[]; rows: Row[]; rowCount: number };
-          chart?: { chartId: string; chartType: "bar" | "line" | "area" | "scatter" | "pie" };
-        };
-      }
-  >;
-  error?: string;
-};
+import { createAgent, GENIE_INSTRUCTIONS } from "@dbx-tools/appkit-mastra";
+
+const support = createAgent({
+  instructions: `${baseInstructions}\n\n${GENIE_INSTRUCTIONS}`,
+  tools(plugins) {
+    return { ...plugins.genie?.toolkit() };
+  },
+});
 ```
 
-The `summary` is the user-facing renderable: a mixed sequence of
-prose paragraphs (`type: "string"`) and `visualize` slots that
-mark where a chart should appear in the model's final answer.
-Visualize slots embed the dataset (rows + columns) plus a slim
-`chart` reference (just `chartId` + `chartType`); the resolved
-Echarts spec rides a separate `type: "chart"` writer event so the
-LLM never holds it in context. The host UI joins the dataset and
-the writer event by `chartId` and renders inline at the matching
-`[[chart:<chartId>]]` marker.
+`GENIE_INSTRUCTIONS` references the default (`default` alias)
+tool names. Multi-space deployments should write a custom
+variant that names the suffixed per-space tools
+(e.g. `ask_genie_sales`).
 
 Genie writer event flow:
 
-- The writer emits the flat
-  [`GenieWriterEvent`](../appkit-mastra-shared/src/genie.ts)
-  union for the live loading pill - the wire-derived
-  `GenieChatEvent` (status / thinking / sql / rows / suggested)
-  plus the Mastra-only lifecycle events (`started`,
-  `ask_genie_done`, `summary`, `chart`, `error`).
-- The writer emits one `type: "chart"` event per executed SQL
-  statement carrying `{chartId, title, description?, data,
-  option, statementId, messageId}`. The chat client's
-  `<ChartSlot>` renders inline at the matching
-  `[[chart:<chartId>]]` marker. This is the exact same wire
-  format as the `render_data` tool, so Genie and hand-built
-  charts are indistinguishable on the client.
-- After a hard reload, `synthesizeToolEventsFromHistory`
-  reconstructs lifecycle events from the persisted summary
-  (`error` events via `genieResultToWriterEvents`); live-only
-  events (rows, SQL pill, chart specs) don't replay because the
-  resolved Echarts spec is held off-band on the per-request
-  `RequestContext`.
+- Each `ask_genie` call emits a Mastra-only `started` event
+  before any network round-trip, then forwards every wire
+  `GenieChatEvent` (status / thinking / sql / rows / suggested
+  / message / result / error) through `ctx.writer`.
+- Charts ride out-of-band: `prepare_chart` mints a `chartId`
+  synchronously, the planner runs in the background and writes
+  the spec to the chart cache (1h TTL). The host UI long-polls
+  `${MastraClientConfig.embedPathTemplate}` (`/embed/chart/:id`)
+  by id and renders inline at the matching `[chart:<chartId>]`
+  marker.
+- After a hard reload, the live `started` / `status` / `sql`
+  events are gone (they only ride the writer, not persisted
+  tool results); the central agent's text reply (with embedded
+  `[data:<statement_id>]` / `[chart:<chartId>]` markers) is
+  preserved in the message history and the host UI re-resolves
+  the markers on its own.
 
 ### `render_data` (system-default ambient tool)
 
@@ -272,73 +279,66 @@ set, an API response, a hand-built array, etc.).
 
 #### How it works
 
-`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. `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.
+`render_data` is a thin wrapper around `prepareChart`, the same
+orchestrator the Genie `prepare_chart` tool uses. It mints a
+`chartId` synchronously, caches an empty placeholder, and kicks
+off the chart-planner in the background. The tool returns just
+`{ chartId }` so the model can embed `[chart:<chartId>]` in
+prose immediately without blocking on chart generation.
+
+1. Mint a `chartId` (v4 UUID via `crypto.randomUUID()`).
+2. Cache an empty `{ chartId }` placeholder so the first
+   `fetchChart` call always sees an entry (no spurious 404 race).
+3. Fire-and-forget: resolve the dataset (trivial for
+   `render_data` since the rows are already in hand) and run
+   `runChartPlanner` in the background. On success the cache
+   entry settles with `{ chartId, result }` (containing the
+   `chartType` and full `EChartsOption`). On failure it settles
+   with `{ chartId, error }`.
+4. Return `{ chartId }` to the LLM immediately.
+
+The host UI resolves `[chart:<chartId>]` markers by hitting
+the plugin's generic `GET /embed/chart/:id` route, which long-polls
+until the entry settles or the server-side timeout elapses.
 
 #### Inline placement contract
 
-The model embeds `[[chart:<chartId>]]` on its own line in its
-markdown reply at the position where the chart should appear:
+The model embeds `[chart:<chartId>]` on its own line in its
+markdown reply at the position where the chart should appear
+(the `<chartId>` is the v4 UUID the tool returned):
 
 ```markdown
 ## Audit Score
 
 Audit Score is stable at ~94%, hovering between 93.5 and 95.0.
 
-[[chart:a3f9c1d2]]
+[chart:a3f9c1d2-7b4e-4c1a-9f2d-1e6b8c0a5d31]
 
 ## Service Time
 
 Service time is the outlier at 162.5s, up from a target of 150s.
 
-[[chart:b7e2d4f1]]
+[chart:b7e2d4f1-3a9c-4e58-8d10-2f7a4b6c9e02]
 ```
 
 The chat client splits the assistant text on these markers and
 drops a `<ChartSlot>` in at each spot. A marker that arrives
-before its `chart` event (rare; only during fast streaming) shows
-a "Queueing chart" skeleton; a chart whose marker the model
-forgot to place falls through to the end of the reply as a
-fallback. All three states (queueing, rendering, rendered) share
-the same fixed-height frame so the layout doesn't jump as
-charts resolve.
+before its chart settles in the cache shows a "Queueing chart"
+skeleton; a chart whose marker the model forgot to place falls
+through to the end of the reply as a fallback. All three states
+(queueing, rendering, rendered) share the same fixed-height
+frame so the layout doesn't jump as charts resolve.
 
 #### Trade-offs
 
-- Both events ride the writer, not the persisted tool-result, so
-  charts don't re-render after a hard reload. The model can call
-  `render_data` again (or re-ask Genie) on the next turn if the
-  user wants the chart back.
+- Chart entries live in the cache with a 1h TTL. After expiry
+  the `/embed/chart/:id` route returns 404. The model can call
+  `render_data` again on the next turn if the user wants the
+  chart back.
 - The chart-planner is a separate model call per dataset (fast
   tier, but still ~1-3s each). For an N-chart turn, latency is
-  `Genie + max(planners)` since the planners run concurrently
-  with the rest of Genie's stream and with each other.
+  `max(planners)` since the planners run concurrently in the
+  background and the tool returns immediately.
 
 Plugins that aren't registered (or don't implement the toolkit
 interface) resolve to `undefined` at runtime, so guard with `?.` /
@@ -551,192 +551,4 @@ Same payload from a sibling plugin or script (no HTTP round-trip):
 import { appkitUtils } from "@dbx-tools/shared";
 import { mastra } from "@dbx-tools/appkit-mastra";
 
-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
-```
-
-### Per-request model override
-
-Any in-flight request can pick a different backing endpoint without
-redeploying. Sources, checked in priority order:
-
-
-| Source                    | Example                                          |
-| ------------------------- | ------------------------------------------------ |
-| `X-Mastra-Model` header   | `curl -H 'X-Mastra-Model: claude-haiku' ...`     |
-| `?model=` query parameter | `POST /api/mastra/route/chat?model=llama-70b`    |
-| Body `model` or `modelId` | `{ "messages": [...], "model": "claude-haiku" }` |
-
-
-The override flows through the same fuzzy matcher as static ids, so
-`X-Mastra-Model: claude sonnet` still snaps to
-`databricks-claude-sonnet-4-6`. Set `modelOverride: false` on the
-plugin config to disable the override path entirely (e.g. for a
-multi-tenant deployment where untrusted clients shouldn't pick the
-endpoint).
-
-## Memory + storage
-
-Memory and storage are split into two independent knobs and both auto-on
-the moment the `lakebase` plugin is registered. Bare `mastra()` next to
-`lakebase()` already gets you per-agent threads + shared semantic recall;
-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, 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
-value wins when set; otherwise the plugin value cascades.
-
-```ts
-mastra({
-  // Plugin defaults. Either field becomes the cascading baseline.
-  // Omit entirely to inherit "auto-on when lakebase is present".
-  storage: true,      // (default behavior when lakebase is registered)
-  memory: true,       // (default behavior when lakebase is registered)
-
-  agents: {
-    analyst: createAgent({
-      instructions: "...",
-      // No overrides: inherits the auto-on defaults above.
-      //   - threads stored under schema "mastra_analyst"
-      //   - recalls from the shared vector index
-    }),
-
-    router: createAgent({
-      instructions: "Stateless routing agent.",
-      // Opt out of both for a fully stateless agent.
-      storage: false,
-      memory: false,
-    }),
-
-    legal: createAgent({
-      instructions: "Compliance-bounded assistant.",
-      // Private vector index so legal's recall doesn't bleed into
-      // analyst's. Threads still get their own per-agent schema.
-      memory: { connectionString: process.env.LEGAL_PG_URL!, /* ... */ },
-    }),
-
-    archive: createAgent({
-      instructions: "Read-only archive viewer.",
-      // Pin to a specific schema (e.g. shared with another service).
-      storage: {
-        schemaName: "shared_history",
-        pool: archivePool,
-      },
-    }),
-  },
-});
-```
-
-Notes:
-
-- `PostgresStore` runs `CREATE SCHEMA IF NOT EXISTS` on `init()`, so
-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.
-- The `lakebase` plugin is declared as a **required** resource only when
-`storage` / `memory` is explicitly truthy at registration time. Auto-on
-defaults activate inside `setup:complete`, after lakebase is already
-proven to be present.
-
-## Runtime exports
-
-Other plugins / route handlers can introspect the registry via the
-`exports()` surface, modeled on AppKit's:
-
-```ts
-import { appkitUtils } from "@dbx-tools/shared";
-import { mastra } from "@dbx-tools/appkit-mastra";
-
-const m = appkitUtils.require(this.context, mastra).exports();
-m.list(); // ["analyst", "helper"]
-m.get("analyst"); // Agent | null
-m.getDefault(); // Agent | null
-m.getMastra(); // underlying Mastra instance (advanced)
-m.listModels(); // Promise<ServingEndpointSummary[]> - cached + OBO when wrapped with asUser(req)
-m.clearModelsCache(); // force the next listModels() to re-fetch
-```
-
-## Client wiring
-
-`clientConfig()` publishes the mount paths, default agent id, and the
-full registry to `usePluginClientConfig("mastra")` so the React client
-never has to hardcode `/api/mastra` or rely on `DEFAULT_AGENT_ID`
-constants. A tiny URL helper (`chatUrl`) and the `MastraClientConfig`
-type ship from the standalone `@dbx-tools/appkit-mastra-shared`
-package; that package is pure (no `pg` / `fastembed` / Mastra
-dependencies) so it imports cleanly into Vite / Webpack / esbuild
-builds.
-
-```tsx
-import { usePluginClientConfig } from "@databricks/appkit-ui/react";
-import { chatUrl, type MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
-import { useChat } from "@ai-sdk/react";
-import { DefaultChatTransport } from "ai";
-import { useMemo, useState } from "react";
-
-function Chat() {
-  const config = usePluginClientConfig<MastraClientConfig>("mastra");
-  const [selected, setSelected] = useState<string>();
-  const api = chatUrl(config, selected); // defaults to config.defaultAgent
-
-  const transport = useMemo(() => new DefaultChatTransport({ api }), [api]);
-  const { messages, sendMessage } = useChat({ transport });
-
-  return (
-    <>
-      <select onChange={(e) => setSelected(e.target.value)}>
-        {config.agents.map((id) => (
-          <option key={id} value={id}>
-            {id}
-          </option>
-        ))}
-      </select>
-      {/* render messages, etc. */}
-    </>
-  );
-}
-```
-
-`MastraClientConfig` fields (all derived from the server-side plugin
-mount, so a custom `mastra({ name: "myMastra" })` rewrites every path):
-
-
-| Field                 | Example                                | Description                                                          |
-| --------------------- | -------------------------------------- | -------------------------------------------------------------------- |
-| `basePath`            | `"/api/mastra"`                        | Plugin mount path.                                                   |
-| `chatPath`            | `"/api/mastra/route/chat"`             | Default-agent chat URL. Use `chatUrl(config)` to get it.             |
-| `chatPathTemplate`    | `"/api/mastra/route/chat/:agentId"`    | OpenAPI-style template for tools / docs.                             |
-| `modelsPath`          | `"/api/mastra/models"`                 | `GET` cached endpoint catalogue.                                     |
-| `historyPath`         | `"/api/mastra/route/history"`          | Default-agent thread history. Use `historyUrl(config, opts)`.        |
-| `historyPathTemplate` | `"/api/mastra/route/history/:agentId"` | OpenAPI-style template for tools / docs.                             |
-| `defaultAgent`        | `"analyst"`                            | Agent id `chatRoute` binds to when none is supplied.                 |
-| `agents`              | `["analyst", "helper"]`                | Every registered agent id in order.                                  |
-
-
-`chatUrl(config, agentId?)` returns `config.chatPath` for the default
-agent (the registered `chatRoute` mount that omits `:agentId`), and
-`${config.chatPath}/${encodeURIComponent(agentId)}` otherwise. The
-sibling `historyUrl(config, { agentId?, page?, perPage? })` mirrors
-that pattern for the `/history` endpoint and appends pagination
-query parameters when provided. Both are pure functions: no React,
-no hooks, safe in service workers and SSR.
-
-## License
-
-Apache-2.0
+const m = appkitUtils.require(this.context, ma

package/dist/src/agents.d.ts

@@ -274,6 +274,16 @@ export interface BuiltAgents {
 }
 /** Fallback agent id used when `config.agents` is omitted entirely. */
 export declare 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 declare const DEFAULT_AGENT_MAX_STEPS = 25;
 /**
  * Style guardrails appended to every agent's `instructions` to curb
  * common LLM-isms (em dashes, emojis, sycophantic openers, excessive

package/dist/src/agents.js

@@ -15,10 +15,10 @@
 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 { buildGenieToolkitProvider, resolveGenieSpaces } from "./genie.js";
 import { buildModel, FALLBACK_MODEL_IDS } from "./model.js";
 import { stripStaleChartsProcessor } from "./processors/strip-stale-charts.js";
+import { buildRenderDataTool } from "./chart.js";
 /** Re-export of Mastra's native `createTool` for full-feature access. */
 export { createTool } from "@mastra/core/tools";
 /**
@@ -90,6 +90,16 @@ export function createAgent(def) {
 }
 /** 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.
 
@@ -178,7 +188,7 @@ export async function buildAgents(opts) {
     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
+    // turn's `[chart:<id>]` markers. Opt out per-plugin via
     // `config.stripStaleCharts: false`.
     const inputProcessors = config.stripStaleCharts === false ? [] : [stripStaleChartsProcessor];
     const agents = {};
@@ -191,6 +201,9 @@ export async function buildAgents(opts) {
             ...(def.description !== undefined ? { description: def.description } : {}),
             instructions: composeInstructions(def.instructions, style),
             model: resolveModel(config, def.model),
+            defaultOptions: {
+                maxSteps: config.agentMaxSteps ?? DEFAULT_AGENT_MAX_STEPS,
+            },
             tools,
             ...(memory ? { memory } : {}),
             ...(inputProcessors.length > 0 ? { inputProcessors } : {}),