@dbx-tools/appkit-mastra 0.6.218 → 0.6.219

package/src/processors.ts

@@ -1,21 +1,15 @@
 /**
  * Mastra stream processors wired onto the plugin's agents.
  *
- * Two complementary processors live here:
- *
- * - An **input** processor ({@link stripStaleChartsProcessor}) that
- *   scrubs turn-scoped `chartId` fields out of prior tool results
- *   replayed from Memory, so the model can't copy a stale id into the
- *   new turn's `[chart:<id>]` markers.
- * - An **output** processor ({@link ResultProcessor}) that trims the
- *   bulky, redundant payload fields off targeted outbound stream frames
- *   before they're serialized to the SSE client.
+ * The input processor ({@link stripStaleChartsProcessor}) scrubs turn-scoped
+ * `chartId` fields out of prior tool results replayed from Memory, so the model
+ * cannot copy a stale id into the new turn's `[chart:<id>]` markers.
  *
  * @module
  */
 
 import { log } from "@dbx-tools/shared-core";
-import type { InputProcessor, ProcessInputArgs, Processor } from "@mastra/core/processors";
+import type { InputProcessor, ProcessInputArgs } from "@mastra/core/processors";
 
 const logger = log.logger("mastra/processors");
 
@@ -112,59 +106,3 @@ export const stripStaleChartsProcessor: InputProcessor = {
     return args.messages;
   },
 };
-
-/**
- * Mastra output processor that trims the bulky, redundant payload
- * fields off targeted outbound stream frames.
- *
- * Mastra emits step / finish / tool-result frames whose payloads
- * echo the full tool `output` / `result` / assistant `messages` /
- * `response` - data the chat client already received inline and
- * doesn't need re-sent. This processor empties those keys on the
- * targeted frame types so the outbound SSE stream stays lean;
- * every other frame passes through untouched.
- */
-export class ResultProcessor implements Processor {
-  id = "result-processor";
-
-  // Tell Mastra to also route tool/data parts to this processor method
-  processDataParts = true;
-
-  async processOutputStream({ part }: { part: any }): Promise<any | null> {
-    // 1. Guard clause: Ensure the chunk is a valid object
-    if (!part || typeof part !== "object") {
-      return part;
-    }
-
-    // 2. Filter for the targeted frame types
-    const targetedTypes = ["step-finish", "finish", "tool-result", "data-tool-agent"];
-    if (!targetedTypes.includes(part.type)) {
-      return part; // Return unchanged to pass-through
-    }
-
-    // 3. Check for the presence of a payload object
-    const payload = part.payload;
-    if (!payload || typeof payload !== "object") {
-      return part;
-    }
-
-    // 4. Safely delete the unwanted keys from the payload reference
-    const keysToDelete = ["output", "messages", "response", "result"];
-    for (const key of keysToDelete) {
-      if (key in payload) {
-        const value = payload[key];
-        if (typeof value === "object") {
-          payload[key] = {};
-        } else if (Array.isArray(value)) {
-          payload[key] = [];
-        } else {
-          delete payload[key];
-        }
-      }
-    }
-
-    // 5. Return the modified part object. Mastra handles re-serialization
-    // for the outbound SSE client stream automatically.
-    return part;
-  }
-}

package/src/server.ts

@@ -1,8 +1,6 @@
 /**
  * Express-layer plumbing for the Mastra plugin: a `MastraServer` that
- * stamps the per-request `RequestContext`, and a route-patch middleware
- * that lets the plugin's custom API routes (e.g. `historyRoute`) work
- * behind an Express mount point.
+ * stamps the per-request `RequestContext` and a scoped native API gate.
  *
  * @module
  */
