@dbx-tools/appkit-mastra 0.6.218 → 0.6.220

package/src/history.ts

@@ -1,270 +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 { error, log } from "@dbx-tools/shared-core";
-import type {
-  MastraClearHistoryResponse,
-  MastraHistoryResponse,
-  MastraHistoryUIMessage,
-} 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 type { ContextWithMastra } from "@mastra/core/server";
-import { registerApiRoute } from "@mastra/core/server";
-
-import {
-  resolveAgentRequestContext,
-  resolveAgentRouteOptions,
-  type AgentRouteOptions,
-} from "./_agent-route-context.ts";
-import { clampPerPage, parseIntParam } from "./pagination.ts";
-
-const logger = log.logger("mastra/history");
-
-/** Default history page size; matches the Mastra storage default. */
-const DEFAULT_PER_PAGE = 20;
-/** Hard cap so a misbehaving client can't fetch the whole thread at once. */
-const MAX_PER_PAGE = 200;
-
-/** 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 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,
-    resourceId: opts.resourceId,
-    page,
-    perPage,
-    orderBy: {
-      field: "createdAt",
-      direction: opts.ascending ? "ASC" : "DESC",
-    },
-  });
-  const chronological = sortChronological(result.messages);
-  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,
-    perPage,
-    total: result.total,
-    hasMore: result.hasMore,
-  };
-}
-
-/** 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 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 };
-  }
-  const existing = await memory.getThreadById({ threadId: opts.threadId });
-  if (!existing || existing.resourceId !== opts.resourceId) {
-    logger.debug("clear:not-owned", {
-      agentId: opts.agent.id,
-      threadId: opts.threadId,
-      found: existing !== null,
-    });
-    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,
-      resourceId: opts.resourceId,
-      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();
-  await memory.deleteThread(opts.threadId);
-  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 = 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 function historyRoute(options: HistoryRouteOptions) {
-  const { path, fixedAgent } = resolveAgentRouteOptions(options, "historyRoute.path");
-
-  return [
-    registerApiRoute(path, {
-      method: "GET",
-      handler: async (c: ContextWithMastra) => {
-        const ctx = resolveAgentRequestContext(c, { fixedAgent, threadId: "required" });
-        if ("error" in ctx) return ctx.error;
-        const payload = await loadHistory({
-          agent: ctx.agent,
-          threadId: ctx.threadId,
-          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 = resolveAgentRequestContext(c, { fixedAgent, threadId: "required" });
-        if ("error" in ctx) return ctx.error;
-        const { cleared } = await clearHistory({
-          agent: ctx.agent,
-          threadId: ctx.threadId,
-          resourceId: ctx.resourceId,
-        });
-        const payload: MastraClearHistoryResponse = {
-          ok: true,
-          agentId: ctx.agentId,
-          threadId: ctx.threadId,
-          cleared,
-        };
-        return c.json(payload);
-      },
-    }),
-  ];
-}
-
-/**
- * Sort messages oldest-first by `createdAt`, falling back to whatever
- * order the storage returned them in. The native `recall` call honors
- * `orderBy` but doesn't guarantee a stable secondary sort, so we
- * normalize here before handing the page to the AI SDK converter.
- */
-function sortChronological(messages: MastraDBMessage[]): MastraDBMessage[] {
-  return [...messages].sort((a, b) => {
-    const ta = toEpoch(a.createdAt);
-    const tb = toEpoch(b.createdAt);
-    return ta - tb;
-  });
-}
-
-function toEpoch(value: unknown): number {
-  if (value instanceof Date) return value.getTime();
-  if (typeof value === "string" || typeof value === "number") {
-    const parsed = new Date(value).getTime();
-    return Number.isNaN(parsed) ? 0 : parsed;
-  }
-  return 0;
-}

package/src/threads.ts

