@dbx-tools/appkit-mastra 0.1.5 → 0.1.10

package/src/history.ts

@@ -9,27 +9,29 @@
  *
  * The route is registered through {@link historyRoute} as a Mastra
  * `registerApiRoute` so it sits in the same dispatcher pipeline as
- * `chatRoute`. That means the `MastraServer` auth middleware (in
- * `./server.ts`) has already populated `RequestContext` with
+ * 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`.
  */
 
-import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
-import type { Agent } from "@mastra/core/agent";
-import type {
-  MastraDBMessage,
-} from "@mastra/core/agent/message-list";
-import {
-  MASTRA_RESOURCE_ID_KEY,
-  MASTRA_THREAD_ID_KEY,
-} from "@mastra/core/request-context";
-import { registerApiRoute } from "@mastra/core/server";
 import type {
+  MastraClearHistoryResponse,
   MastraHistoryResponse,
   MastraHistoryUIMessage,
-} from "@dbx-tools/appkit-mastra-shared";
+} from "@dbx-tools/shared-mastra";
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+import type { Agent } from "@mastra/core/agent";
+import type { MastraDBMessage } from "@mastra/core/agent/message-list";
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
+import type { ContextWithMastra } from "@mastra/core/server";
+import { registerApiRoute } from "@mastra/core/server";
+
+import { clampPerPage, parseIntParam } from "./pagination";
+import { error, log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("mastra/history");
 
 /** Default history page size; matches the Mastra storage default. */
 const DEFAULT_PER_PAGE = 20;
@@ -62,15 +64,18 @@ export interface LoadHistoryOptions {
  * so the client can prepend them above the existing transcript
  * without sorting locally.
  */
-export async function loadHistory(
-  opts: LoadHistoryOptions,
-): Promise<MastraHistoryResponse> {
-  const perPage = clampPerPage(opts.perPage);
+export async function loadHistory(opts: LoadHistoryOptions): Promise<MastraHistoryResponse> {
+  const perPage = clampPerPage(opts.perPage, {
+    fallback: DEFAULT_PER_PAGE,
+    max: MAX_PER_PAGE,
+  });
   const page = Math.max(0, Math.trunc(opts.page ?? 0));
   const memory = await opts.agent.getMemory();
   if (!memory) {
+    logger.debug("recall:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
     return { uiMessages: [], page, perPage, total: 0, hasMore: false };
   }
+  const startedAt = Date.now();
   const result = await memory.recall({
     threadId: opts.threadId,
     ...(opts.resourceId ? { resourceId: opts.resourceId } : {}),
@@ -82,9 +87,17 @@ export async function loadHistory(
     },
   });
   const chronological = sortChronological(result.messages);
-  const uiMessages = toAISdkV5Messages(
-    chronological,
-  ) as unknown as MastraHistoryUIMessage[];
+  const uiMessages = toAISdkV5Messages(chronological) as unknown as MastraHistoryUIMessage[];
+  logger.debug("recall:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    page,
+    perPage,
+    returned: uiMessages.length,
+    total: result.total,
+    hasMore: result.hasMore,
+    elapsedMs: Date.now() - startedAt,
+  });
   return {
     uiMessages,
     page,
@@ -94,19 +107,95 @@ export async function loadHistory(
   };
 }
 
+/** Inputs accepted by {@link clearHistory}. */
+export interface ClearHistoryOptions {
+  agent: Agent;
+  threadId: 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 async function clearHistory(opts: ClearHistoryOptions): Promise<{ cleared: number }> {
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    logger.debug("clear:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
+    return { cleared: 0 };
+  }
+  // Mastra's `deleteThread` cascades to the message table, so we
+  // can't ask for a count after the fact. Read it pre-delete with a
+  // one-page recall sized to fit common threads in a single round
+  // trip; the value is for telemetry / UI, not correctness.
+  let cleared = 0;
+  try {
+    const probe = await memory.recall({
+      threadId: opts.threadId,
+      page: 0,
+      perPage: 1,
+    });
+    cleared = probe.total;
+  } catch (err) {
+    // A missing-thread error is the happy-path "nothing to count";
+    // every other error is logged but doesn't block the delete.
+    logger.debug("clear:probe-failed", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      error: error.errorMessage(err),
+    });
+  }
+
+  const startedAt = Date.now();
+  try {
+    await memory.deleteThread(opts.threadId);
+  } catch (err) {
+    // Mastra's `deleteThread` raises when the thread row was never
+    // created (e.g. clearing an empty session). Surface as a soft
+    // warn and treat as success - the user-facing semantic is
+    // "history is now empty" which is already true.
+    logger.warn("clear:delete-soft-failed", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      error: error.errorMessage(err),
+    });
+  }
+  logger.info("clear:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    cleared,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return { cleared };
+}
+
 /** Options accepted by {@link historyRoute}. */
 export type HistoryRouteOptions =
-  | { path: `${string}:agentId${string}`; agent?: never }
-  | { path: string; agent: string };
+  { path: `${string}:agentId${string}`; agent?: never } | { path: string; agent: string };
 
 /**
- * Register a `GET <path>` Mastra custom API route that returns a page
- * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ * 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.
  *
- * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
- * fixed-agent mount, or include `:agentId` in the path for dynamic
- * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
- * layout (`/route/chat` + `/route/chat/:agentId`).
+ * 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
@@ -120,46 +209,68 @@ export function historyRoute(options: HistoryRouteOptions) {
       "historyRoute path must include `:agentId` or `agent` must be passed explicitly",
     );
   }
-  return registerApiRoute(path, {
-    method: "GET",
-    handler: async (c) => {
-      const mastra = c.get("mastra");
-      const requestContext = c.get("requestContext");
-      const agentId = fixedAgent ?? c.req.param("agentId");
-      if (!agentId) {
-        return c.json({ error: "agentId is required" }, 400);
-      }
-      const agent = mastra.getAgentById(agentId);
-      if (!agent) {
-        return c.json({ error: `Unknown agent "${agentId}"` }, 404);
-      }
-      const threadId = requestContext.get(MASTRA_THREAD_ID_KEY) as
-        | string
-        | undefined;
-      if (!threadId) {
-        return c.json({ error: "thread id missing from request context" }, 400);
-      }
-      const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as
-        | string
-        | undefined;
-      const payload = await loadHistory({
-        agent,
-        threadId,
-        ...(resourceId ? { resourceId } : {}),
-        page: parseIntParam(c.req.query("page")),
-        perPage: parseIntParam(c.req.query("perPage")),
-      });
-      return c.json(payload);
-    },
-  });
-}
+  // Tiny resolver shared by GET / DELETE: derive the active agent
+  // and thread id, returning a JSON error response when either is
+  // missing. Keeps both handlers thin and gives them identical
+  // validation behaviour.
+  const resolveContext = (c: ContextWithMastra) => {
+    const mastra = c.get("mastra");
+    const requestContext = c.get("requestContext");
+    const agentId = fixedAgent ?? c.req.param("agentId");
+    if (!agentId) {
+      return { error: c.json({ error: "agentId is required" }, 400) } as const;
+    }
+    const agent = mastra.getAgentById(agentId);
+    if (!agent) {
+      return {
+        error: c.json({ error: `Unknown agent "${agentId}"` }, 404),
+      } as const;
+    }
+    const threadId = requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
+    if (!threadId) {
+      return {
+        error: c.json({ error: "thread id missing from request context" }, 400),
+      } as const;
+    }
+    const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as string | undefined;
+    return { agentId, agent, threadId, resourceId } as const;
+  };
 
-/** Coerce / clamp `perPage`; falls back to the page-size default. */
-function clampPerPage(value: number | undefined): number {
-  if (value === undefined || Number.isNaN(value)) return DEFAULT_PER_PAGE;
-  const n = Math.trunc(value);
-  if (n <= 0) return DEFAULT_PER_PAGE;
-  return Math.min(n, MAX_PER_PAGE);
+  return [
+    registerApiRoute(path, {
+      method: "GET",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const payload = await loadHistory({
+          agent: ctx.agent,
+          threadId: ctx.threadId,
+          ...(ctx.resourceId ? { resourceId: ctx.resourceId } : {}),
+          page: parseIntParam(c.req.query("page")),
+          perPage: parseIntParam(c.req.query("perPage")),
+        });
+        return c.json(payload);
+      },
+    }),
+    registerApiRoute(path, {
+      method: "DELETE",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const { cleared } = await clearHistory({
+          agent: ctx.agent,
+          threadId: ctx.threadId,
+        });
+        const payload: MastraClearHistoryResponse = {
+          ok: true,
+          agentId: ctx.agentId,
+          threadId: ctx.threadId,
+          cleared,
+        };
+        return c.json(payload);
+      },
+    }),
+  ];
 }
 
 /**
@@ -184,15 +295,3 @@ function toEpoch(value: unknown): number {
   }
   return 0;
 }
-
-/**
- * Coerce a Hono query value into a non-negative integer. Returns
- * `undefined` for empty / non-numeric / negative inputs so
- * {@link loadHistory} can apply its built-in defaults.
- */
-function parseIntParam(value: string | undefined): number | undefined {
-  if (!value) return undefined;
-  const n = Number(value);
-  if (!Number.isFinite(n) || n < 0) return undefined;
-  return Math.trunc(n);
-}

package/src/mcp.ts

@@ -0,0 +1,105 @@
+/**
+ * Optional Mastra MCP server exposure for the AppKit Mastra plugin.
+ *
+ * Turns the plugin's registered agents (and, opt-in, its ambient tools)
+ * into a Mastra `MCPServer` so external MCP clients - Claude Desktop,
+ * Cursor, the Mastra playground, or another agent - can call them over
+ * the standard MCP transports. The resulting server is handed to the
+ * `Mastra` instance via `mcpServers`, which makes `@mastra/express`
+ * serve the stock MCP routes under the plugin's base path; the plugin
+ * never registers a bespoke MCP route of its own.
+ */
+
+import type { Agent } from "@mastra/core/agent";
+import { MCPServer } from "@mastra/mcp";
+
+import type { MastraTools } from "./agents";
+import type { MastraMcpConfig, MastraPluginConfig } from "./config";
+
+/** MCP server version advertised when the caller doesn't pin one. */
+const DEFAULT_MCP_VERSION = "1.0.0";
+
+/**
+ * A built MCP server plus the request paths it answers on, relative to
+ * the plugin's base path (`/api/<plugin>`).
+ *
+ * The paths are the **clean public aliases** (`/mcp`, `/sse`,
+ * `/messages`) the plugin exposes. `@mastra/express` actually mounts the
+ * transports under `/mcp/<serverId>/<transport>` off the `Mastra`
+ * instance's `mcpServers`; the plugin rewrites the alias to that route
+ * before dispatch (see {@link ResolvedMcp.serverId}), so a client never
+ * sees the doubled `/mcp/<serverId>/mcp` segment.
+ */
+export interface ResolvedMcp {
+  /**
+   * Registry id, used in the underlying `@mastra/express` route
+   * (`/mcp/<serverId>/...`) the plugin rewrites the clean alias to.
+   */
+  serverId: string;
+  /** The Mastra MCP server to hand to `new Mastra({ mcpServers })`. */
+  server: MCPServer;
+  /** Streamable-HTTP transport path, relative to the plugin base path. */
+  httpPath: string;
+  /** SSE transport path, relative to the plugin base path. */
+  ssePath: string;
+  /** SSE message path, relative to the plugin base path. */
+  messagePath: string;
+}
+
+/**
+ * Build the plugin's MCP server, or `null` only when `config.mcp` is
+ * explicitly `false`.
+ *
+ * Agent exposure is on by default because it's cheap: the already-
+ * registered agents are wrapped as `ask_<agentId>` tools and handed to
+ * `@mastra/express` (already mounted for the chat routes) - no extra
+ * process, dependency, or network cost, and requests run under the same
+ * OBO scope. So `undefined` (the default) and `true` both expose every
+ * registered agent under a server id equal to the plugin name; only
+ * `false` turns MCP off. The object form ({@link MastraMcpConfig}) tunes
+ * the id / advertised metadata and can additionally expose the plugin's
+ * ambient tools or a set of extra MCP-only tools. Ambient tools stay off
+ * unless explicitly enabled - they assume an in-process chat turn, so
+ * they aren't cheap / safe to expose to a standalone MCP client.
+ */
+export function buildMcpServer(opts: {
+  config: MastraPluginConfig;
+  pluginName: string;
+  displayName: string;
+  agents: Record<string, Agent>;
+  ambientTools: MastraTools;
+}): ResolvedMcp | null {
+  const { config, pluginName, displayName, agents, ambientTools } = opts;
+  if (config.mcp === false) return null;
+  const settings: MastraMcpConfig = typeof config.mcp === "object" ? config.mcp : {};
+
+  const serverId = settings.serverId ?? pluginName;
+  const exposeAgents = settings.agents !== false;
+  const exposeTools = settings.tools === true;
+
+  // MCPServerConfig.tools is required, so always pass a record (empty
+  // when the caller exposes only agents).
+  const tools: MastraTools = {
+    ...(exposeTools ? ambientTools : {}),
+    ...(settings.extraTools ?? {}),
+  };
+
+  const server = new MCPServer({
+    id: serverId,
+    name: settings.name ?? `${displayName} MCP`,
+    version: settings.version ?? DEFAULT_MCP_VERSION,
+    ...(settings.description ? { description: settings.description } : {}),
+    ...(exposeAgents ? { agents } : {}),
+    tools,
+  });
+
+  // Advertise the clean aliases; the plugin rewrites these to the stock
+  // `/mcp/<serverId>/<transport>` routes `@mastra/express` mounts.
+  return {
+    serverId,
+    server,
+    httpPath: "/mcp",
+    ssePath: "/sse",
+    messagePath: "/messages",
+  };
+}