@dbx-tools/appkit-mastra 0.1.26 → 0.1.28

package/README.md

@@ -199,7 +199,7 @@ once regardless of how many spaces are wired:
   Genie statement. Use only when the agent needs to read values
   to reason about them; otherwise embed `[data:<statement_id>]`.
 - `prepare_chart({statement_id, title?, description?})` - mint a
-  short `chartId`, kick off a background chart-planner task,
+  `chartId` (v4 UUID), kick off a background chart-planner task,
   cache the resolved Echarts spec under the id for one hour.
   Returns `{chartId}` synchronously so the agent can embed
   `[chart:<chartId>]` in prose without blocking.
@@ -254,8 +254,9 @@ Genie writer event flow:
 - Charts ride out-of-band: `prepare_chart` mints a `chartId`
   synchronously, the planner runs in the background and writes
   the spec to the chart cache (1h TTL). The host UI long-polls
-  `${MastraClientConfig.chartsPathTemplate}` by id and renders
-  inline at the matching `[chart:<chartId>]` marker.
+  `${MastraClientConfig.embedPathTemplate}` (`/embed/chart/:id`)
+  by id and renders inline at the matching `[chart:<chartId>]`
+  marker.
 - After a hard reload, the live `started` / `status` / `sql`
   events are gone (they only ride the writer, not persisted
   tool results); the central agent's text reply (with embedded
@@ -285,7 +286,7 @@ off the chart-planner in the background. The tool returns just
 `{ chartId }` so the model can embed `[chart:<chartId>]` in
 prose immediately without blocking on chart generation.
 