@@ -1,309 +0,0 @@
-/**
- * Conversation-thread listing exposed as a Mastra custom API route.
- *
- * Backed entirely by native Mastra: looks up the active agent by id,
- * asks its `Memory` instance to `listThreads` filtered to the caller's
- * resource, and shapes each into the JSON-safe {@link MastraThread}
- * wire type. A sibling `DELETE` removes a single named thread.
- *
- * A sibling `DELETE` removes a single named thread; a `PATCH` renames
- * one ({@link renameThread}).
- *
- * Like {@link historyRoute} this registers through Mastra's
- * `registerApiRoute` so it shares the `MastraServer` auth-middleware
- * pipeline (in `./server.ts`), which has already stamped the resource
- * id (`MASTRA_RESOURCE_ID_KEY`) and the targeted thread id
- * (`MASTRA_THREAD_ID_KEY`, resolved from the thread-selection header /
- * cookie) on `RequestContext` by the time a handler runs. Resource
- * scoping lives here so a caller can only ever see, rename, or delete
- * its own threads; no cookie or user lookups happen in this module.
- *
- * @module
- */
-
-import { log } from "@dbx-tools/shared-core";
-import {
-  wire,
-  type MastraDeleteThreadResponse,
-  type MastraThread,
-  type MastraThreadsResponse,
-  type MastraUpdateThreadResponse,
-} from "@dbx-tools/shared-mastra";
-import type { Agent } from "@mastra/core/agent";
-import type { StorageThreadType } from "@mastra/core/memory";
-import type { ContextWithMastra } from "@mastra/core/server";
-import { registerApiRoute } from "@mastra/core/server";
-
-import {
-  resolveAgentRequestContext,
-  resolveAgentRouteOptions,
-  type AgentRouteOptions,
-} from "./_agent-route-context.ts";
-import { clampPerPage, parseIntParam } from "./pagination.ts";
-import { invalidFields } from "./validation.ts";
-
-const logger = log.logger("mastra/threads");
-
-/** Default threads page size. */
-const DEFAULT_PER_PAGE = 30;
-/** Hard cap so a misbehaving client can't fetch every thread at once. */
-const MAX_PER_PAGE = 200;
-/** Stable client message for a rename body that fails schema validation. */
-const INVALID_RENAME_MESSAGE = "Invalid thread rename request";
-
-/** Inputs accepted by {@link listThreads}. */
-export interface ListThreadsOptions {
-  agent: Agent;
-  resourceId: string;
-  page?: number;
-  perPage?: number;
-}
-
-/**
- * Fetch a page of the resource's conversation threads, newest
- * (`updatedAt` DESC) first.
- *
- * Uses the agent's resolved `Memory` (`getMemory()`) so the per-agent
- * storage namespace (`mastra_<agentId>` schema) applies 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.
- */
-export async function listThreads(opts: ListThreadsOptions): Promise<MastraThreadsResponse> {
-  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("list:no-memory", { agentId: opts.agent.id });
-    return { threads: [], page, perPage, total: 0, hasMore: false };
-  }
-  const startedAt = Date.now();
-  const result = await memory.listThreads({
-    filter: { resourceId: opts.resourceId },
-    page,
-    perPage,
-    orderBy: { field: "updatedAt", direction: "DESC" },
-  });
-  const threads = result.threads.map(toWireThread);
-  logger.debug("list:done", {
-    agentId: opts.agent.id,
-    resourceId: opts.resourceId,
-    page,
-    perPage,
-    returned: threads.length,
-    total: result.total,
-    hasMore: result.hasMore,
-    elapsedMs: Date.now() - startedAt,
-  });
-  return {
-    threads,
-    page,
-    perPage,
-    total: result.total,
-    hasMore: result.hasMore,
-  };
-}
-
-/** Inputs accepted by {@link deleteThread}. */
-export interface DeleteThreadOptions {
-  agent: Agent;
-  threadId: string;
-  resourceId: string;
-}
-
-/**
- * Delete a single named thread (and every message on it).
- *
- * Ownership is enforced: the thread is only removed when it belongs to
- * the calling resource, so a client can't delete another user's
- * conversation by guessing its id. A thread that doesn't exist (or
- * isn't owned by the caller) is a successful no-op (`deleted: false`)
- * so the UI can fire-and-forget.
- */
-export async function deleteThread(opts: DeleteThreadOptions): Promise<{ deleted: boolean }> {
-  const memory = await opts.agent.getMemory();
-  if (!memory) {
-    logger.debug("delete:no-memory", { agentId: opts.agent.id });
-    return { deleted: false };
-  }
-  // Confirm the thread exists and is owned by the caller before
-  // deleting; never let a guessed id touch another resource's data.
-  const existing = await memory.getThreadById({ threadId: opts.threadId });
-  if (!existing || existing.resourceId !== opts.resourceId) {
-    logger.debug("delete:not-owned", {
-      agentId: opts.agent.id,
-      threadId: opts.threadId,
-      found: existing !== null,
-    });
-    return { deleted: false };
-  }
-  const startedAt = Date.now();
-  await memory.deleteThread(opts.threadId);
-  logger.info("delete:done", {
-    agentId: opts.agent.id,
-    threadId: opts.threadId,
-    elapsedMs: Date.now() - startedAt,
-  });
-  return { deleted: true };
-}
-
-/** Inputs accepted by {@link renameThread}. */
-export interface RenameThreadOptions {
-  agent: Agent;
-  threadId: string;
-  resourceId: string;
-  title: string;
-}
-
-/**
- * Rename a single thread, returning the updated wire thread.
- *
- * Ownership is enforced the same way {@link deleteThread} enforces it:
- * the title is only changed when the thread belongs to the calling
- * resource, so a client can't rename another user's conversation by
- * guessing its id. Existing thread `metadata` is preserved untouched
- * (Mastra's `updateThread` replaces the row, so it must be passed back
- * in). Returns `null` when the thread doesn't exist, isn't owned by the
- * caller, or the agent has no memory configured, letting the route map
- * that to a 404.
- */
-export async function renameThread(opts: RenameThreadOptions): Promise<MastraThread | null> {
-  const memory = await opts.agent.getMemory();
-  if (!memory) {
-    logger.debug("rename:no-memory", { agentId: opts.agent.id });
-    return null;
-  }
-  const existing = await memory.getThreadById({ threadId: opts.threadId });
-  if (!existing || existing.resourceId !== opts.resourceId) {
-    logger.debug("rename:not-owned", {
-      agentId: opts.agent.id,
-      threadId: opts.threadId,
-      found: existing !== null,
-    });
-    return null;
-  }
-  const startedAt = Date.now();
-  const updated = await memory.updateThread({
-    id: opts.threadId,
-    title: opts.title,
-    metadata: existing.metadata ?? {},
-  });
-  logger.info("rename:done", {
-    agentId: opts.agent.id,
-    threadId: opts.threadId,
-    elapsedMs: Date.now() - startedAt,
-  });
-  return toWireThread(updated);
-}
-
-/** Options accepted by {@link threadsRoute}. */
-export type ThreadsRouteOptions = AgentRouteOptions;
-
-/**
- * Register the `<path>` Mastra custom API route. Handles three methods
- * on the same mount:
- *
- *   - `GET`: a page of the resource's conversation threads
- *     ({@link listThreads}).
- *   - `DELETE`: remove the thread named by the thread-selection header
- *     / `?threadId=` query ({@link deleteThread}). The id is read from
- *     `RequestContext` (the auth middleware resolves it the same way it
- *     does for streaming and history), so the client deletes any of its
- *     threads by stamping the target id - no separate path param.
- *   - `PATCH`: rename the thread named by the thread-selection header /
- *     `?threadId=` query to the `{ title }` in the JSON body
- *     ({@link renameThread}). Targets a thread the same way `DELETE`
- *     does; 404s when the thread isn't owned by the caller.
- *
- * Follows the `@mastra/ai-sdk` agent-binding convention: pass `agent`
- * for a fixed-agent mount, or include `:agentId` in the path for
- * dynamic routing. The plugin registers both `/route/threads` (default
- * agent) and `/route/threads/:agentId`.
- */
-export function threadsRoute(options: ThreadsRouteOptions) {
-  const { path, fixedAgent } = resolveAgentRouteOptions(options, "threadsRoute.path");
-
-  return [
-    registerApiRoute(path, {
-      method: "GET",
-      handler: async (c: ContextWithMastra) => {
-        const ctx = resolveAgentRequestContext(c, { fixedAgent });
-        if ("error" in ctx) return ctx.error;
-        const payload = await listThreads({
-          agent: ctx.agent,
-          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 = resolveAgentRequestContext(c, { fixedAgent, threadId: "required" });
-        if ("error" in ctx) return ctx.error;
-        const { deleted } = await deleteThread({
-          agent: ctx.agent,
-          threadId: ctx.threadId,
-          resourceId: ctx.resourceId,
-        });
-        const payload: MastraDeleteThreadResponse = {
-          ok: true,
-          agentId: ctx.agentId,
-          threadId: ctx.threadId,
-          deleted,
-        };
-        return c.json(payload);
-      },
-    }),
-    registerApiRoute(path, {
-      method: "PATCH",
-      handler: async (c: ContextWithMastra) => {
-        const ctx = resolveAgentRequestContext(c, { fixedAgent, threadId: "required" });
-        if ("error" in ctx) return ctx.error;
-        const body = wire.MastraUpdateThreadRequestSchema.safeParse(await c.req.json());
-        if (!body.success) {
-          logger.warn("rename:invalid", { error: body.error.message });
-          return c.json({ error: INVALID_RENAME_MESSAGE, fields: invalidFields(body.error) }, 400);
-        }
-        const thread = await renameThread({
-          agent: ctx.agent,
-          threadId: ctx.threadId,
-          resourceId: ctx.resourceId,
-          title: body.data.title,
-        });
-        if (!thread) {
-          return c.json({ error: `Unknown thread "${ctx.threadId}"` }, 404);
-        }
-        const payload: MastraUpdateThreadResponse = {
-          ok: true,
-          agentId: ctx.agentId,
-          thread,
-        };
-        return c.json(payload);
-      },
-    }),
-  ];
-}
-
-/** Coerce a Mastra `StorageThreadType` into the JSON-safe wire shape. */
-function toWireThread(thread: StorageThreadType): MastraThread {
-  return {
-    id: thread.id,
-    ...(thread.title ? { title: thread.title } : {}),
-    resourceId: thread.resourceId,
-    createdAt: toIso(thread.createdAt),
-    updatedAt: toIso(thread.updatedAt),
-    ...(thread.metadata ? { metadata: thread.metadata } : {}),
-  };
-}
-
-/** Render a storage timestamp as an ISO-8601 string for the wire. */
-function toIso(value: Date | string | number): string {
-  if (value instanceof Date) return value.toISOString();
-  const parsed = new Date(value);
-  return Number.isNaN(parsed.getTime()) ? new Date(0).toISOString() : parsed.toISOString();
-}