@dbx-tools/appkit-mastra 0.1.25 → 0.1.27

package/dist/src/statement.js

@@ -0,0 +1,118 @@
+/**
+ * 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 { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
+import { apiUtils } from "@dbx-tools/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 const STATEMENT_ROW_CAP = 500;
+/**
+ * Best-effort numeric coercion for the Statement Execution API's
+ * all-strings cells. Leaves non-numeric strings (and explicit
+ * `null`s) intact; everything else flows through `Number`.
+ */
+function coerceCell(cell) {
+    if (cell === null)
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(cell)) {
+        const n = Number(cell);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return cell;
+}
+/**
+ * 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 async function fetchStatementData(client, statementId, options) {
+    const ctx = options?.signal ? apiUtils.toContext(options.signal) : undefined;
+    const r = await client.statementExecution.getStatement({ statement_id: statementId }, ctx);
+    const columns = (r.manifest?.schema?.columns ?? []).map((c) => c.name ?? "");
+    const dataArray = (r.result?.data_array ?? []);
+    const sliced = options?.limit !== undefined && options.limit >= 0
+        ? dataArray.slice(0, options.limit)
+        : dataArray;
+    const rows = sliced.map((row) => {
+        const obj = {};
+        columns.forEach((col, i) => {
+            obj[col] = coerceCell(row[i] ?? null);
+        });
+        return obj;
+    });
+    return {
+        columns,
+        rows,
+        rowCount: r.manifest?.total_row_count ?? dataArray.length,
+    };
+}
+/**
+ * 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 function isStatementNotFoundError(err) {
+    if (err instanceof ApiError) {
+        if (err.statusCode === 404)
+            return true;
+        if (err.errorCode === "RESOURCE_DOES_NOT_EXIST")
+            return true;
+    }
+    if (err instanceof HttpError && err.code === 404)
+        return true;
+    if (err instanceof Error && /does not exist|not found/i.test(err.message)) {
+        return true;
+    }
+    return false;
+}

package/dist/src/tools/email.js

@@ -30,40 +30,40 @@ import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 const log = logUtils.logger("mastra/tool/send-email");
 const emailInputSchema = z.object({
-    to: z.string().describe(stringUtils.toDescription `
+    to: z.string().describe(stringUtils.toDescription(`
     Single recipient email address (e.g. "alice@example.com"). For
     multiple recipients, comma-separate them yourself.
-  `),
-    subject: z.string().describe(stringUtils.toDescription `
+  `)),
+    subject: z.string().describe(stringUtils.toDescription(`
     Subject line.
-  `),
-    body: z.string().describe(stringUtils.toDescription `
-    Email body. Plain text or markdown; the renderer downstream
-    decides which to honour. Be specific - the recipient may not
-    have any context the model has from prior chat turns.
-  `),
+  `)),
+    body: z.string().describe(stringUtils.toDescription(`
+    Email body. Plain text or markdown; the renderer downstream decides
+    which to honour. Be specific - the recipient may not have any
+    context the model has from prior chat turns.
+  `)),
     cc: z
         .array(z.string())
         .optional()
-        .describe(stringUtils.toDescription `
+        .describe(stringUtils.toDescription(`
       Optional CC recipients.
-    `),
+    `)),
     bcc: z
         .array(z.string())
         .optional()
-        .describe(stringUtils.toDescription `
+        .describe(stringUtils.toDescription(`
       Optional BCC recipients.
-    `),
+    `)),
 });
 const emailOutputSchema = z.object({
-    sent: z.boolean().describe(stringUtils.toDescription `
+    sent: z.boolean().describe(stringUtils.toDescription(`
     True when the email was dispatched. The current implementation
-    always returns true after console-logging the would-be email;
-    swap in a real provider to make this meaningful.
-  `),
-    recipient: z.string().describe(stringUtils.toDescription `
+    always returns true after console-logging the would-be email; swap
+    in a real provider to make this meaningful.
+  `)),
+    recipient: z.string().describe(stringUtils.toDescription(`
     Echo of the \`to\` field for confirmation.
-  `),
+  `)),
 });
 /**
  * Build the `send_email` tool. Approval-gated by default; the
@@ -88,15 +88,14 @@ const emailOutputSchema = z.object({
 export function buildEmailTool(opts = {}) {
     return createTool({
         id: opts.id ?? "send_email",
-        description: stringUtils.toDescription `
-      Send an email on the user's behalf. Pass a recipient
-      address, subject, and body; the user will be prompted to
-      approve the send before it goes out (the tool is
-      approval-gated). Use this when the user explicitly asks
-      to send / forward / share something via email - never
-      autonomously. Keep subjects short and bodies focused; the
-      recipient may not have any of the chat context.
-    `,
+        description: stringUtils.toDescription(`
+      Send an email on the user's behalf. Pass a recipient address,
+      subject, and body; the user will be prompted to approve the send
+      before it goes out (the tool is approval-gated). Use this when
+      the user explicitly asks to send / forward / share something via
+      email - never autonomously. Keep subjects short and bodies
+      focused; the recipient may not have any of the chat context.
+    `),
         inputSchema: emailInputSchema,
         outputSchema: emailOutputSchema,
         requireApproval: true,