@dbx-tools/appkit-mastra 0.1.25 → 0.1.27

package/dist/src/intercept.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Server-side Server-Sent-Events frame interceptor for the native
+ * Mastra agent `/stream` endpoint.
+ *
+ * The Mastra stream (`@mastra/express`) emits one `data: <json>\n\n`
+ * SSE frame per chunk, where the decoded JSON carries a
+ * discriminating `type` (`text-delta`, `reasoning-delta`,
+ * `tool-call`, `step-finish`, ...) and is terminated by a
+ * `data: [DONE]` sentinel. {@link installStreamEventInterceptor} wraps
+ * an Express response and runs a caller-supplied
+ * {@link StreamFrameInterceptor} over each decoded frame so the caller
+ * can keep, rewrite, or drop it; every non-`data:` byte (SSE
+ * keep-alive comments, the `[DONE]` sentinel, blank padding) passes
+ * through verbatim.
+ *
+ * The wrap is inert unless the response turns out to be a streamed
+ * `200 text/event-stream` body, so non-streaming JSON routes and
+ * error responses are never touched.
+ */
+import type express from "express";
+/**
+ * Per-frame interceptor invoked with the `JSON.parse`d object of every
+ * `data: {json}` frame on the Mastra `/stream` response. The return
+ * value decides the frame's fate:
+ *
+ * - `true`: forward the frame's original bytes unchanged (no
+ *   re-serialization).
+ * - `false`: drop the frame entirely.
+ * - `{ replace }`: re-emit the frame with the original `data:` prefix
+ *   and trailing whitespace preserved and only the JSON body replaced
+ *   by `JSON.stringify(replace)`.
+ */
+export type StreamFrameInterceptor = (chunk: unknown) => {
+    replace: unknown;
+} | true | false;
+/**
+ * Wrap `res.write` / `res.end` so each SSE frame on a streamed Mastra
+ * response is run through `interceptor` (keep / rewrite / drop).
+ *
+ * Interception only engages once the response is confirmed to be a
+ * `200 text/event-stream` body (decided lazily on the first write,
+ * after the handler has set status + content-type); any other
+ * response streams through unchanged. A {@link StringDecoder}
+ * reassembles multi-byte UTF-8 sequences that straddle chunk
+ * boundaries, and a running buffer holds the trailing partial frame
+ * until its `\n\n` arrives.
+ */
+export declare function installStreamEventInterceptor(res: express.Response, interceptor: StreamFrameInterceptor): void;

package/dist/src/intercept.js

