@dbx-tools/appkit-mastra 0.1.18 → 0.1.19

package/README.md

@@ -190,65 +190,72 @@ that implements the standard `getAgentTools()` + `executeAgentTool()` +
 `executeAgentTool`, so OBO auth (`asUser`) and telemetry spans stay
 intact.
 
-`plugins.genie` is special-cased: it swaps the generic AppKit toolkit
-(which only emits a single final result chunk per call) for a
-streaming-aware tools record built on top of the plugin's
-`exports().sendMessage` AsyncGenerator. Each Genie wire event
-(`FETCHING_METADATA`, `ASKING_AI`, `EXECUTING_QUERY`, attached SQL,
-errors) is normalised into a `GenieProgress` payload and pushed
-mid-flight through Mastra's `ctx.writer`, surfacing as
-`tool-output` chunks the React client can render as inline status
-pills and SQL blocks while the LLM is still waiting on the final
-`tool-result`. Tool ids are stable: `genie` for the default alias,
-`genie-<alias>` for additional aliases, and one shared
-`genie_get_conversation`.
-
-Genie tool-result shape (LLM-bound):
+`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:
 
-```
-{
-  conversationId?: string,        // pass back to continue the same Genie thread
-  genieAnswer?: string,           // Genie's prose answer; pass through verbatim
-  datasets?: [{                   // metadata only, one per executed SQL statement
-    chartId: string,              // embed [[chart:<chartId>]] to render inline
-    title?: string,
-    description?: string,
-    columns: string[],
-    rowCount: number,
-    sql?: string,
-  }],
-  suggestedFollowUps?: string[],  // UI shows as buttons; don't list in reply
-  error?: string,
-}
+```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;
+};
 ```
 
