@dbx-tools/appkit-mastra 0.1.5 → 0.1.13

package/src/observability.ts

@@ -0,0 +1,92 @@
+/**
+ * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
+ * sibling plugin.
+ *
+ * Mastra's `Observability` registry accepts any
+ * `@mastra/observability` `BaseExporter`. We use `OtelExporter` from
+ * `@mastra/otel-exporter` (Mastra's first-party OTLP shim) with the
+ * `custom` provider pointed at Phoenix's local collector URL. No
+ * Arize-specific wrapper is needed - Phoenix is a vanilla
+ * OpenInference-compatible OTLP/HTTP receiver.
+ *
+ * Discovery is structural so this module doesn't depend on
+ * `@dbx-tools/appkit-phoenix` at compile time: we look up the
+ * registered plugin by its registered name (`"phoenix"`) and read its
+ * `exports().collectorEndpoint()` if it is shaped like the phoenix
+ * plugin. The phoenix package is therefore an *optional* sibling -
+ * apps that don't install it just get an undefined observability
+ * config and Mastra runs without OTLP export.
+ */
+
+import type { pluginUtils } from "@dbx-tools/appkit-shared";
+import { Observability } from "@mastra/observability";
+import { OtelExporter } from "@mastra/otel-exporter";
+
+/** Plugin name the phoenix plugin registers under (matches `phoenix()`). */
+const PHOENIX_PLUGIN_NAME = "phoenix";
+
+/** Structural shape of the bits of `phoenix().exports()` we touch. */
+interface PhoenixExportsLike {
+  collectorEndpoint?(): string | undefined;
+}
+
+/** Structural shape of an AppKit plugin instance with `exports()`. */
+interface PluginWithExports {
+  exports?(): unknown;
+}
+
+/**
+ * If the sibling `phoenix` plugin is registered AND has booted with a
+ * usable collector URL, return a Mastra `Observability` configured to
+ * stream traces + logs there. Otherwise return `undefined` so the
+ * caller can omit the field on the `new Mastra({...})` constructor.
+ *
+ * The exporter uses `provider.custom` with `http/protobuf`, which is
+ * what Phoenix's `/v1/traces` endpoint speaks natively. Switching
+ * Phoenix to gRPC would be a one-line `protocol: "grpc"` change and
+ * a different exported URL.
+ */
+export function buildPhoenixObservability(
+  context: pluginUtils.PluginContextLike | undefined,
+  serviceName: string,
+): Observability | undefined {
+  const endpoint = readPhoenixEndpoint(context);
+  if (!endpoint) return undefined;
+
+  return new Observability({
+    configs: {
+      phoenix: {
+        serviceName,
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint,
+                protocol: "http/protobuf",
+              },
+            },
+          }),
+        ],
+      },
+    },
+  });
+}
+
+/**
+ * Pull the OTLP collector URL out of the registered `phoenix` plugin.
+ * Tolerant of the plugin being absent (returns `undefined`) and of a
+ * future shape change in its exports (anything that's not a string
+ * is ignored). The lookup is keyed off the registered plugin *name*
+ * so this file does not depend on `@dbx-tools/appkit-phoenix`.
+ */
+function readPhoenixEndpoint(
+  context: pluginUtils.PluginContextLike | undefined,
+): string | undefined {
+  if (!context) return undefined;
+  const plugin = context.getPlugins().get(PHOENIX_PLUGIN_NAME) as
+    | PluginWithExports
+    | undefined;
+  const exports_ = plugin?.exports?.() as PhoenixExportsLike | undefined;
+  const url = exports_?.collectorEndpoint?.();
+  return typeof url === "string" ? url : undefined;
+}

package/src/plugin.ts