@@ -44,6 +42,23 @@ import {
  * attach feedback to.
  */
 const INVALID_TRACE_ID = "0".repeat(32);
+const TRUSTED_REQUEST_CONTEXT_KEYS = [
+  MASTRA_RESOURCE_ID_KEY,
+  MASTRA_THREAD_ID_KEY,
+  MASTRA_USER_KEY,
+  MASTRA_USER_NAME_KEY,
+  MASTRA_USER_EMAIL_KEY,
+  MASTRA_REQUEST_ID_KEY,
+  MASTRA_SCOPES_KEY,
+  MASTRA_MODEL_OVERRIDE_KEY,
+] as const;
+
+/** Remove browser-supplied values for fields owned by trusted server middleware. */
+export function clearTrustedRequestContext(requestContext: RequestContext): void {
+  for (const key of TRUSTED_REQUEST_CONTEXT_KEYS) {
+    requestContext.deleteRaw(key);
+  }
+}
 
 /**
  * Who a turn is ATTRIBUTED to, independent of which Databricks credential runs
@@ -173,6 +188,7 @@ export class MastraServer extends ExpressMastraServer {
     super.registerAuthMiddleware();
     this.app.use(async (req, res, next) => {
       const requestContext = res.locals.requestContext! as RequestContext;
+      clearTrustedRequestContext(requestContext);
       await this.configureRequestContextUser(req, requestContext);
       this.configureRequestContextThreadId(req, res, requestContext);
       this.configureRequestContextModelOverride(req, requestContext);
@@ -268,7 +284,7 @@ export class MastraServer extends ExpressMastraServer {
   /**
    * Resolve the thread id this request targets and pin it on
    * `RequestContext` (consumed by the agent stream for persistence and
-   * by the history / threads routes). Resolution order:
+   * by native memory routes). Resolution order:
    *
    *   1. A client-supplied thread id (the thread-selection header /
    *      `?threadId=` query). This is how the chat UI references a
@@ -365,26 +381,34 @@ export interface MastraApiGateOptions {
  * prefix their `-generate` non-streaming variants), the `-network-` variants,
  * and `resume-stream` (covers `resume-stream-until-idle`). Without these an
  * approval-gated tool (e.g. `send_email`) can be requested but never approved
- * from the browser - the resume `POST` 403s under scoped mode. These are the
- * only *writes* the browser client is allowed to make against stock Mastra.
+ * from the browser - the resume `POST` 403s under scoped mode. Together with
+ * the resource-scoped memory mutations below, these are the only stock Mastra
+ * writes the browser client can make.
  */
 const AGENT_INFERENCE =
   /^\/agents\/[^/]+\/(stream|generate|network|resume-stream|approve-tool-call|decline-tool-call|approve-network-tool-call|decline-network-tool-call)/i;
 
 /** Mount-relative read-only agent metadata (`/agents`, `/agents/:id`). */
 const AGENT_METADATA = /^\/agents(\/[^/]+)?$/;
+/** Persisted approval discovery for one agent. */
+const AGENT_SUSPENDED_RUNS = /^\/agents\/[^/]+\/suspended-runs$/i;
+/** Official AI SDK UI stream route, including `resumeData` continuations. */
+const AGENT_CHAT = /^\/chat\/[^/]+$/i;
+/** Native resource-scoped memory reads used by history and the thread list. */
+const MEMORY_READ = /^\/memory\/threads(?:\/[^/]+(?:\/messages)?)?$/i;
+/** Native thread rename/delete routes. */
+const MEMORY_THREAD_MUTATION = /^\/memory\/threads\/[^/]+$/i;
 
 /**
  * Whether a request to the stock `@mastra/express` sub-app should be
  * dispatched, given the configured {@link MastraApiGateOptions.access}.
  *
  * `path` is mount-relative (what the plugin's catch-all sees, e.g.
- * `/agents/x/stream`, `/route/history/x`, `/mcp/...`). In `"scoped"`
+ * `/chat/x`, `/memory/threads`, `/mcp/...`). In `"scoped"`
  * mode the allowlist is deliberately tight - the chat client only ever
- * needs agent inference, read-only agent metadata, this plugin's own
- * OBO/resource-scoped `/route/*` routes, and (when enabled) MCP - so the
- * whole admin / mutating / bulk-export surface Mastra also exposes is
- * denied by default rather than enumerated.
+ * needs agent inference, read-only agent metadata, resource-scoped memory,
+ * this plugin's own `/route/*` routes, and (when enabled) MCP. The remaining
+ * admin, mutating, and bulk-export surface stays denied by default.
  */
 export function isMastraRequestAllowed(
   method: string,
@@ -393,33 +417,31 @@ export function isMastraRequestAllowed(
 ): boolean {
   if (opts.access === "full") return true;
   const p = path.startsWith("/") ? path : `/${path}`;
-  // This plugin's own custom routes are individually OBO- and
-  // resource-scoped (see history.ts / threads.ts), so every method is safe.
+  // The plugin's `/route/*` additions validate their own inputs and trusted
+  // AppKit request context before reaching product behavior.
   if (p === "/route" || p.startsWith("/route/")) return true;
   if (opts.mcpEnabled && (p === "/mcp" || p.startsWith("/mcp/"))) return true;
   const m = method.toUpperCase();
+  if (m === "POST" && AGENT_CHAT.test(p)) return true;
   if (m === "POST" && AGENT_INFERENCE.test(p)) return true;
-  if (m === "GET" && AGENT_METADATA.test(p)) return true;
+  if (m === "GET" && (AGENT_METADATA.test(p) || AGENT_SUSPENDED_RUNS.test(p))) return true;
+  if (m === "GET" && MEMORY_READ.test(p)) return true;
+  if ((m === "PATCH" || m === "DELETE") && MEMORY_THREAD_MUTATION.test(p)) return true;
+  if (m === "POST" && p === "/memory/messages/delete") return true;
   return false;
 }
 
 /**
- * Patches around `@mastra/express`'s custom-route dispatcher so the
- * plugin's custom API routes (e.g. `historyRoute`) work when
- * `MastraServer` is hosted on an Express subapp mounted under a parent
- * path (e.g. `/api/mastra`).
- *
- * The adapter's `registerCustomApiRoutes` matches against `req.path`
- * (mount-relative, correct) but dispatches to its internal Hono
- * mini-app using `req.originalUrl`, which still contains the parent
- * mount prefix. The Hono app registers the literal route paths
- * (for example `/route/history`), so the absolute URL never matches
- * until we overwrite `originalUrl` for `/route` and `/route/*` to the
- * mount-relative path.
+ * Keep Mastra custom API routes mount-relative when the Express subapp is
+ * hosted under AppKit's `/api/<plugin>` path.
  */
 export function attachRoutePatchMiddleware(app: express.Express): void {
   app.use((req, _res, next) => {
-    const isCustomRoute = req.path === "/route" || req.path.startsWith("/route/");
+    const isCustomRoute =
+      req.path === "/chat" ||
+      req.path.startsWith("/chat/") ||
+      req.path === "/route" ||
+      req.path.startsWith("/route/");
     if (!isCustomRoute) return next();
     req.originalUrl = req.path;
     next();

package/src/trace-io.ts

@@ -33,7 +33,7 @@ export const TRACE_IO_LIMIT = 8_000;
  * are intentionally excluded: their bodies are tool decisions, not the
  * user prompt, and they rarely produce a fresh answer worth surfacing.
  */
-const AGENT_TURN_ROUTE = /^\/agents\/[^/]+\/(stream|generate)(\/|$)/i;
+const AGENT_TURN_ROUTE = /^(?:\/agents\/[^/]+\/(?:stream|generate)(?:\/|$)|\/chat\/[^/]+$)/i;
 
 /** Attribute keys the MLflow UC `*_trace_unified` view reads from the root span. */
 export const MLFLOW_SPAN_INPUTS_ATTR = "mlflow.spanInputs";
@@ -55,7 +55,12 @@ export function assistantTextFromSse(body: string): string {
     // assistant text, so skipping them is the intended path rather than an error.
     const frame = json.parse(line.slice(5));
     if (!object.isRecord(frame) || frame.type !== "text-delta") continue;
-    const text = object.isRecord(frame.payload) ? frame.payload.text : undefined;
+    const text =
+      typeof frame.delta === "string"
+        ? frame.delta
+        : object.isRecord(frame.payload)
+          ? frame.payload.text
+          : undefined;
     if (typeof text === "string") parts.push(text);
   }
   return parts.join("");

package/src/writer.ts

@@ -1,8 +1,6 @@
 /**
- * Shared helper for publishing events through Mastra's
- * `ctx.writer`. Centralizes the "the downstream stream may already
- * be closed, don't take the whole tool down" pattern that the
- * Genie agent and chart tool both need.
+ * Shared helper for publishing Genie progress through Mastra's native
+ * `ctx.writer.custom()` data-part surface.
  *
  * Failures are logged at `warn` (a persistently-closed writer is
  * the most likely culprit when events go missing client-side) but
@@ -13,10 +11,12 @@
  */
 
 import { error, log } from "@dbx-tools/shared-core";
-import type { MastraWriter } from "@dbx-tools/shared-mastra";
+import { GENIE_PROGRESS_PART_TYPE, type GenieWriterEvent } from "@dbx-tools/shared-mastra";
+import type { ToolExecutionContext } from "@mastra/core/tools";
 
 /**
- * Best-effort `writer.write`. No-op when `writer` is undefined;
+ * Best-effort native custom progress write. No-op when the writer or owning
+ * tool call id is unavailable;
  * caught errors are logged via `log.warn("writer:error", ...)`
  * along with any caller-supplied `context` fields (e.g. a
  * `chartId` or `messageId`) so the warning is greppable per
@@ -24,18 +24,22 @@ import type { MastraWriter } from "@dbx-tools/shared-mastra";
  *
  * Returns when the write resolves or rejects; never throws.
  */
-export async function safeWrite(
+export async function safeWriteProgress(
   log: log.Logger,
-  writer: MastraWriter | undefined,
-  chunk: unknown,
+  writer: ToolExecutionContext["writer"],
+  toolCallId: string | undefined,
+  event: GenieWriterEvent,
   context: Record<string, unknown> = {},
 ): Promise<void> {
-  if (!writer) {
+  if (!writer || !toolCallId) {
     log.debug("writer:no-writer", context);
     return;
   }
   try {
-    await writer.write(chunk);
+    await writer.custom({
+      type: GENIE_PROGRESS_PART_TYPE,
+      data: { toolCallId, event },
+    });
     log.debug("writer:ok", context);
   } catch (err) {
     log.warn("writer:error", {

package/lib/src/history.d.ts

@@ -1,93 +0,0 @@
-/**
- * Thread history loader exposed as a Mastra custom API route.
- *
- * Backed entirely by native Mastra: looks up the active agent by id,
- * asks its `Memory` instance to `recall` a page of `MastraDBMessage`s,
- * and converts the result to AI SDK V5 `UIMessage`s with the official
- * {@link toAISdkV5Messages} helper from `@mastra/ai-sdk/ui`. No direct
- * database reads.
- *
- * The route is registered through {@link historyRoute} as a Mastra
- * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * the standard agent routes. That means the `MastraServer` auth
- * middleware (in `./server.ts`) has already populated `RequestContext` with
- * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
- * the handler runs - no cookie or user lookups happen here, and the
- * session-cookie logic stays the single source of truth in `server.ts`.
- *
- * @module
- */
-import type { MastraHistoryResponse } from "@dbx-tools/shared-mastra";
-import type { Agent } from "@mastra/core/agent";
-import { type AgentRouteOptions } from "./_agent-route-context.ts";
-/** Inputs accepted by {@link loadHistory}. */
-export interface LoadHistoryOptions {
-    agent: Agent;
-    threadId: string;
-    resourceId: string;
-    page?: number;
-    perPage?: number;
-    /** When true, returns the *oldest* page first (chronological). */
-    ascending?: boolean;
-}
-/**
- * Fetch a page of UI-formatted messages for a thread.
- *
- * Uses the agent's resolved `Memory` (`getMemory()`) so per-agent
- * storage namespaces (`mastra_<agentId>` schemas) and any future
- * memory-side filters apply automatically. When the agent has no
- * memory configured the response is a successful empty page so
- * callers don't have to special-case stateless agents.
- *
- * Pagination is descending-by-default: page 0 is the most recent
- * page, page 1 the page before that, etc. The returned `uiMessages`
- * are always re-sorted into chronological order (oldest -> newest)
- * so the client can prepend them above the existing transcript
- * without sorting locally.
- */
-export declare function loadHistory(opts: LoadHistoryOptions): Promise<MastraHistoryResponse>;
-/** Inputs accepted by {@link clearHistory}. */
-export interface ClearHistoryOptions {
-    agent: Agent;
-    threadId: string;
-    resourceId: string;
-}
-/**
- * Wipe every persisted message tied to a thread. Returns the count
- * of messages that were on the thread at delete time so the caller
- * can render a "cleared N messages" affordance without an
- * additional round-trip.
- *
- * Agents without a configured `Memory` resolve to a no-op (count
- * 0), matching {@link loadHistory}'s "stateless agents return an
- * empty page" stance so callers don't have to special-case them.
- * Threads that don't exist yet are also a successful no-op - the
- * operation is idempotent so the UI can fire-and-forget without
- * tracking thread existence.
- */
-export declare function clearHistory(opts: ClearHistoryOptions): Promise<{
-    cleared: number;
-}>;
-/** Options accepted by {@link historyRoute}. */
-export type HistoryRouteOptions = AgentRouteOptions;
-/**
- * Register the `<path>` Mastra custom API route. Handles two
- * methods on the same mount:
- *
- *   - `GET`: return a page of AI SDK V5 `UIMessage`s for the
- *     caller's current thread ({@link loadHistory}).
- *   - `DELETE`: wipe every persisted message on the caller's
- *     thread ({@link clearHistory}). The session cookie that
- *     anchors the thread id is left alone so the user keeps the
- *     same thread - only the contents go away.
- *
- * Follows the `@mastra/ai-sdk` `chatRoute` convention for agent
- * binding: pass `agent` for a fixed-agent mount, or include
- * `:agentId` in the path for dynamic routing. The plugin registers
- * both `/route/history` (default agent) and `/route/history/:agentId`.
- *
- * The handler reads `threadId` and `resourceId` from `RequestContext`
- * (populated upstream by `MastraServer.registerAuthMiddleware`), so
- * no cookie or user lookups happen here.
- */
-export declare function historyRoute(options: HistoryRouteOptions): import("@mastra/core/server").ApiRoute[];