-`datasets[]` is metadata only - column names, row count, the SQL
-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
-chart inline; see the `render_data` section below for how the
-client resolves those markers.
-
-Genie data flow:
-
-- 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 `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
-  coercion); the second, when the chart-planner agent finishes,
-  carries `{chartId, option}` (the resolved Echarts spec). The
-  chat client's `<ChartSlot>` merges them by `chartId` and
-  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` rebuilds
-  `suggested` events from the persisted tool-result; the SQL pill
-  and chart events are live-only and don't replay.
+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 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`.
 
 ### `render_data` (system-default ambient tool)
 
@@ -710,20 +717,25 @@ function Chat() {
 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.                         |
-| `defaultAgent`     | `"analyst"`                         | Agent id `chatRoute` binds to when none is supplied.     |
-| `agents`           | `["analyst", "helper"]`             | Every registered agent id in order.                      |
+| 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. Pure
-function: no React, no hooks, safe in service workers and SSR.
+`${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
 

package/dist/src/agents.js

@@ -389,13 +389,12 @@ function buildPluginsMap(config, context) {
  * 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.
+ * The Genie 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 resource manifest and `spaces`
+ * config so existing `app.yaml` configs and `genie({ spaces })`
+ * wiring keep working without change.
  */
 function resolveProvider(config, context, propName) {
     if (propName === "genie") {

package/dist/src/chart.js

@@ -31,6 +31,7 @@ import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 import { ModelTier, modelForTier, buildModel } from "./model.js";
+import { safeWrite } from "./writer.js";
 /**
  * Module-level logger tagged `[mastra/chart]`. Uses the shared
  * {@link logUtils.logger} so calls below `LOG_LEVEL` are
@@ -373,56 +374,33 @@ export function buildRenderDataTool(config) {
                 // for the table-like fallback / hover, option for the
                 // actual render. Best-effort write so a closed
                 // downstream stream can't take the tool down.
-                await safeWrite(writer, chartId, {
+                await safeWrite(log, writer, {
                     type: "chart",
                     chartId,
                     title,
                     ...(description ? { description } : {}),
                     data,
                     option,
-                });
+                }, { chartId });
             }
             catch (err) {
                 log.warn("render:error", {
                     chartId,
                     elapsedMs: Date.now() - startedAt,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: commonUtils.errorMessage(err),
                 });
                 // Surface as a writer-level error so the slot can
                 // transition to "couldn't render chart" without the
                 // parent agent surfacing a stack trace.
-                await safeWrite(writer, chartId, {
+                await safeWrite(log, writer, {
                     type: "error",
-                    error: err instanceof Error ? err.message : String(err),
-                });
+                    error: commonUtils.errorMessage(err),
+                }, { chartId });
             }
             return { chartId };
         },
     });
 }
-/**
- * Best-effort writer.write. Failures are logged at `warn` (a
- * persistently-closed writer is the most likely culprit when
- * chart events go missing client-side) but swallowed so a closed
- * downstream stream (cancelled request, client navigated away)
- * can't take a tool down.
- */
-async function safeWrite(writer, chartId, chunk) {
-    if (!writer) {
-        log.debug("write:no-writer", { chartId });
-        return;
-    }
-    try {
-        await writer.write(chunk);
-        log.debug("write:ok", { chartId });
-    }
-    catch (err) {
-        log.warn("write:error", {
-            chartId,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
 /**
  * Expand a {@link ChartPlan} into a full Echarts `EChartsOption`
  * JSON. Centralized here so the planner agent only fills in the

package/dist/src/genie.d.ts

@@ -32,12 +32,11 @@
  *      {@link GenieSummaryItem} `string` variant, and returns the
  *      hydrated {@link GenieAgentResult}.
  *
- * The legacy AppKit `genie` plugin (`@databricks/appkit`'s `genie`)
- * is no longer used at runtime. The inner agent talks to Genie
- * directly via `@dbx-tools/genie` (`genieEventChat`) and the
- * workspace `statementExecution.getStatement` API. The plugin's
- * `spaces` config is still honored so existing AppKit-style wiring
- * keeps working without change.
+ * 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.
  */
 import { type ChartEvent } from "@dbx-tools/appkit-mastra-shared";
 import { appkitUtils } from "@dbx-tools/shared";

package/dist/src/genie.js

@@ -32,12 +32,11 @@
  *      {@link GenieSummaryItem} `string` variant, and returns the
  *      hydrated {@link GenieAgentResult}.
  *
- * The legacy AppKit `genie` plugin (`@databricks/appkit`'s `genie`)
- * is no longer used at runtime. The inner agent talks to Genie
- * directly via `@dbx-tools/genie` (`genieEventChat`) and the
- * workspace `statementExecution.getStatement` API. The plugin's
- * `spaces` config is still honored so existing AppKit-style wiring
- * keeps working without change.
+ * 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.
  */
 import { CacheManager, genie } from "@databricks/appkit";
 import { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
@@ -52,6 +51,7 @@ import { z } from "zod";
 import { runChartPlanner } from "./chart.js";
 import { MASTRA_USER_KEY } from "./config.js";
 import { buildModel } from "./model.js";
+import { safeWrite } from "./writer.js";
 const log = logUtils.logger("mastra/genie");
 /** Default alias used when a single unnamed Genie space is wired up. */
 export const DEFAULT_GENIE_ALIAS = "default";
@@ -118,26 +118,6 @@ function extractStatementId(message) {
     }
     return undefined;
 }
-/**
- * Best-effort `writer.write`. The writer carries the unified flat
- * event vocabulary directly - no translation layer - so
- * subscribers narrow on `event.type` and read fields inline.
- * Failures (downstream stream closed, cancelled request) are
- * swallowed with a `warn` log so an in-flight Genie turn isn't
- * taken down by a navigated-away client.
- */
-async function safeWrite(writer, chunk) {
-    if (!writer)
-        return;
-    try {
-        await writer.write(chunk);
-    }
-    catch (err) {
-        log.warn("writer:error", {
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
 /**
  * Lowercased placeholder strings we reject at the `ask_genie`
  * boundary so the LLM doesn't spend a Genie round-trip on a
@@ -279,7 +259,7 @@ async function readCachedConversationId(cacheKey) {
     }
     catch (err) {
         log.warn("conversation-cache:read-error", {
-            error: err instanceof Error ? err.message : String(err),
+            error: commonUtils.errorMessage(err),
         });
         return undefined;
     }
@@ -301,7 +281,7 @@ async function saveCachedConversationId(cacheKey, conversationId) {
     }
     catch (err) {
         log.warn("conversation-cache:write-error", {
-            error: err instanceof Error ? err.message : String(err),
+            error: commonUtils.errorMessage(err),
         });
     }
 }
@@ -314,7 +294,7 @@ async function evictCachedConversationId(cacheKey) {
     }
     catch (err) {
         log.warn("conversation-cache:delete-error", {
-            error: err instanceof Error ? err.message : String(err),
+            error: commonUtils.errorMessage(err),
         });
     }
 }
@@ -397,7 +377,7 @@ function buildAskGenieTool(deps) {
                     ...(seedConversationId ? { conversationId: seedConversationId } : {}),
                     ...(signal ? { context: signal } : {}),
                 })) {
-                    await safeWrite(writer, event);
+                    await safeWrite(log, writer, event);
                     // Wire events come in two flavors: the lifecycle `message`
                     // event embeds the raw `GenieMessage` (read its
                     // `conversation_id`), and the rest carry a flat
@@ -437,7 +417,7 @@ function buildAskGenieTool(deps) {
                     log.warn("conversation-cache:stale, resetting", {
                         spaceId,
                         conversationId: seeded,
-                        error: err instanceof Error ? err.message : String(err),
+                        error: commonUtils.errorMessage(err),
                     });
                     await evictCachedConversationId(cacheKey);
                     writeContextConversationId(requestContext, spaceId, undefined);
@@ -663,7 +643,7 @@ export function createGenieTool(opts) {
                 spaceId,
                 content: input.question,
             };
-            await safeWrite(writer, startedEvent);
+            await safeWrite(log, writer, startedEvent);
             const resultSets = new Map();
             // Seed the active Genie `conversation_id` onto
             // `RequestContext` from AppKit's `CacheManager` when a Mastra
@@ -801,7 +781,7 @@ export function createGenieTool(opts) {
                 textItems: textItemCount,
                 dataItems: dataItemCount,
             };
-            await safeWrite(writer, summaryEvent);
+            await safeWrite(log, writer, summaryEvent);
             // Chart every `data` item in parallel; map `text` items to
             // the shared `string` summary variant verbatim. Missing
             // statement ids are dropped (the agent referenced something
@@ -856,7 +836,7 @@ export function createGenieTool(opts) {
                         data: data.rows,
                         option: planned.option,
                     };
-                    await safeWrite(writer, chartEvent);
+                    await safeWrite(log, writer, chartEvent);
                     // Stash the resolved chart on the per-request
                     // `RequestContext` so downstream code in the same
                     // request (output processors, follow-up tool calls,
@@ -865,7 +845,7 @@ export function createGenieTool(opts) {
                     recordChartInContext(requestContext, chartEvent);
                 }
                 catch (err) {
-                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    const errorMessage = commonUtils.errorMessage(err);
                     log.warn("chart:error", {
                         statementId: item.statementId,
                         messageId,
@@ -883,7 +863,7 @@ export function createGenieTool(opts) {
                         messageId,
                         error: `chart-planner: ${errorMessage}`,
                     };
-                    await safeWrite(writer, errorEvent);
+                    await safeWrite(log, writer, errorEvent);
                 }
                 return {
                     type: "visualize",

package/dist/src/history.js

@@ -15,7 +15,7 @@
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
  */
-import { logUtils } from "@dbx-tools/shared";
+import { commonUtils, logUtils } from "@dbx-tools/shared";
 import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
 import { registerApiRoute } from "@mastra/core/server";
@@ -116,7 +116,7 @@ export async function clearHistory(opts) {
         log.debug("clear:probe-failed", {
             agentId: opts.agent.id,
             threadId: opts.threadId,
-            error: err instanceof Error ? err.message : String(err),
+            error: commonUtils.errorMessage(err),
         });
     }
     const startedAt = Date.now();
@@ -131,7 +131,7 @@ export async function clearHistory(opts) {
         log.warn("clear:delete-soft-failed", {
             agentId: opts.agent.id,
             threadId: opts.threadId,
-            error: err instanceof Error ? err.message : String(err),
+            error: commonUtils.errorMessage(err),
         });
     }
     log.info("clear:done", {

package/dist/src/writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared helper for publishing events through Mastra's
+ * `ctx.writer`. Centralizes the "the downstream stream may already
+ * be closed, don't take the whole tool down" pattern that the
+ * Genie agent and chart tool both need.
+ *
+ * Failures are logged at `warn` (a persistently-closed writer is
+ * the most likely culprit when events go missing client-side) but
+ * swallowed so a cancelled request or a client that navigated
+ * away can't crash a tool mid-flight.
+ */
+import type { MinimalWriter } from "@dbx-tools/appkit-mastra-shared";
+import { type logUtils } from "@dbx-tools/shared";
+/**
+ * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * caught errors are logged via `log.warn("writer:error", ...)`
+ * along with any caller-supplied `context` fields (e.g. a
+ * `chartId` or `messageId`) so the warning is greppable per
+ * resource.
+ *
+ * Returns when the write resolves or rejects; never throws.
+ */
+export declare function safeWrite(log: logUtils.Logger, writer: MinimalWriter | undefined, chunk: unknown, context?: Record<string, unknown>): Promise<void>;

package/dist/src/writer.js

@@ -0,0 +1,37 @@
+/**
+ * Shared helper for publishing events through Mastra's
+ * `ctx.writer`. Centralizes the "the downstream stream may already
+ * be closed, don't take the whole tool down" pattern that the
+ * Genie agent and chart tool both need.
+ *
+ * Failures are logged at `warn` (a persistently-closed writer is
+ * the most likely culprit when events go missing client-side) but
+ * swallowed so a cancelled request or a client that navigated
+ * away can't crash a tool mid-flight.
+ */
+import { commonUtils } from "@dbx-tools/shared";
+/**
+ * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * caught errors are logged via `log.warn("writer:error", ...)`
+ * along with any caller-supplied `context` fields (e.g. a
+ * `chartId` or `messageId`) so the warning is greppable per
+ * resource.
+ *
+ * Returns when the write resolves or rejects; never throws.
+ */
+export async function safeWrite(log, writer, chunk, context = {}) {
+    if (!writer) {
+        log.debug("writer:no-writer", context);
+        return;
+    }
+    try {
+        await writer.write(chunk);
+        log.debug("writer:ok", context);
+    }
+    catch (err) {
+        log.warn("writer:error", {
+            ...context,
+            error: commonUtils.errorMessage(err),
+        });
+    }
+}