-1. Mint a short `chartId` (8 hex chars).
+1. Mint a `chartId` (v4 UUID via `crypto.randomUUID()`).
 2. Cache an empty `{ chartId }` placeholder so the first
    `fetchChart` call always sees an entry (no spurious 404 race).
 3. Fire-and-forget: resolve the dataset (trivial for
@@ -297,26 +298,27 @@ prose immediately without blocking on chart generation.
 4. Return `{ chartId }` to the LLM immediately.
 
 The host UI resolves `[chart:<chartId>]` markers by hitting
-the plugin's `GET /charts/:chartId` route, which long-polls
+the plugin's generic `GET /embed/chart/:id` route, which long-polls
 until the entry settles or the server-side timeout elapses.
 
 #### Inline placement contract
 
-The model embeds `[[chart:<chartId>]]` on its own line in its
-markdown reply at the position where the chart should appear:
+The model embeds `[chart:<chartId>]` on its own line in its
+markdown reply at the position where the chart should appear
+(the `<chartId>` is the v4 UUID the tool returned):
 
 ```markdown
 ## Audit Score
 
 Audit Score is stable at ~94%, hovering between 93.5 and 95.0.
 
-[[chart:a3f9c1d2]]
+[chart:a3f9c1d2-7b4e-4c1a-9f2d-1e6b8c0a5d31]
 
 ## Service Time
 
 Service time is the outlier at 162.5s, up from a target of 150s.
 
-[[chart:b7e2d4f1]]
+[chart:b7e2d4f1-3a9c-4e58-8d10-2f7a4b6c9e02]
 ```
 
 The chat client splits the assistant text on these markers and
@@ -330,7 +332,7 @@ frame so the layout doesn't jump as charts resolve.
 #### Trade-offs
 
 - Chart entries live in the cache with a 1h TTL. After expiry
-  the `/charts/:chartId` route returns 404. The model can call
+  the `/embed/chart/:id` route returns 404. The model can call
   `render_data` again on the next turn if the user wants the
   chart back.
 - The chart-planner is a separate model call per dataset (fast

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 /**
- * AppKit Mastra integration: {@link MastraPlugin} / {@link mastra},
- * plugin config types, agent registration helpers, Genie tool
- * builders, and dynamic Model Serving endpoint resolution.
+ * Server-side entry point for the AppKit Mastra integration. Mounts
+ * the plugin via {@link mastra} and re-exports the full server surface
+ * (config, agent wiring, Genie and chart tooling, and dynamic Model
+ * Serving resolution) so apps build agent backends from one import.
  *
  * Client-side consumers should import URL helpers and the
  * {@link MastraClientConfig} type from `@dbx-tools/appkit-mastra-shared`

package/dist/index.js

@@ -1,7 +1,8 @@
 /**
- * AppKit Mastra integration: {@link MastraPlugin} / {@link mastra},
- * plugin config types, agent registration helpers, Genie tool
- * builders, and dynamic Model Serving endpoint resolution.
+ * Server-side entry point for the AppKit Mastra integration. Mounts
+ * the plugin via {@link mastra} and re-exports the full server surface
+ * (config, agent wiring, Genie and chart tooling, and dynamic Model
+ * Serving resolution) so apps build agent backends from one import.
  *
  * Client-side consumers should import URL helpers and the
  * {@link MastraClientConfig} type from `@dbx-tools/appkit-mastra-shared`

package/dist/src/agents.js

@@ -188,7 +188,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];
     const agents = {};

package/dist/src/chart.d.ts

@@ -20,18 +20,9 @@
  * dataset, custom API). The module has no knowledge of Genie or
  * statement ids; those concerns live in the tools that wrap it.
  *
- * Wire-format schemas (`ChartSchema`, `ChartResultSchema`,
- * {@link ChartTypeSchema}) live in
- * `@dbx-tools/appkit-mastra-shared` so the demo client and any
- * other UI consumer share the exact same shape this module reads
- * and writes.
- *
- * Public surface (everything else is module-private):
- *   - {@link chartPlannerRequestSchema} / {@link ChartPlannerRequest}
- *   - {@link prepareChart} / {@link PrepareChartOptions}
- *   - {@link fetchChart} / {@link FetchChartOptions}
- *   - {@link buildRenderDataTool} (the `render_data` Mastra tool
- *     auto-wired on every agent in `agents.ts`)
+ * Wire-format schemas live in `@dbx-tools/appkit-mastra-shared` so
+ * the demo client and any other UI consumer share the exact same
+ * shape this module reads and writes.
  */
 import { type Chart } from "@dbx-tools/appkit-mastra-shared";
 import type { RequestContext } from "@mastra/core/request-context";
@@ -147,7 +138,7 @@ export declare function fetchChart(chartId: string, options?: FetchChartOptions)
  * 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/dist/src/chart.js

@@ -20,18 +20,9 @@
  * dataset, custom API). The module has no knowledge of Genie or
  * statement ids; those concerns live in the tools that wrap it.
  *
- * Wire-format schemas (`ChartSchema`, `ChartResultSchema`,
- * {@link ChartTypeSchema}) live in
- * `@dbx-tools/appkit-mastra-shared` so the demo client and any
- * other UI consumer share the exact same shape this module reads
- * and writes.
- *
- * Public surface (everything else is module-private):
- *   - {@link chartPlannerRequestSchema} / {@link ChartPlannerRequest}
- *   - {@link prepareChart} / {@link PrepareChartOptions}
- *   - {@link fetchChart} / {@link FetchChartOptions}
- *   - {@link buildRenderDataTool} (the `render_data` Mastra tool
- *     auto-wired on every agent in `agents.ts`)
+ * Wire-format schemas live in `@dbx-tools/appkit-mastra-shared` so
+ * the demo client and any other UI consumer share the exact same
+ * shape this module reads and writes.
  */
 import { CacheManager } from "@databricks/appkit";
 import { ChartSchema, ChartTypeSchema, } from "@dbx-tools/appkit-mastra-shared";
@@ -199,9 +190,7 @@ const chartPlanSchema = z.object({
  * 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
@@ -530,7 +519,7 @@ function planToEchartsOption(plan, fallbackTitle) {
  * 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/dist/src/config.d.ts

@@ -191,7 +191,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/dist/src/genie.d.ts

@@ -1,41 +1,19 @@
 /**
  * Genie tools for Mastra.
  *
- * Each configured Genie space is surfaced as a small set of flat
- * Mastra tools the calling agent can drive directly - no inner
- * orchestrator agent. The central agent decomposes user questions,
- * picks which Genie space to ask, and composes the final reply.
- *
- * Per-space tools (suffixed with `_<alias>` for non-default
- * aliases):
- *
- *   - `ask_genie`: drives one `genieEventChat` turn and
- *     forwards every wire event (status, thinking, sql, rows)
- *     through `ctx.writer` for streaming UI updates. Returns
- *     the terminal `GenieMessage` only - rows are NOT fetched
- *     eagerly.
- *   - `get_space_description`: cheap title / description /
- *     warehouse id lookup for grounding.
- *   - `get_space_serialized`: full `GenieSpace` JSON for
- *     column-level grounding when the description isn't enough.
- *
- * Space-agnostic shared tools (registered once, regardless of
- * how many spaces are wired):
- *
- *   - `get_statement`: opt-in lookup of a Genie statement's rows
- *     by `statement_id` (with a row `limit`). The agent calls
- *     this only when it needs to read values to reason about
- *     them; if the data is just being displayed, it embeds a
- *     `[data:<statement_id>]` marker in prose instead and lets
- *     the host UI resolve it.
- *   - `prepare_chart`: mints a short `chartId`, kicks off a
- *     background task that fetches the statement's rows and
- *     runs the chart-planner, and caches the resolved Echarts
- *     spec under the id (1h TTL). Returns the `chartId`
- *     synchronously so the agent embeds `[chart:<chartId>]`
- *     markers in prose without blocking on chart generation;
- *     the host UI fetches the cached chart by id once it's
- *     ready (see {@link fetchChart}).
+ * Surfaces each configured Genie space as a small set of flat Mastra
+ * tools the calling agent drives directly - no inner orchestrator
+ * agent. The central agent decomposes user questions, picks which
+ * space to ask, streams the per-turn wire events (status, thinking,
+ * sql, rows) through `ctx.writer`, and composes the final reply.
+ * Rows are never fetched eagerly: the agent reads a statement's
+ * values only when it needs to reason about them, otherwise it embeds
+ * a `[data:<statement_id>]` marker in prose and lets the host UI
+ * resolve the data. Charts are minted asynchronously and referenced
+ * by `[chart:<chartId>]` markers so prose isn't blocked on chart
+ * generation; the host UI fetches the cached spec by id once ready.
+ * Space description and serialized-space lookups are available for
+ * grounding when the agent needs schema context.
  *
  * Each tool's `execute` pulls the per-request
  * {@link WorkspaceClient} off `ctx.requestContext` (stamped by

package/dist/src/genie.js

@@ -1,41 +1,19 @@
 /**
  * Genie tools for Mastra.
  *
- * Each configured Genie space is surfaced as a small set of flat
- * Mastra tools the calling agent can drive directly - no inner
- * orchestrator agent. The central agent decomposes user questions,
- * picks which Genie space to ask, and composes the final reply.
- *
- * Per-space tools (suffixed with `_<alias>` for non-default
- * aliases):
- *
- *   - `ask_genie`: drives one `genieEventChat` turn and
- *     forwards every wire event (status, thinking, sql, rows)
- *     through `ctx.writer` for streaming UI updates. Returns
- *     the terminal `GenieMessage` only - rows are NOT fetched
- *     eagerly.
- *   - `get_space_description`: cheap title / description /
- *     warehouse id lookup for grounding.
- *   - `get_space_serialized`: full `GenieSpace` JSON for
- *     column-level grounding when the description isn't enough.
- *
- * Space-agnostic shared tools (registered once, regardless of
- * how many spaces are wired):
- *
- *   - `get_statement`: opt-in lookup of a Genie statement's rows
- *     by `statement_id` (with a row `limit`). The agent calls
- *     this only when it needs to read values to reason about
- *     them; if the data is just being displayed, it embeds a
- *     `[data:<statement_id>]` marker in prose instead and lets
- *     the host UI resolve it.
- *   - `prepare_chart`: mints a short `chartId`, kicks off a
- *     background task that fetches the statement's rows and
- *     runs the chart-planner, and caches the resolved Echarts
- *     spec under the id (1h TTL). Returns the `chartId`
- *     synchronously so the agent embeds `[chart:<chartId>]`
- *     markers in prose without blocking on chart generation;
- *     the host UI fetches the cached chart by id once it's
- *     ready (see {@link fetchChart}).
+ * Surfaces each configured Genie space as a small set of flat Mastra
+ * tools the calling agent drives directly - no inner orchestrator
+ * agent. The central agent decomposes user questions, picks which
+ * space to ask, streams the per-turn wire events (status, thinking,
+ * sql, rows) through `ctx.writer`, and composes the final reply.
+ * Rows are never fetched eagerly: the agent reads a statement's
+ * values only when it needs to reason about them, otherwise it embeds
+ * a `[data:<statement_id>]` marker in prose and lets the host UI
+ * resolve the data. Charts are minted asynchronously and referenced
+ * by `[chart:<chartId>]` markers so prose isn't blocked on chart
+ * generation; the host UI fetches the cached spec by id once ready.
+ * Space description and serialized-space lookups are available for
+ * grounding when the agent needs schema context.
  *
  * Each tool's `execute` pulls the per-request
  * {@link WorkspaceClient} off `ctx.requestContext` (stamped by
@@ -614,9 +592,13 @@ function buildPrepareChartTool(opts) {
             `
         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
@@ -728,6 +710,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/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

@@ -110,8 +110,8 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
     clientConfig(): Record<string, unknown>;
     injectRoutes(router: IAppRouter): void;
     /**
-     * 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