@@ -47,8 +47,8 @@ import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.js";
 import type { MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
 import type { MastraPluginConfig } from "./config.js";
 import { historyRoute } from "./history.js";
-import { renderChartRoute } from "./render-chart-route.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
+import { buildPhoenixObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import {
   clearServingEndpointsCache,
@@ -191,7 +191,6 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       modelsPath: `${basePath}/models`,
       historyPath: `${basePath}/route/history`,
       historyPathTemplate: `${basePath}/route/history/:agentId`,
-      renderChartPath: `${basePath}/route/render-chart`,
       defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
       agents: Object.keys(this.built?.agents ?? {}),
     };
@@ -251,6 +250,11 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       ? createMemoryBuilder(this.config, this.context)
       : undefined;
 
+    this.log.debug("build:start", {
+      lakebase: memoryBuilder !== undefined,
+      stripStaleCharts: this.config.stripStaleCharts !== false,
+    });
+
     // Build every agent declared in `config.agents` (or the built-in
     // fallback when none are declared). Each agent's `model` resolves
     // workspace URL + bearer at call time so concurrent requests get
@@ -268,7 +272,26 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // dev server. Since we're hosting Mastra inside our own Express
     // subapp via `@mastra/express`, custom routes must be passed to
     // the `MastraServer` constructor directly.
-    this.mastra = new Mastra({ agents: this.built.agents });
+    //
+    // `storage` here is *Mastra-instance-level* and persists workflow
+    // snapshots (where suspended `requireApproval` tool calls live).
+    // It's separate from each agent's `Memory.storage`, which only
+    // covers thread / message history. Without it,
+    // `agent.resumeStream()` errors with "could not find a suspended
+    // run" and the approval UI hangs after the user clicks Approve.
+    const instanceStorage = memoryBuilder?.instanceStorage();
+    // Auto-wire OTLP trace export to the sibling `phoenix` plugin if
+    // it's registered. Returns undefined when phoenix isn't around so
+    // the field stays off the constructor and Mastra keeps its noop
+    // observability default. The serviceName is the plugin's bound
+    // name so multiple mastra instances in one process stay
+    // distinguishable in Phoenix.
+    const observability = buildPhoenixObservability(this.context, this.name);
+    this.mastra = new Mastra({
+      agents: this.built.agents,
+      ...(instanceStorage ? { storage: instanceStorage } : {}),
+      ...(observability ? { observability } : {}),
+    });
     this.mastraApp = express();
     attachRoutePatchMiddleware(this.mastraApp);
     this.mastraServer = new MastraServer(this.config, {
@@ -280,10 +303,16 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         chatRoute({ path: "/route/chat/:agentId" }),
         historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
         historyRoute({ path: "/route/history/:agentId" }),
-        renderChartRoute({ path: "/route/render-chart", config: this.config }),
       ],
     });
     await this.mastraServer.init();
+    this.log.debug("build:done", {
+      agents: Object.keys(this.built.agents),
+      defaultAgent: this.built.defaultAgentId,
+      routes: ["/route/chat", "/route/history", "/models"],
+      instanceStorage: instanceStorage !== undefined,
+      observability: observability !== undefined ? "phoenix" : "off",
+    });
   }
 }
 

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

@@ -0,0 +1,105 @@
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * 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.
+ *
+ * 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.
+ */
+
+import { logUtils } from "@dbx-tools/appkit-shared";
+import type {
+  InputProcessor,
+  ProcessInputArgs,
+} from "@mastra/core/processors";
+
+const log = logUtils.logger("mastra/processor/strip-stale-charts");
+
+/**
+ * Recursively clone `value`, omitting any property whose key is
+ * `chartId`. Arrays are mapped element-wise; primitives are
+ * returned as-is. The result is structurally identical to the
+ * input minus chartIds, so downstream message-shape consumers
+ * keep working.
+ */
+function stripChartIds(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stripChartIds);
+  }
+  if (value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      if (key === "chartId") continue;
+      out[key] = stripChartIds(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Input processor that scrubs `chartId` from every tool-invocation
+ * result in the message list. Wired onto every agent by default
+ * via {@link buildAgents}; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export const stripStaleChartsProcessor: InputProcessor = {
+  id: "strip-stale-charts",
+  description:
+    "Removes chartId fields from prior tool-invocation results so the model can't reuse turn-scoped ids from memory.",
+  processInput(args: ProcessInputArgs) {
+    let stripped = 0;
+    for (const message of args.messages) {
+      if (message.role !== "assistant") continue;
+      const parts = message.content?.parts;
+      if (!Array.isArray(parts)) continue;
+      for (const part of parts) {
+        // Tool-invocation parts hold the persisted tool result.
+        // We don't scrub the input args (`rawInput` / `args`) because
+        // the chartId there is the model's outgoing claim, not
+        // anything it could re-reference; only `result` carries
+        // ids that subsequent turns might copy.
+        if (
+          (part as { type?: unknown }).type !== "tool-invocation"
+        ) {
+          continue;
+        }
+        const inv = (part as { toolInvocation?: { result?: unknown } })
+          .toolInvocation;
+        if (!inv || inv.result === undefined) continue;
+        const before = inv.result;
+        const after = stripChartIds(before);
+        // Cheap structural check via JSON length - the actual
+        // strip writes a fresh object only when chartId keys
+        // existed, so different stringification length is a
+        // reliable signal that something was removed.
+        if (
+          typeof before === "object" &&
+          before !== null &&
+          JSON.stringify(before).length !== JSON.stringify(after).length
+        ) {
+          inv.result = after;
+          stripped += 1;
+        }
+      }
+    }
+    if (stripped > 0) {
+      log.debug("stripped", { results: stripped });
+    }
+    return args.messages;
+  },
+};

package/src/server.ts

@@ -46,6 +46,17 @@ export class MastraServer extends MastraServerExpress {
       this.configureRequestContextUser(requestContext);
       this.configureRequestContextThreadId(req, res, requestContext);
       this.configureRequestContextModelOverride(req, requestContext);
+      this.log.debug("auth:middleware", {
+        method: req.method,
+        path: req.path,
+        threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
+        resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
+        modelOverride: requestContext.get(
+          // imported below; logged so a misrouted request shows
+          // up alongside its model selection in `LOG_LEVEL=debug`.
+          "mastra__model_override",
+        ),
+      });
       next();
     });
   }

