@dbx-tools/appkit-mastra 0.1.26 → 0.1.27

package/package.json

@@ -9,13 +9,13 @@
     }
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@dbx-tools/appkit-mastra-shared": "0.1.26",
-    "@dbx-tools/genie": "0.1.26",
-    "@dbx-tools/genie-shared": "0.1.26",
-    "@dbx-tools/shared": "0.1.26",
+    "@dbx-tools/appkit-mastra-shared": "0.1.27",
+    "@dbx-tools/genie": "0.1.27",
+    "@dbx-tools/genie-shared": "0.1.27",
+    "@dbx-tools/shared": "0.1.27",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",

package/src/agents.ts

@@ -431,7 +431,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];

package/src/chart.ts

@@ -238,13 +238,11 @@ type ChartPlan = z.infer<typeof chartPlanSchema>;
  * sees a planner request, only the resolved {@link Chart}.
  */
 export const chartPlannerRequestSchema = z.object({
-  title: z
-    .string()
-    .describe(
-      stringUtils.toDescription(`
+  title: z.string().describe(
+    stringUtils.toDescription(`
         Concise title shown above the chart (e.g. "Top 10 SKUs by Revenue").
       `),
-    ),
+  ),
   description: z
     .string()
     .optional()
@@ -676,7 +674,7 @@ function planToEchartsOption(
  * an empty placeholder, and kicks off the chart-planner in the
  * background. Returns just the `chartId`; the host UI resolves
  * `[chart:<chartId>]` markers by hitting the plugin's
- * `/charts/:chartId` route.
+ * `/embed/chart/:id` route.
  *
  * For Genie statement results, prefer the Genie agent's
  * `prepare_chart` tool, which accepts a `statement_id` and

package/src/config.ts

@@ -216,7 +216,7 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * processor that strips `chartId` fields from prior assistant
    * tool-invocation results before they reach the model. This
    * prevents the model from reusing turn-scoped chartIds it sees
-   * in memory recall (which would leave `[[chart:<id>]]` markers
+   * in memory recall (which would leave `[chart:<id>]` markers
    * pointing at writer events that no longer exist).
    *
    * Set to `false` to opt out - useful if a non-default agent

package/src/genie.ts

@@ -725,9 +725,13 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
       `
         To display the chart in your reply, embed
         \`[chart:<chartId>]\` on its own line at the position you
-        want it to appear. The tool returns immediately - do NOT
-        wait or call it again to "check progress"; the chart
-        resolves asynchronously on the host UI's side.
+        want it to appear, using the EXACT \`chartId\` string this
+        call returned. Never construct a chart id yourself (it is
+        not the \`statement_id\` or any variation of it) - only a
+        value returned by this tool resolves to a real chart. The
+        tool returns immediately - do NOT wait or call it again to
+        "check progress"; the chart resolves asynchronously on the
+        host UI's side.
       `,
       `
         Use this only when the data has a story a chart conveys
@@ -842,6 +846,17 @@ export const GENIE_INSTRUCTIONS = stringUtils.toDescription([
               chart should appear. Use a chart when the data has a
               story a visual conveys better than a table (trends,
               rankings, distributions, parts-of-a-whole).
+
+              NEVER invent or hand-build a \`<chartId>\`. A valid
+              \`<chartId>\` is the opaque token a \`prepare_chart\`
+              call returned to you in THIS turn - nothing else. It
+              is NOT a \`statement_id\`, and it is NOT a
+              \`statement_id\` prefix with a label appended (e.g.
+              \`01f1...-region-fill\`). If you have not called
+              \`prepare_chart\` and received an id back, do not write
+              a \`[chart:...]\` marker at all - use \`[data:...]\`
+              instead. A fabricated chart id renders nothing and
+              wastes a request.
             `,
           ],
         },

package/src/intercept.ts

@@ -0,0 +1,206 @@
+/**
+ * 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";
+
+import type express from "express";
+
+/** 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*)$/;
+
+/**
+ * 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;
+
+/**
+ * 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: express.Response): boolean {
+  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: string,
+  interceptor: StreamFrameInterceptor,
+): string | undefined {
+  const match = DATA_OBJECT_RE.exec(frame);
+  if (!match) return frame;
+  const [, prefix, body, suffix] = match;
+  let parsed: unknown;
+  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: express.Response,
+  interceptor: StreamFrameInterceptor,
+): void {
+  const origWrite = res.write.bind(res);
+  const origEnd = res.end.bind(res);
+  const decoder = new StringDecoder("utf8");
+  let engaged: boolean | undefined;
+  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: string, final: boolean): string => {
+    buffer += text;
+
+    const out: string[] = [];
+
+    let idx: number;
+    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: unknown): string => {
+    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: unknown,
+    encodingOrCb?: BufferEncoding | ((error?: Error | null) => void),
+    cb?: (error?: Error | null) => void,
+  ): boolean {
+    if (engaged === undefined) engaged = isEventStream(res);
+    if (!engaged) {
+      return origWrite(chunk as never, encodingOrCb as never, cb as never);
+    }
+    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 as never);
+  } as typeof res.write;
+
+  res.end = function patchedEnd(
+    chunk?: unknown | (() => void),
+    encodingOrCb?: BufferEncoding | (() => void),
+    cb?: () => void,
+  ): express.Response {
+    if (engaged === undefined) engaged = isEventStream(res);
+    if (!engaged) {
+      return origEnd(chunk as never, encodingOrCb as never, cb as never);
+    }
+    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 as never);
+  } as typeof res.end;
+}

package/src/plugin.ts

@@ -37,7 +37,7 @@ import {
   type PluginManifest,
   type ResourceRequirement,
 } 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 type { Agent } from "@mastra/core/agent";
 import { Mastra } from "@mastra/core/mastra";
@@ -54,6 +54,10 @@ import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { buildObservability } from "./observability.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
+import {
+  installStreamEventInterceptor,
+  type StreamFrameInterceptor,
+} from "./intercept.js";
 import {
   clearServingEndpointsCache,
   listServingEndpoints,
@@ -208,8 +212,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       modelsPath: `${basePath}/models`,
       historyPath: `${basePath}/route/history`,
       historyPathTemplate: `${basePath}/route/history/:agentId`,
-      chartsPathTemplate: `${basePath}/charts/:chartId`,
-      statementsPathTemplate: `${basePath}/statements/:statementId`,
+      embedPathTemplate: `${basePath}/embed/:type/:id`,
       defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
       agents: Object.keys(this.built?.agents ?? {}),
     };
@@ -229,114 +232,97 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         .catch(next);
     });
 
-    // `GET /charts/:chartId` long-polls the chart cache.
-    //
-    // Charts kicked off by the Genie agent's `prepare_chart` tool
-    // (or the system `render_data` tool) resolve asynchronously
-    // and land in the AppKit cache under a chartId. The host UI
-    // resolves `[chart:<chartId>]` markers by hitting this route,
-    // which blocks until the entry settles (`result` or `error`
-    // set) or the server-side budget elapses (then returns the
-    // last seen still-processing entry so the client can poll
-    // again).
+    // `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 JSON body when the entry is found (any state).
-    //   - 404 when the chartId doesn't exist or its 1h TTL elapsed.
+    //   - 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.
     //
-    // Query params:
-    //   - `timeoutMs` (optional, default 60000): how long to long-poll
-    //     before returning a still-processing entry.
+    // 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).
     //
-    // Wired with `req.signal` so a closed connection unblocks the
-    // poll immediately and the request thread frees up. Cache
-    // failures bubble through `next(err)` to Express's default
-    // error handler.
-    router.get("/charts/:chartId", (req, res, next) => {
-      const chartId = req.params["chartId"];
-      if (!chartId) {
-        res.status(400).json({ error: "chartId is required" });
+    // 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: Record<string, EmbedResolver> = {
+      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;
       }
-      const timeoutMs = parseTimeoutMs(req.query["timeoutMs"]);
-      // Express's `req` predates `AbortSignal`. Bridge the
-      // `close` event onto an `AbortController` so a closed
-      // connection unblocks the long-poll immediately and frees
-      // the request thread. The `close` listener also fires on
-      // a normal completion, but at that point we no longer
-      // care about the abort and the listener is GC'd with the
-      // request.
-      const controller = new AbortController();
-      req.on("close", () => controller.abort());
-      fetchChart(chartId, {
-        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-        signal: controller.signal,
-      })
-        .then((entry) => {
-          if (!entry) {
-            res.status(404).json({ error: "chart not found" });
-            return;
-          }
-          res.json(entry);
-        })
-        .catch(next);
-    });
-
-    // `GET /statements/:statementId` resolves a Genie / Statement
-    // Execution result for inline rendering as a table.
-    //
-    // The agent embeds `[data:<statement_id>]` markers in prose
-    // (see `GENIE_INSTRUCTIONS`) whenever it wants the host UI to
-    // display a result set without the model re-spelling every
-    // row in markdown. This route is what those markers resolve
-    // against - one OBO-scoped fetch returns the columns + rows
-    // so the client renders an AppKit Table inline.
-    //
-    // Status codes:
-    //   - 200 with `StatementData` body when the statement is found.
-    //   - 404 when the workspace can't find / read the statement.
-    //
-    // Query params:
-    //   - `limit` (optional): row cap. Clamped to
-    //     {@link STATEMENT_ROW_CAP} so a runaway result set
-    //     can't hose the response.
-    //
-    // OBO-scoped via {@link userScopedSelf} so the caller's
-    // workspace permissions apply; SDK errors propagate through
-    // `next(err)` to Express's default error handler.
-    router.get("/statements/:statementId", (req, res, next) => {
-      const statementId = req.params["statementId"];
-      if (!statementId) {
-        res.status(400).json({ error: "statementId is required" });
+      if (!id) {
+        res.status(400).json({ error: "id is required" });
         return;
       }
-      const limit = parseStatementLimit(req.query["limit"]);
+      // 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());
-      this.userScopedSelf(req)
-        .fetchStatement(statementId, {
-          ...(limit !== undefined ? { limit } : {}),
-          signal: controller.signal,
-        })
-        .then((data) => {
-          if (!data) {
-            res.status(404).json({ error: "statement not found" });
+      resolve(req, id, controller.signal)
+        .then((entry) => {
+          if (entry === undefined) {
+            res.status(404).json({ error: `${type} not found` });
             return;
           }
-          res.json(data);
+          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 `/statements/:statementId` route.
-   * Runs inside the AppKit user-context proxy so
+   * 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
@@ -472,9 +458,22 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
   }
 }
 
+/**
+ * Resolver for one embed `<type>` behind the generic
+ * `GET /embed/:type/:id` route. Returns the JSON body to send on
+ * success, or `undefined` to signal a 404 (unknown / expired id).
+ * `signal` aborts when the client disconnects so long-polling
+ * resolvers (e.g. `chart`) unblock immediately.
+ */
+type EmbedResolver = (
+  req: express.Request,
+  id: string,
+  signal: AbortSignal,
+) => Promise<unknown | undefined>;
+
 /**
  * Parse the optional `?timeoutMs=<n>` query parameter from a
- * `GET /charts/:chartId` request. Accepts a positive integer up
+ * `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
@@ -490,7 +489,7 @@ function parseTimeoutMs(raw: unknown): number | undefined {
 
 /**
  * Parse the optional `?limit=<n>` query parameter from a
- * `GET /statements/:statementId` request. Accepts a non-negative
+ * `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.
@@ -503,4 +502,36 @@ function parseStatementLimit(raw: unknown): number | 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: StreamFrameInterceptor = (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/src/statement.ts

@@ -3,7 +3,7 @@
  *
  * Wraps `client.statementExecution.getStatement` with the shape
  * + size + error handling the plugin's tools and the
- * `/statements/:statementId` route both need:
+ * `/embed/data/:id` route both need:
  *
  *   - {@link fetchStatementData}: low-level fetch that returns the
  *     raw `{columns, rows, rowCount}` shape used by the
@@ -12,7 +12,7 @@
  *     numeric strings to numbers so downstream charts /
  *     aggregations don't have to.
  *   - {@link STATEMENT_ROW_CAP}: hard cap callers (notably the
- *     `/statements/:statementId` route) clamp `limit` to so a
+ *     `/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
@@ -33,7 +33,7 @@ import { apiUtils } from "@dbx-tools/shared";
 
 /**
  * Hard server-side cap on rows returned by the
- * `/statements/:statementId` route. Sized to keep responses small
+ * `/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.
@@ -66,7 +66,7 @@ function coerceCell(cell: string | null): unknown {
  *
  * Exported because every consumer in the plugin (the
  * `get_statement` tool, the `prepare_chart` dataset resolver, and
- * the `/statements/:statementId` route) needs the exact same
+ * 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`.
@@ -110,7 +110,7 @@ export async function fetchStatementData(
  * catalogued.
  *
  * Pulled into its own helper so callers (notably the
- * `/statements/:statementId` route) stay decoupled from SDK
+ * `/embed/data/:id` route) stay decoupled from SDK
  * error-class identity, and the conversion logic stays testable
  * in isolation.
  */