@@ -0,0 +1,167 @@
+/**
+ * Server-side Server-Sent-Events frame interceptor for the native
+ * Mastra agent `/stream` endpoint.
+ *
+ * The Mastra stream (`@mastra/express`) emits one `data: <json>\n\n`
+ * SSE frame per chunk, where the decoded JSON carries a
+ * discriminating `type` (`text-delta`, `reasoning-delta`,
+ * `tool-call`, `step-finish`, ...) and is terminated by a
+ * `data: [DONE]` sentinel. {@link installStreamEventInterceptor} wraps
+ * an Express response and runs a caller-supplied
+ * {@link StreamFrameInterceptor} over each decoded frame so the caller
+ * can keep, rewrite, or drop it; every non-`data:` byte (SSE
+ * keep-alive comments, the `[DONE]` sentinel, blank padding) passes
+ * through verbatim.
+ *
+ * The wrap is inert unless the response turns out to be a streamed
+ * `200 text/event-stream` body, so non-streaming JSON routes and
+ * error responses are never touched.
+ */
+import { StringDecoder } from "node:string_decoder";
+/** SSE event separator used by the Mastra stream wire format. */
+const FRAME_DELIMITER = "\n\n";
+/**
+ * Matches a whole SSE frame whose `data:` payload is a JSON object,
+ * capturing it in three parts: the `data:` field prefix (including
+ * whatever inter-token whitespace the producer used), the JSON object
+ * body, and any trailing whitespace. Anchored end-to-end so it only
+ * matches a single self-contained object frame; anything else (SSE
+ * comments, the `[DONE]` sentinel, text/array payloads) fails the
+ * match and is forwarded verbatim without a parse attempt. On rewrite
+ * the captured prefix/suffix are re-emitted as-is so only the body
+ * changes.
+ */
+const DATA_OBJECT_RE = /^(data:\s*)(\{[\s\S]*\})(\s*)$/;
+/**
+ * True when `res` is a `200 text/event-stream` body - the only
+ * response shape we intercept. Content-type based so it tracks the
+ * Mastra `/stream` route without hard-coding the path, and naturally
+ * skips the JSON routes (history, models, charts, statements) and any
+ * non-200 error response.
+ */
+function isEventStream(res) {
+    if (res.statusCode !== 200)
+        return false;
+    const contentType = String(res.getHeader("content-type") ?? "").toLowerCase();
+    return contentType.includes("text/event-stream");
+}
+/**
+ * Run `interceptor` over a single SSE frame. Forwards anything that
+ * isn't a parseable `data: {json}` object frame verbatim (comments,
+ * the `[DONE]` sentinel, blank padding, unparseable / non-object
+ * payloads) so the interceptor only ever sees real chunk objects.
+ * Returns the frame string to emit, or `undefined` to drop the frame.
+ */
+function interceptFrame(frame, interceptor) {
+    const match = DATA_OBJECT_RE.exec(frame);
+    if (!match)
+        return frame;
+    const [, prefix, body, suffix] = match;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // Forward unparseable payloads untouched - feeding a partial /
+        // malformed frame to the interceptor risks corrupting bytes the
+        // client could still have handled.
+        return frame;
+    }
+    const result = interceptor(parsed);
+    if (result === true)
+        return frame;
+    if (result === false)
+        return undefined;
+    // Preserve the exact captured prefix/suffix so only the JSON body
+    // changes; the framing the client parses stays byte-identical.
+    return `${prefix}${JSON.stringify(result.replace)}${suffix}`;
+}
+/**
+ * Wrap `res.write` / `res.end` so each SSE frame on a streamed Mastra
+ * response is run through `interceptor` (keep / rewrite / drop).
+ *
+ * Interception only engages once the response is confirmed to be a
+ * `200 text/event-stream` body (decided lazily on the first write,
+ * after the handler has set status + content-type); any other
+ * response streams through unchanged. A {@link StringDecoder}
+ * reassembles multi-byte UTF-8 sequences that straddle chunk
+ * boundaries, and a running buffer holds the trailing partial frame
+ * until its `\n\n` arrives.
+ */
+export function installStreamEventInterceptor(res, interceptor) {
+    const origWrite = res.write.bind(res);
+    const origEnd = res.end.bind(res);
+    const decoder = new StringDecoder("utf8");
+    let engaged;
+    let buffer = "";
+    // Append decoded text, emit every whole `\n\n`-delimited frame the
+    // interceptor keeps, and retain any trailing partial frame in
+    // `buffer`. On `final`, the residual buffer is flushed as the last
+    // frame so a stream that doesn't end on a delimiter isn't dropped.
+    const intercept = (text, final) => {
+        buffer += text;
+        const out = [];
+        let idx;
+        while ((idx = buffer.indexOf(FRAME_DELIMITER)) !== -1) {
+            const frame = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + FRAME_DELIMITER.length);
+            const kept = interceptFrame(frame, interceptor);
+            if (kept !== undefined) {
+                out.push(kept, FRAME_DELIMITER);
+            }
+        }
+        if (final && buffer.length > 0) {
+            const kept = interceptFrame(buffer, interceptor);
+            if (kept !== undefined)
+                out.push(kept);
+            buffer = "";
+        }
+        return out.length === 0 ? "" : out.join("");
+    };
+    const toText = (chunk) => {
+        if (typeof chunk === "string")
+            return chunk;
+        if (Buffer.isBuffer(chunk))
+            return decoder.write(chunk);
+        if (chunk instanceof Uint8Array) {
+            return decoder.write(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+        }
+        return "";
+    };
+    res.write = function patchedWrite(chunk, encodingOrCb, cb) {
+        if (engaged === undefined)
+            engaged = isEventStream(res);
+        if (!engaged) {
+            return origWrite(chunk, encodingOrCb, cb);
+        }
+        const callback = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+        const out = intercept(toText(chunk), false);
+        if (out.length === 0) {
+            // The chunk only advanced a partial frame; nothing to forward
+            // yet. Honor the write callback so backpressure-aware writers
+            // don't stall waiting on an ack that never comes.
+            if (callback)
+                queueMicrotask(() => callback());
+            return true;
+        }
+        return origWrite(out, callback);
+    };
+    res.end = function patchedEnd(chunk, encodingOrCb, cb) {
+        if (engaged === undefined)
+            engaged = isEventStream(res);
+        if (!engaged) {
+            return origEnd(chunk, encodingOrCb, cb);
+        }
+        const callback = typeof chunk === "function"
+            ? chunk
+            : typeof encodingOrCb === "function"
+                ? encodingOrCb
+                : cb;
+        const text = (typeof chunk !== "function" && chunk !== undefined ? toText(chunk) : "") +
+            decoder.end();
+        const out = intercept(text, true);
+        if (out.length > 0)
+            origWrite(out);
+        return origEnd(callback);
+    };
+}