package/src/serving.ts

@@ -21,7 +21,7 @@
  */
 
 import { CacheManager, type getExecutionContext } from "@databricks/appkit";
-import { stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import Fuse from "fuse.js";
 
 import type { ServingEndpointSummary } from "@dbx-tools/appkit-mastra-shared";
@@ -29,6 +29,8 @@ import type { MastraPluginConfig } from "./config.js";
 
 export type { ServingEndpointSummary };
 
+const log = logUtils.logger("mastra/serving");
+
 /**
  * Structural type for the Databricks workspace client. Derived from
  * AppKit's `ExecutionContext` so this module doesn't take a direct
@@ -111,6 +113,7 @@ export async function listServingEndpoints(
 async function fetchEndpoints(
   client: WorkspaceClientLike,
 ): Promise<ServingEndpointSummary[]> {
+  const startedAt = Date.now();
   const out: ServingEndpointSummary[] = [];
   for await (const ep of client.servingEndpoints.list()) {
     if (!ep.name) continue;
@@ -121,6 +124,7 @@ async function fetchEndpoints(
       ...(ep.description !== undefined ? { description: ep.description } : {}),
     });
   }
+  log.debug("listed", { count: out.length, elapsedMs: Date.now() - startedAt });
   return out;
 }
 
@@ -185,10 +189,12 @@ export function resolveModelId(
   opts: ResolveModelOptions = {},
 ): ResolvedModel {
   if (endpoints.length === 0) {
+    log.debug("resolve:no-endpoints", { input });
     return { modelId: input, matched: false };
   }
   for (const ep of endpoints) {
     if (ep.name === input) {
+      log.debug("resolve:exact", { input });
       return { modelId: ep.name, matched: true, score: 0 };
     }
   }
@@ -208,12 +214,25 @@ export function resolveModelId(
   const query = Array.from(
     stringUtils.tokenizeWithOptions({ lowerCase: true, camelCase: false }, input),
   ).join(" ");
-  if (!query) return { modelId: input, matched: false };
+  if (!query) {
+    log.debug("resolve:empty-tokens", { input });
+    return { modelId: input, matched: false };
+  }
   const results = fuse.search(query);
   const best = results[0];
   if (best?.item.name && (best.score ?? 0) <= threshold) {
+    log.debug("resolve:fuzzy-match", {
+      input,
+      modelId: best.item.name,
+      score: best.score,
+    });
     return { modelId: best.item.name, matched: true, score: best.score };
   }
+  log.debug("resolve:no-match", {
+    input,
+    bestScore: best?.score,
+    threshold,
+  });
   return { modelId: input, matched: false };
 }
 

package/src/tools/email.ts

@@ -0,0 +1,147 @@
+/**
+ * Mastra tool: `send_email`. Gated behind {@link requireApproval}
+ * so the model can call it freely but execution is paused until a
+ * human approves via the chat UI.
+ *
+ * The execute body is a stub - it logs the would-be email to the
+ * server console (via `logUtils.logger`) and returns success. Swap
+ * in a real SMTP / SES / Resend / Workspace Mail call later by
+ * editing the `execute` body; the tool surface and approval gate
+ * stay the same.
+ *
+ * Approval flow (Mastra + AI SDK V5):
+ *
+ * 1. Model calls the tool with `{ to, subject, body, ... }`.
+ * 2. Mastra evaluates `requireApproval` (here always `true`),
+ *    pauses the agent loop, and emits a `tool-call-approval`
+ *    chunk on the response stream.
+ * 3. The chat client renders an approve/deny prompt against the
+ *    `state: 'approval-requested'` tool part. On approve, it sends
+ *    a `MastraToolApproval` response back; on deny, the tool call
+ *    is rejected and the model sees an error.
+ * 4. On approve, this `execute` runs and logs the email.
+ *
+ * The tool is intentionally NOT auto-installed on every agent -
+ * email is domain-specific, not infrastructure. Spread it into the
+ * specific agents that should be able to draft emails.
+ */
+
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
+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`
+    Single recipient email address (e.g. "alice@example.com"). For
+    multiple recipients, comma-separate them yourself.
+  `),
+  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.
+  `),
+  cc: z
+    .array(z.string())
+    .optional()
+    .describe(stringUtils.toDescription`
+      Optional CC recipients.
+    `),
+  bcc: z
+    .array(z.string())
+    .optional()
+    .describe(stringUtils.toDescription`
+      Optional BCC recipients.
+    `),
+});
+
+const emailOutputSchema = z.object({
+  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`
+    Echo of the \`to\` field for confirmation.
+  `),
+});
+
+/** Options accepted by {@link buildEmailTool}. */
+export interface BuildEmailToolOptions {
+  /**
+   * Override the tool id. Defaults to `"send_email"`. Useful if a
+   * caller wants `send_internal_email` / `send_external_email`
+   * variants.
+   */
+  id?: string;
+  /**
+   * Replace the default execute body with a real provider call.
+   * Receives the validated input and must return `{sent, recipient}`.
+   * The console-log default is meant for demos / dev; production
+   * deployments should wire SMTP / SES / Resend / Workspace Mail
+   * here.
+   */
+  send?: (input: z.infer<typeof emailInputSchema>) => Promise<void> | void;
+}
+
+/**
+ * Build the `send_email` tool. Approval-gated by default; the
+ * execute body either calls the supplied {@link send} hook or
+ * logs the email to the server console as a demo stub.
+ *
+ * @example
+ * ```ts
+ * import { buildEmailTool, createAgent, mastra } from "@dbx-tools/appkit-mastra";
+ *
+ * const support = createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       ...(plugins.genie?.toolkit() ?? {}),
+ *       send_email: buildEmailTool(),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export function buildEmailTool(opts: BuildEmailToolOptions = {}) {
+  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.
+    `,
+    inputSchema: emailInputSchema,
+    outputSchema: emailOutputSchema,
+    requireApproval: true,
+    execute: async (input) => {
+      const { to, subject, body, cc, bcc } = input as z.infer<
+        typeof emailInputSchema
+      >;
+      // Default behaviour: dump the email to the server console so
+      // demos can see the gate fire end-to-end without a real
+      // provider. Replace by passing `opts.send`.
+      log.info("send", {
+        to,
+        ...(cc && cc.length > 0 ? { cc } : {}),
+        ...(bcc && bcc.length > 0 ? { bcc } : {}),
+        subject,
+        bodyLength: body.length,
+        body,
+      });
+      if (opts.send) {
+        await opts.send(input as z.infer<typeof emailInputSchema>);
+      }
+      return { sent: true, recipient: to };
+    },
+  });
+}

package/dist/src/render-chart-route.d.ts

@@ -1,33 +0,0 @@
-/**
- * Chart-render HTTP endpoint for the Mastra plugin.
- *
- * The `render_data` tool returns immediately with a `chartId` and
- * emits the dataset over `ctx.writer`; the client then POSTs that
- * dataset to this endpoint to actually run the chart-planner
- * agent and get back an Echarts `EChartsOption` JSON. Planning
- * happens out-of-band so the calling agent's response stream
- * doesn't sit idle waiting for it - the model can finish the
- * report while the client is still rendering charts.
- *
- * Auth flows through the standard Mastra middleware: the route
- * sits in the same dispatcher pipeline as `chatRoute` /
- * `historyRoute`, so by the time the handler runs the
- * `RequestContext` is populated with the workspace user and
- * the chart-planner's model resolver has the OBO token it
- * needs.
- */
-import type { MastraPluginConfig } from "./config.js";
-/** Options accepted by {@link renderChartRoute}. */
-export interface RenderChartRouteOptions {
-    path: string;
-    config: MastraPluginConfig;
-}
-/**
- * Register a `POST <path>` Mastra custom API route that runs the
- * chart-planner agent against a dataset and returns an Echarts
- * `EChartsOption` JSON.
- *
- * Body shape: {@link RenderChartRequest}; response:
- * {@link RenderChartResponse}.
- */
-export declare function renderChartRoute(options: RenderChartRouteOptions): import("@mastra/core/server").ApiRoute;

package/dist/src/render-chart-route.js

@@ -1,120 +0,0 @@
-/**
- * Chart-render HTTP endpoint for the Mastra plugin.
- *
- * The `render_data` tool returns immediately with a `chartId` and
- * emits the dataset over `ctx.writer`; the client then POSTs that
- * dataset to this endpoint to actually run the chart-planner
- * agent and get back an Echarts `EChartsOption` JSON. Planning
- * happens out-of-band so the calling agent's response stream
- * doesn't sit idle waiting for it - the model can finish the
- * report while the client is still rendering charts.
- *
- * Auth flows through the standard Mastra middleware: the route
- * sits in the same dispatcher pipeline as `chatRoute` /
- * `historyRoute`, so by the time the handler runs the
- * `RequestContext` is populated with the workspace user and
- * the chart-planner's model resolver has the OBO token it
- * needs.
- */
-import { registerApiRoute } from "@mastra/core/server";
-import { runChartPlanner } from "./chart.js";
-/** Hard cap so a misbehaving client can't hand us a million-row payload. */
-const MAX_ROWS = 5_000;
-/**
- * Hard cap on the JSON body the route accepts (in bytes). Mirrors
- * the same intent as {@link MAX_ROWS}: bound the chart-planner's
- * prompt size and protect against accidental denial-of-service
- * from a runaway tool that ships an enormous payload.
- */
-const MAX_BODY_BYTES = 2 * 1024 * 1024;
-/**
- * Register a `POST <path>` Mastra custom API route that runs the
- * chart-planner agent against a dataset and returns an Echarts
- * `EChartsOption` JSON.
- *
- * Body shape: {@link RenderChartRequest}; response:
- * {@link RenderChartResponse}.
- */
-export function renderChartRoute(options) {
-    const { path, config } = options;
-    return registerApiRoute(path, {
-        method: "POST",
-        handler: async (c) => {
-            const requestContext = c.get("requestContext");
-            // Hono parses the body as JSON; we still validate shape /
-            // size since the tool's structured output is a contract,
-            // not a guarantee, and the route is publicly mountable.
-            const raw = (await c.req.json().catch(() => null));
-            const validation = validateBody(raw);
-            if ("error" in validation) {
-                return c.json({ error: validation.error }, 400);
-            }
-            const { title, description, data } = validation.body;
-            try {
-                const result = await runChartPlanner({
-                    config,
-                    ...(requestContext ? { requestContext } : {}),
-                    title,
-                    ...(description ? { description } : {}),
-                    data,
-                });
-                const payload = {
-                    option: result.option,
-                    chartType: result.chartType,
-                };
-                return c.json(payload);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return c.json({ error: message }, 500);
-            }
-        },
-    });
-}
-/**
- * Best-effort body validation. Surfaces a 400 for malformed input
- * instead of letting a downstream `.map` / `.length` blow up
- * inside the planner agent. Field-level shape mirrors
- * {@link RenderChartRequest}.
- */
-function validateBody(raw) {
-    if (!raw || typeof raw !== "object") {
-        return { error: "request body must be a JSON object" };
-    }
-    const r = raw;
-    const title = r.title;
-    if (typeof title !== "string" || title.length === 0) {
-        return { error: "`title` must be a non-empty string" };
-    }
-    if (r.description !== undefined && typeof r.description !== "string") {
-        return { error: "`description` must be a string when provided" };
-    }
-    if (!Array.isArray(r.data)) {
-        return { error: "`data` must be an array of row objects" };
-    }
-    if (r.data.length === 0) {
-        return { error: "`data` must contain at least one row" };
-    }
-    if (r.data.length > MAX_ROWS) {
-        return { error: `\`data\` exceeds the per-request limit of ${MAX_ROWS} rows` };
-    }
-    for (const [i, row] of r.data.entries()) {
-        if (!row || typeof row !== "object" || Array.isArray(row)) {
-            return { error: `data[${i}] must be a plain object` };
-        }
-    }
-    // Approximate body-size check; spares us pulling Buffer in.
-    const approximateBytes = JSON.stringify(r.data).length;
-    if (approximateBytes > MAX_BODY_BYTES) {
-        return {
-            error: `\`data\` exceeds the per-request size limit of ${MAX_BODY_BYTES} bytes`,
-        };
-    }
-    return {
-        body: {
-            title,
-            ...(typeof r.description === "string" ? { description: r.description } : {}),
-            data: r.data,
-        },
-    };
-}