package/dist/src/plugin.d.ts

@@ -109,6 +109,18 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
     };
     clientConfig(): Record<string, unknown>;
     injectRoutes(router: IAppRouter): void;
+    /**
+     * Implementation backing the `data` embed resolver
+     * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so
+     * `getExecutionContext()` returns the OBO-scoped workspace
+     * client, then reuses the same `fetchStatementData` pipeline
+     * the `get_statement` tool runs so the LLM and the UI see the
+     * exact same shape for the same statement.
+     *
+     * Returns `undefined` for upstream 404s so the route can map
+     * them to a clean HTTP 404; any other failure bubbles up.
+     */
+    private fetchStatement;
     /**
      * Return `this.asUser(req)` when the request carries an OBO token,
      * otherwise return `this` directly. Prevents the noisy AppKit warn

package/dist/src/plugin.js

@@ -27,16 +27,19 @@
  *   AI SDK transport URL is `/api/mastra/route/chat/<agentId>`.
  */
 import { genie, getExecutionContext, lakebase, Plugin, toPlugin, } from "@databricks/appkit";
-import { appkitUtils, logUtils } from "@dbx-tools/shared";
+import { appkitUtils, commonUtils, logUtils } from "@dbx-tools/shared";
 import { chatRoute } from "@mastra/ai-sdk";
 import { Mastra } from "@mastra/core/mastra";
 import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.js";
+import { fetchChart } from "./chart.js";
 import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { buildObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
+import { installStreamEventInterceptor, } from "./intercept.js";
 import { clearServingEndpointsCache, listServingEndpoints, resolveServingConfig, } from "./serving.js";
+import { fetchStatementData, isStatementNotFoundError, STATEMENT_ROW_CAP, } from "./statement.js";
 const GENIE_MANIFEST = appkitUtils.data(genie).plugin.manifest;
 const LAKEBASE_MANIFEST = appkitUtils.data(lakebase).plugin.manifest;
 /**
@@ -171,6 +174,7 @@ export class MastraPlugin extends Plugin {
             modelsPath: `${basePath}/models`,
             historyPath: `${basePath}/route/history`,
             historyPathTemplate: `${basePath}/route/history/:agentId`,
+            embedPathTemplate: `${basePath}/embed/:type/:id`,
             defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
             agents: Object.keys(this.built?.agents ?? {}),
         };
@@ -188,12 +192,126 @@ export class MastraPlugin extends Plugin {
                 .then((endpoints) => res.json({ endpoints }))
                 .catch(next);
         });
+        // `GET /embed/:type/:id` is the single resolver for every embed
+        // marker the agent emits in prose (`[chart:<id>]`,
+        // `[data:<id>]`, ...). `:type` selects a resolver from the
+        // registry below; `:id` is that resolver's lookup key. The
+        // grammar (see `marker.ts`) is type-agnostic on purpose - new
+        // embed kinds are added by registering a resolver here, with no
+        // client or grammar change.
+        //
+        // Status codes:
+        //   - 200 with the resolver's JSON body when the id resolves.
+        //   - 404 when `:type` isn't registered (unsupported embed
+        //     type) OR a registered resolver can't find `:id` (unknown
+        //     / expired - e.g. a chart past its 1h TTL or a fabricated
+        //     id the model never minted).
+        //   - 400 when `:id` is empty.
+        //
+        // Per-type query knobs and behavior:
+        //   - `chart`: long-polls the chart cache until the entry
+        //     settles (`result` / `error`) or the budget elapses (then
+        //     returns the still-processing entry to poll again).
+        //     `?timeoutMs=<n>` (default 60s, capped 5min) tunes it.
+        //   - `data`: one OBO-scoped Statement Execution fetch.
+        //     `?limit=<n>` caps rows (clamped to STATEMENT_ROW_CAP).
+        //
+        // Built once (this handler is registered once) and keyed by the
+        // raw `:type` token. Each resolver gets the request (for query
+        // parsing + OBO scoping) and an `AbortSignal` bridged off the
+        // connection `close` event so a long-poll unblocks the instant
+        // the client disconnects. `undefined` from a resolver maps to a
+        // clean 404; thrown errors bubble through `next(err)`.
+        const embedResolvers = {
+            chart: (req, id, signal) => {
+                const timeoutMs = parseTimeoutMs(req.query["timeoutMs"]);
+                return fetchChart(id, {
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    signal,
+                });
+            },
+            data: (req, id, signal) => {
+                const limit = parseStatementLimit(req.query["limit"]);
+                return this.userScopedSelf(req).fetchStatement(id, {
+                    ...(limit !== undefined ? { limit } : {}),
+                    signal,
+                });
+            },
+        };
+        router.get("/embed/:type/:id", (req, res, next) => {
+            const type = req.params["type"] ?? "";
+            const id = req.params["id"];
+            const resolve = embedResolvers[type];
+            if (!resolve) {
+                res.status(404).json({ error: `unsupported embed type: ${type}` });
+                return;
+            }
+            if (!id) {
+                res.status(400).json({ error: "id is required" });
+                return;
+            }
+            // Express's `req` predates `AbortSignal`; bridge the `close`
+            // event onto an `AbortController` so a closed connection
+            // unblocks any long-poll immediately and frees the request
+            // thread. The listener is GC'd with the request on normal
+            // completion.
+            const controller = new AbortController();
+            req.on("close", () => controller.abort());
+            resolve(req, id, controller.signal)
+                .then((entry) => {
+                if (entry === undefined) {
+                    res.status(404).json({ error: `${type} not found` });
+                    return;
+                }
+                res.json(entry);
+            })
+                .catch(next);
+        });
         router.use("", (req, res, next) => {
             if (!this.mastraApp)
                 return res.status(503).end();
+            // Run each Mastra `/stream` SSE frame through the interceptor
+            // (keep / rewrite / drop). Only engages on a
+            // `200 text/event-stream` body, so the JSON routes above and any
+            // error response are untouched.
+            installStreamEventInterceptor(res, interceptStreamFrame);
             return this.userScopedSelf(req).mastraApp(req, res, next);
         });
     }
+    /**
+     * Implementation backing the `data` embed resolver
+     * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so
+     * `getExecutionContext()` returns the OBO-scoped workspace
+     * client, then reuses the same `fetchStatementData` pipeline
+     * the `get_statement` tool runs so the LLM and the UI see the
+     * exact same shape for the same statement.
+     *
+     * Returns `undefined` for upstream 404s so the route can map
+     * them to a clean HTTP 404; any other failure bubbles up.
+     */
+    async fetchStatement(statementId, options = {}) {
+        const client = getExecutionContext().client;
+        const limit = Math.min(options.limit ?? STATEMENT_ROW_CAP, STATEMENT_ROW_CAP);
+        try {
+            const data = await fetchStatementData(client, statementId, {
+                limit,
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            return {
+                columns: data.columns,
+                rows: data.rows,
+                rowCount: data.rowCount,
+                truncated: data.rows.length < data.rowCount,
+            };
+        }
+        catch (err) {
+            // The Databricks SDK throws on 404; surface as `undefined`
+            // so the route maps to a clean HTTP 404 instead of a 500.
+            if (isStatementNotFoundError(err))
+                return undefined;
+            throw err;
+        }
+    }
     /**
      * Return `this.asUser(req)` when the request carries an OBO token,
      * otherwise return `this` directly. Prevents the noisy AppKit warn
@@ -290,4 +408,70 @@ export class MastraPlugin extends Plugin {
         });
     }
 }
+/**
+ * Parse the optional `?timeoutMs=<n>` query parameter from a
+ * `GET /embed/chart/:id` request. Accepts a positive integer up
+ * to 5 minutes (clamped) and rejects everything else as
+ * `undefined` so {@link fetchChart} falls back to its default.
+ * Express produces `string | string[] | undefined`; we normalize
+ * to the first scalar before parsing.
+ */
+function parseTimeoutMs(raw) {
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof v !== "string")
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(Math.floor(n), 5 * 60_000);
+}
+/**
+ * Parse the optional `?limit=<n>` query parameter from a
+ * `GET /embed/data/:id` request. Accepts a non-negative
+ * integer and lets the route clamp to `STATEMENT_ROW_CAP`;
+ * rejects anything else as `undefined` so the route falls back
+ * to the server-side cap.
+ */
+function parseStatementLimit(raw) {
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof v !== "string")
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return Math.floor(n);
+}
+/**
+ * {@link StreamFrameInterceptor} for Mastra `/stream` responses.
+ *
+ * Removes large, redundant payloads from terminal `step-finish`,
+ * `finish`, and `tool-result` frames before they reach the browser.
+ * These frames often repeat information already delivered incrementally
+ * via streamed text and tool events, including full tool outputs,
+ * accumulated responses, message history, SQL results, chart data, and
+ * other large result payloads.
+ *
+ * The interceptor deletes heavyweight payload properties
+ * (`output`, `messages`, `response`, and `result`) while preserving the
+ * event envelope and lifecycle metadata required by the client.
+ *
+ * Deletion is key based, so streams that do not contain these
+ * fields are passed through unchanged.
+ */
+const interceptStreamFrame = (chunk) => {
+    if (!commonUtils.isRecord(chunk))
+        return true;
+    if (!["step-finish", "finish", "tool-result"].find((type) => type === chunk.type))
+        return true;
+    const payload = chunk.payload;
+    if (!commonUtils.isRecord(payload))
+        return true;
+    const trimmedPayload = commonUtils.deleteKeys(payload, [
+        "output",
+        "messages",
+        "response",
+        "result",
+    ]);
+    return trimmedPayload ? { replace: chunk } : true;
+};
 export const mastra = toPlugin(MastraPlugin);

package/dist/src/processors/strip-stale-charts.d.ts

@@ -3,21 +3,24 @@
  * tool-invocation result in prior assistant messages before they
  * reach the model.
  *
- * Why: chartIds are only meaningful within the assistant turn that
- * minted them - the writer events backing them are gone after the
- * stream closes. When the model sees old chartIds in memory recall
- * (Mastra Memory persists tool results), it's tempted to type
- * those ids into the new turn's `[[chart:<id>]]` markers, leaving
- * the chat client's chart slots stuck with no matching event. This
- * processor removes the temptation by deleting `chartId` keys from
- * every assistant message's tool results before the prompt is
- * built. The current turn's tool results don't exist yet at
- * `processInput` time, so they pass through unmodified.
+ * Why: chartIds are turn-scoped from the model's point of view -
+ * each `prepare_chart` / `render_data` call mints a fresh id and
+ * the host UI binds it to that turn's reply. Mastra Memory
+ * replays prior tool results into the prompt; if old chartIds
+ * leak through, the model is tempted to copy them verbatim into
+ * the new turn's `[chart:<id>]` markers and the host UI ends up
+ * rendering an unrelated chart from the chart cache (or
+ * a 404 once the 1h TTL elapsed). This processor removes the
+ * temptation by deleting `chartId` keys from every assistant
+ * message's tool results before the prompt is built. The current
+ * turn's tool results don't exist yet at `processInput` time, so
+ * they pass through unmodified.
  *
  * The strip is recursive - any nested `chartId` field is removed,
- * regardless of which tool produced the result. This covers Genie's
- * `datasets[].chartId` and `render_data`'s top-level `chartId`
- * uniformly without coupling to specific tool ids.
+ * regardless of which tool produced the result. This covers
+ * `prepare_chart` / `render_data` top-level chartIds and any
+ * legacy `datasets[].chartId` payloads uniformly without coupling
+ * to specific tool ids.
  */
 import type { InputProcessor } from "@mastra/core/processors";
 /**

package/dist/src/processors/strip-stale-charts.js

@@ -3,21 +3,24 @@
  * tool-invocation result in prior assistant messages before they
  * reach the model.
  *
- * Why: chartIds are only meaningful within the assistant turn that
- * minted them - the writer events backing them are gone after the
- * stream closes. When the model sees old chartIds in memory recall
- * (Mastra Memory persists tool results), it's tempted to type
- * those ids into the new turn's `[[chart:<id>]]` markers, leaving
- * the chat client's chart slots stuck with no matching event. This
- * processor removes the temptation by deleting `chartId` keys from
- * every assistant message's tool results before the prompt is
- * built. The current turn's tool results don't exist yet at
- * `processInput` time, so they pass through unmodified.
+ * Why: chartIds are turn-scoped from the model's point of view -
+ * each `prepare_chart` / `render_data` call mints a fresh id and
+ * the host UI binds it to that turn's reply. Mastra Memory
+ * replays prior tool results into the prompt; if old chartIds
+ * leak through, the model is tempted to copy them verbatim into
+ * the new turn's `[chart:<id>]` markers and the host UI ends up
+ * rendering an unrelated chart from the chart cache (or
+ * a 404 once the 1h TTL elapsed). This processor removes the
+ * temptation by deleting `chartId` keys from every assistant
+ * message's tool results before the prompt is built. The current
+ * turn's tool results don't exist yet at `processInput` time, so
+ * they pass through unmodified.
  *
  * The strip is recursive - any nested `chartId` field is removed,
- * regardless of which tool produced the result. This covers Genie's
- * `datasets[].chartId` and `render_data`'s top-level `chartId`
- * uniformly without coupling to specific tool ids.
+ * regardless of which tool produced the result. This covers
+ * `prepare_chart` / `render_data` top-level chartIds and any
+ * legacy `datasets[].chartId` payloads uniformly without coupling
+ * to specific tool ids.
  */
 import { logUtils } from "@dbx-tools/shared";
 const log = logUtils.logger("mastra/processor/strip-stale-charts");

package/dist/src/statement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Databricks Statement Execution helpers for the Mastra plugin.
+ *
+ * Wraps `client.statementExecution.getStatement` with the shape
+ * + size + error handling the plugin's tools and the
+ * `/embed/data/:id` route both need:
+ *
+ *   - {@link fetchStatementData}: low-level fetch that returns the
+ *     raw `{columns, rows, rowCount}` shape used by the
+ *     `get_statement` tool's output, the `prepare_chart` tool's
+ *     dataset resolver, and the route's response body. Coerces
+ *     numeric strings to numbers so downstream charts /
+ *     aggregations don't have to.
+ *   - {@link STATEMENT_ROW_CAP}: hard cap callers (notably the
+ *     `/embed/data/:id` route) clamp `limit` to so a
+ *     runaway result set can't hose a response.
+ *   - {@link isStatementNotFoundError}: structural detector that
+ *     normalizes the SDK's two error classes plus the loose
+ *     `does not exist` / `not found` message shapes into a single
+ *     boolean - lets the route map upstream 404s to a clean
+ *     HTTP 404 without coupling to SDK error-class identity.
+ *
+ * Not Genie-specific: a Databricks `statement_id` is workspace
+ * scoped and lives in the Statement Execution API regardless of
+ * which producer (Genie, a tool, a notebook, etc.) submitted the
+ * query. Co-located here so consumers can fetch / cap / handle
+ * 404s without reaching into the Genie tool module.
+ */
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import type { GenieDatasetData } from "@dbx-tools/appkit-mastra-shared";
+/**
+ * Hard server-side cap on rows returned by the
+ * `/embed/data/:id` route. Sized to keep responses small
+ * enough for inline tables to render snappily; the route surfaces
+ * a `truncated` flag whenever the upstream `rowCount` exceeds
+ * this so end users know they're seeing a sample.
+ */
+export declare const STATEMENT_ROW_CAP = 500;
+/**
+ * Fetch a single statement's rows via the Statement Execution API
+ * and reshape into the shared {@link GenieDatasetData} shape
+ * (column array + row records).
+ *
+ * Optional `limit` slices the returned `rows` client-side so the
+ * agent can scan a small sample without paging the full result
+ * set into context. `rowCount` always reflects the upstream total
+ * so callers know when the slice truncated.
+ *
+ * Exported because every consumer in the plugin (the
+ * `get_statement` tool, the `prepare_chart` dataset resolver, and
+ * the `/embed/data/:id` route) needs the exact same
+ * fetch + coercion pipeline so LLM-side `get_statement` output
+ * and UI-side `[data:<id>]` rendering stay shape-identical for
+ * the same `statement_id`.
+ */
+export declare function fetchStatementData(client: WorkspaceClient, statementId: string, options?: {
+    limit?: number;
+    signal?: AbortSignal;
+}): Promise<GenieDatasetData>;
+/**
+ * True when `err` looks like the Databricks SDK's "statement not
+ * found" error. Matches the typed {@link ApiError} 404 /
+ * `RESOURCE_DOES_NOT_EXIST` shape first, then falls back to the
+ * lower-level {@link HttpError} 404, then to a loose `does not
+ * exist` / `not found` message sniff for SDK shapes we haven't
+ * catalogued.
+ *
+ * Pulled into its own helper so callers (notably the
+ * `/embed/data/:id` route) stay decoupled from SDK
+ * error-class identity, and the conversion logic stays testable
+ * in isolation.
+ */
+export declare function isStatementNotFoundError(err: unknown): boolean;