@sentry/junior-memory 0.119.0 → 0.121.0

package/src/api.ts

@@ -0,0 +1,168 @@
+/**
+ * Authenticated REST resources for personal memories.
+ *
+ * HTTP identity is one verified viewer. Linked platform actors are resolved
+ * behind the route boundary and used only to authorize personal scopes.
+ */
+import { z } from "zod";
+import {
+  pluginApiRouteRequestContextSchema,
+  type PluginApiRouteRequestContext,
+  type PluginRouteApp,
+  type PluginUserPageActor,
+} from "@sentry/junior-plugin-api";
+import type { MemoryDb, MemoryRecord } from "./store";
+import {
+  createViewerMemories,
+  InvalidMemoryCursorError,
+  PersonalMemoryNotFoundError,
+} from "./personal";
+
+export const memoryApiSchema = z
+  .object({
+    content: z.string().min(1),
+    createdAt: z.iso.datetime(),
+    expiresAt: z.iso.datetime().optional(),
+    id: z.string().min(1),
+    kind: z.enum(["preference", "procedure", "knowledge"]),
+    observedAt: z.iso.datetime(),
+  })
+  .strict();
+
+export const memoryListResponseSchema = z
+  .object({
+    memories: z.array(memoryApiSchema),
+    nextCursor: z.string().min(1).optional(),
+  })
+  .strict();
+
+export type MemoryApi = z.output<typeof memoryApiSchema>;
+export type MemoryListResponse = z.output<typeof memoryListResponseSchema>;
+
+const memoryListQuerySchema = z
+  .object({
+    cursor: z.string().min(1).max(1_000).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(25),
+    q: z.string().trim().max(200).optional(),
+  })
+  .strict();
+
+interface MemoryApiOptions {
+  actors(email: string): Promise<PluginUserPageActor[]>;
+  db: MemoryDb;
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, {
+    headers: { "cache-control": "no-store" },
+    status,
+  });
+}
+
+function apiMemory(memory: MemoryRecord): z.output<typeof memoryApiSchema> {
+  return {
+    content: memory.content,
+    createdAt: new Date(memory.createdAtMs).toISOString(),
+    ...(memory.expiresAtMs !== undefined
+      ? { expiresAt: new Date(memory.expiresAtMs).toISOString() }
+      : {}),
+    id: memory.id,
+    kind: memory.kind,
+    observedAt: new Date(memory.observedAtMs).toISOString(),
+  };
+}
+
+function viewerEmail(
+  context: PluginApiRouteRequestContext | undefined,
+): string | undefined {
+  const parsed = pluginApiRouteRequestContextSchema.safeParse(context);
+  if (!parsed.success || parsed.data.auth.user.emailVerified !== true) {
+    return undefined;
+  }
+  return parsed.data.auth.user.email?.trim().toLowerCase() || undefined;
+}
+
+/** Create the authenticated personal-memory REST app. */
+export function createMemoryApi(options: MemoryApiOptions): PluginRouteApp {
+  return {
+    async fetch(request, context) {
+      const email = viewerEmail(context);
+      if (!email) {
+        return json({ error: "Authentication required." }, 401);
+      }
+
+      const url = new URL(request.url);
+      const memoryPath = /^\/memories\/([^/]+)$/.exec(url.pathname);
+      const isCollection = url.pathname === "/memories";
+      if (!isCollection && !memoryPath) {
+        return json({ error: "Not found." }, 404);
+      }
+
+      const actors = await options.actors(email);
+      const memories = createViewerMemories(options.db, actors);
+      try {
+        if (
+          isCollection &&
+          (request.method === "GET" || request.method === "HEAD")
+        ) {
+          const query = memoryListQuerySchema.parse({
+            cursor: url.searchParams.get("cursor") ?? undefined,
+            limit: url.searchParams.get("limit") ?? undefined,
+            q: url.searchParams.get("q") ?? undefined,
+          });
+          const page = await memories.list({
+            cursor: query.cursor,
+            limit: query.limit,
+            ...(query.q ? { query: query.q } : {}),
+          });
+          const body = memoryListResponseSchema.parse({
+            memories: page.memories.map(apiMemory),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+          });
+          return request.method === "HEAD"
+            ? new Response(null, {
+                headers: { "cache-control": "no-store" },
+                status: 200,
+              })
+            : json(body);
+        }
+
+        if (
+          memoryPath &&
+          (request.method === "GET" || request.method === "HEAD")
+        ) {
+          const memory = memoryApiSchema.parse(
+            apiMemory(await memories.get(decodeURIComponent(memoryPath[1]!))),
+          );
+          return request.method === "HEAD"
+            ? new Response(null, {
+                headers: { "cache-control": "no-store" },
+                status: 200,
+              })
+            : json(memory);
+        }
+
+        if (memoryPath && request.method === "DELETE") {
+          await memories.archive(decodeURIComponent(memoryPath[1]!));
+          return new Response(null, {
+            headers: { "cache-control": "no-store" },
+            status: 204,
+          });
+        }
+      } catch (error) {
+        if (
+          error instanceof z.ZodError ||
+          error instanceof InvalidMemoryCursorError
+        ) {
+          return json({ error: "Invalid memory request." }, 400);
+        }
+        if (error instanceof PersonalMemoryNotFoundError) {
+          return json({ error: error.message }, 404);
+        }
+        throw error;
+      }
+
+      return json({ error: "Method not allowed." }, 405);
+    },
+  };
+}

package/src/db/schema.ts

@@ -58,6 +58,11 @@ export const juniorMemoryMemories = pgTable(
       .where(
         sql`${table.archivedAtMs} IS NULL AND ${table.expiresAtMs} IS NOT NULL`,
       ),
+    index("junior_memory_memories_search_idx")
+      .using("gin", sql`to_tsvector('english', ${table.content})`)
+      .where(
+        sql`${table.archivedAtMs} IS NULL AND ${table.supersededAtMs} IS NULL AND ${table.supersededById} IS NULL`,
+      ),
     uniqueIndex("junior_memory_memories_idempotency_idx")
       .on(table.scope, table.scopeKey, table.idempotencyKey)
       .where(

package/src/index.ts

@@ -1,4 +1,10 @@
 export { memoryPlugin } from "./plugin";
+export {
+  memoryApiSchema,
+  memoryListResponseSchema,
+  type MemoryApi,
+  type MemoryListResponse,
+} from "./api";
 export type { MemoryPluginOptions } from "./plugin";
 export { createMemoryStore } from "./store";
 export type {

package/src/operational-report.ts

@@ -0,0 +1,191 @@
+import type { PluginOperationalReportContent } from "@sentry/junior-plugin-api";
+import { and, eq, gt, isNull, or, sql } from "drizzle-orm";
+import { z } from "zod";
+import { juniorMemoryEmbeddings, juniorMemoryMemories } from "./db/schema";
+import type { MemoryDb } from "./store";
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const WINDOWS = [7, 30, 90] as const;
+
+const memoryDaySchema = z
+  .object({
+    conversation: z.number().int().nonnegative(),
+    date: z.string().date(),
+    personal: z.number().int().nonnegative(),
+  })
+  .strict();
+
+function queryRows(result: unknown): unknown[] {
+  if (
+    typeof result !== "object" ||
+    result === null ||
+    !("rows" in result) ||
+    !Array.isArray(result.rows)
+  ) {
+    throw new TypeError("Memory activity query did not return rows");
+  }
+  return result.rows;
+}
+
+function startOfUtcDay(value: number): Date {
+  const date = new Date(value);
+  date.setUTCHours(0, 0, 0, 0);
+  return date;
+}
+
+async function aggregateMemoryDays(args: { db: MemoryDb; nowMs: number }) {
+  const end = startOfUtcDay(args.nowMs);
+  const start = startOfUtcDay(args.nowMs - (WINDOWS.at(-1)! - 1) * DAY_MS);
+  const endExclusiveMs = end.getTime() + DAY_MS;
+  const table = juniorMemoryMemories;
+  const result = await args.db.execute(sql`
+    WITH days AS (
+      SELECT generate_series(
+        date_trunc('day', ${start}::timestamptz AT TIME ZONE 'UTC'),
+        date_trunc('day', ${end}::timestamptz AT TIME ZONE 'UTC'),
+        interval '1 day'
+      ) AS day
+    ), daily AS (
+      SELECT
+        date_trunc(
+          'day',
+          to_timestamp(${table.createdAtMs} / 1000.0) AT TIME ZONE 'UTC'
+        ) AS day,
+        count(*) FILTER (
+          WHERE ${table.scope} = 'personal'
+        )::integer AS personal,
+        count(*) FILTER (
+          WHERE ${table.scope} = 'conversation'
+        )::integer AS conversation
+      FROM ${table}
+      WHERE ${table.createdAtMs} >= ${start.getTime()}
+        AND ${table.createdAtMs} < ${endExclusiveMs}
+      GROUP BY date_trunc(
+        'day',
+        to_timestamp(${table.createdAtMs} / 1000.0) AT TIME ZONE 'UTC'
+      )
+    )
+    SELECT
+      to_char(days.day, 'YYYY-MM-DD') AS date,
+      coalesce(daily.personal, 0)::integer AS personal,
+      coalesce(daily.conversation, 0)::integer AS conversation
+    FROM days
+    LEFT JOIN daily ON daily.day = days.day
+    ORDER BY days.day
+  `);
+  return z.array(memoryDaySchema).parse(queryRows(result));
+}
+
+function formatCount(value: number): string {
+  return new Intl.NumberFormat("en-US").format(value);
+}
+
+function formatPercent(value: number): string {
+  return new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: 0,
+    style: "percent",
+  }).format(value);
+}
+
+/** Build aggregate memory storage and indexing diagnostics for the System page. */
+export async function buildMemoryOperationalReport(args: {
+  db: MemoryDb;
+  nowMs: number;
+}): Promise<PluginOperationalReportContent> {
+  const active = and(
+    isNull(juniorMemoryMemories.archivedAtMs),
+    isNull(juniorMemoryMemories.supersededAtMs),
+    isNull(juniorMemoryMemories.supersededById),
+    or(
+      isNull(juniorMemoryMemories.expiresAtMs),
+      gt(juniorMemoryMemories.expiresAtMs, args.nowMs),
+    ),
+  );
+  const [[counts], memoryDays] = await Promise.all([
+    args.db
+      .select({
+        active: sql<number>`count(*) filter (where ${active})`.mapWith(Number),
+        conversation:
+          sql<number>`count(*) filter (where ${active} and ${juniorMemoryMemories.scope} = 'conversation')`.mapWith(
+            Number,
+          ),
+        createdThirtyDays:
+          sql<number>`count(*) filter (where ${juniorMemoryMemories.createdAtMs} >= ${args.nowMs - 30 * DAY_MS})`.mapWith(
+            Number,
+          ),
+        embedded:
+          sql<number>`count(${juniorMemoryEmbeddings.memoryId}) filter (where ${active})`.mapWith(
+            Number,
+          ),
+        personal:
+          sql<number>`count(*) filter (where ${active} and ${juniorMemoryMemories.scope} = 'personal')`.mapWith(
+            Number,
+          ),
+      })
+      .from(juniorMemoryMemories)
+      .leftJoin(
+        juniorMemoryEmbeddings,
+        eq(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id),
+      ),
+    aggregateMemoryDays(args),
+  ]);
+
+  const activeCount = counts?.active ?? 0;
+  const embeddedCount = counts?.embedded ?? 0;
+  const embeddingCoverage = activeCount === 0 ? 0 : embeddedCount / activeCount;
+
+  return {
+    generatedAt: new Date(args.nowMs).toISOString(),
+    title: "Memory",
+    metrics: [
+      {
+        label: "active memories",
+        tone: activeCount > 0 ? "good" : "neutral",
+        value: formatCount(activeCount),
+      },
+      {
+        label: "created · 30d",
+        value: formatCount(counts?.createdThirtyDays ?? 0),
+      },
+      {
+        label: "personal",
+        value: formatCount(counts?.personal ?? 0),
+      },
+      {
+        label: "conversation",
+        value: formatCount(counts?.conversation ?? 0),
+      },
+      {
+        label: "embedding coverage",
+        tone:
+          activeCount === 0
+            ? "neutral"
+            : embeddedCount === activeCount
+              ? "good"
+              : "warning",
+        value: formatPercent(embeddingCoverage),
+      },
+    ],
+    widgets: [
+      {
+        categories: memoryDays.map((day) => ({
+          id: day.date,
+          label: day.date,
+          values: {
+            conversation: day.conversation,
+            personal: day.personal,
+          },
+        })),
+        description: "Memories stored per day by scope",
+        id: "memories-created",
+        series: [
+          { key: "personal", label: "Personal" },
+          { key: "conversation", label: "Conversation" },
+        ],
+        timeRangeDays: [...WINDOWS],
+        title: "Memories created",
+        type: "bar_chart",
+      },
+    ],
+  };
+}

package/src/personal-store.ts

@@ -0,0 +1,195 @@
+/**
+ * SQL operations over personal memories owned by one authenticated viewer.
+ *
+ * A viewer may resolve to several runtime actors. This store combines their
+ * personal scopes without treating one actor as the canonical identity.
+ */
+import { and, asc, desc, eq, gt, ilike, lt, or, sql } from "drizzle-orm";
+import { z } from "zod";
+import { juniorMemoryEmbeddings, juniorMemoryMemories } from "./db/schema";
+import { deriveMemoryScope, type ResolvedMemoryScope } from "./scope";
+import {
+  activeVisiblePredicate,
+  archiveExpiredMemoryBatch,
+  parseMemoryRow,
+  type MemoryDb,
+  type MemoryRecord,
+} from "./store";
+import type { MemoryRuntimeContext } from "./types";
+
+const nonEmptyStringSchema = z.string().min(1);
+const personalMemoryCursorSchema = z
+  .object({
+    createdAtMs: z.number().finite(),
+    id: nonEmptyStringSchema,
+  })
+  .strict();
+const personalMemoryPageInputSchema = z
+  .object({
+    cursor: personalMemoryCursorSchema.optional(),
+    limit: z.number().int().min(1).max(50),
+    query: z.string().max(200).optional(),
+  })
+  .strict();
+
+export type PersonalMemoryCursor = z.output<typeof personalMemoryCursorSchema>;
+
+export type PersonalMemoryPageInput = z.output<
+  typeof personalMemoryPageInputSchema
+>;
+
+export interface PersonalMemoryPage {
+  memories: MemoryRecord[];
+  nextCursor?: PersonalMemoryCursor;
+}
+
+/** Expected failure when a viewer does not own the requested memory. */
+export class PersonalMemoryNotFoundError extends Error {
+  constructor() {
+    super("Memory was not found for the authenticated viewer.");
+    this.name = "PersonalMemoryNotFoundError";
+  }
+}
+
+/** Viewer-scoped personal memory operations shared by dashboard and REST. */
+export interface PersonalMemoryCollection {
+  /** Archive one exact personal memory owned by a linked actor. */
+  archive(id: string): Promise<MemoryRecord>;
+  /** Read one exact personal memory owned by a linked actor. */
+  get(id: string): Promise<MemoryRecord>;
+  /** List one stable page across every linked personal scope. */
+  list(input: PersonalMemoryPageInput): Promise<PersonalMemoryPage>;
+}
+
+function personalScopes(
+  runtimeContexts: MemoryRuntimeContext[],
+): ResolvedMemoryScope[] {
+  return [
+    ...new Map(
+      runtimeContexts.map((context) => {
+        const scope = deriveMemoryScope(context, "personal");
+        return [`${scope.scope}:${scope.scopeKey}`, scope] as const;
+      }),
+    ).values(),
+  ];
+}
+
+function searchTerms(query: string): string[] {
+  return [
+    ...new Set(
+      query
+        .toLowerCase()
+        .split(/[^a-z0-9_'-]+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2),
+    ),
+  ];
+}
+
+/** Build storage operations for every personal scope linked to one viewer. */
+export function createPersonalMemoryCollection(
+  db: MemoryDb,
+  runtimeContexts: MemoryRuntimeContext[],
+  options: { now?: () => number } = {},
+): PersonalMemoryCollection {
+  const scopes = personalScopes(runtimeContexts);
+  const getNowMs = () => options.now?.() ?? Date.now();
+
+  return {
+    async archive(id) {
+      const memoryId = nonEmptyStringSchema.parse(id);
+      const nowMs = getNowMs();
+      const predicate = activeVisiblePredicate({ nowMs, scopes });
+      if (!predicate) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      const updated = await db
+        .update(juniorMemoryMemories)
+        .set({
+          archivedAtMs: nowMs,
+          archiveReason: "user_removed",
+        })
+        .where(and(predicate, eq(juniorMemoryMemories.id, memoryId)))
+        .returning();
+      if (!updated[0]) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      await db
+        .delete(juniorMemoryEmbeddings)
+        .where(eq(juniorMemoryEmbeddings.memoryId, memoryId));
+      return parseMemoryRow(updated[0]);
+    },
+
+    async get(id) {
+      const memoryId = nonEmptyStringSchema.parse(id);
+      const nowMs = getNowMs();
+      const predicate = activeVisiblePredicate({ nowMs, scopes });
+      if (!predicate) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      const rows = await db
+        .select()
+        .from(juniorMemoryMemories)
+        .where(and(predicate, eq(juniorMemoryMemories.id, memoryId)))
+        .limit(1);
+      if (!rows[0]) {
+        throw new PersonalMemoryNotFoundError();
+      }
+      return parseMemoryRow(rows[0]);
+    },
+
+    async list(input) {
+      input = personalMemoryPageInputSchema.parse(input);
+      const nowMs = getNowMs();
+      await archiveExpiredMemoryBatch({ db, nowMs, scopes });
+      const active = activeVisiblePredicate({ nowMs, scopes });
+      if (!active) {
+        return { memories: [] };
+      }
+
+      const cursor = input.cursor
+        ? or(
+            lt(juniorMemoryMemories.createdAtMs, input.cursor.createdAtMs),
+            and(
+              eq(juniorMemoryMemories.createdAtMs, input.cursor.createdAtMs),
+              gt(juniorMemoryMemories.id, input.cursor.id),
+            ),
+          )
+        : undefined;
+      const terms = input.query ? searchTerms(input.query) : [];
+      const search =
+        input.query === undefined
+          ? undefined
+          : terms.length === 0
+            ? sql`false`
+            : or(
+                ...terms.map((term) =>
+                  ilike(juniorMemoryMemories.content, `%${term}%`),
+                ),
+              );
+      const rows = await db
+        .select()
+        .from(juniorMemoryMemories)
+        .where(and(active, cursor, search))
+        .orderBy(
+          desc(juniorMemoryMemories.createdAtMs),
+          asc(juniorMemoryMemories.id),
+        )
+        .limit(input.limit + 1);
+      const hasNextPage = rows.length > input.limit;
+      const memories = rows.slice(0, input.limit).map(parseMemoryRow);
+      const last = memories.at(-1);
+      return {
+        memories,
+        ...(hasNextPage && last
+          ? {
+              nextCursor: {
+                createdAtMs: last.createdAtMs,
+                id: last.id,
+              },
+            }
+          : {}),
+      };
+    },
+  };
+}

package/src/personal.ts

@@ -0,0 +1,120 @@
+/**
+ * Authenticated-viewer memory access shared by REST and dashboard projections.
+ *
+ * Viewer identity may resolve to multiple platform actors. This module keeps
+ * that federation behind one personal-memory collection.
+ */
+import { z } from "zod";
+import type { PluginUserPageActor } from "@sentry/junior-plugin-api";
+import { createPersonalMemoryCollection } from "./personal-store";
+import type { MemoryDb, MemoryRecord } from "./store";
+import type { MemoryRuntimeContext } from "./types";
+
+const cursorSchema = z
+  .object({
+    createdAtMs: z.number().finite(),
+    id: z.string().min(1),
+    query: z.string().max(200).optional(),
+    version: z.literal(1),
+  })
+  .strict();
+
+export interface ViewerMemoryPage {
+  memories: MemoryRecord[];
+  nextCursor?: string;
+}
+
+export interface ViewerMemoryPageInput {
+  cursor?: string;
+  limit: number;
+  query?: string;
+}
+
+export class InvalidMemoryCursorError extends Error {
+  constructor() {
+    super("Memory cursor is invalid.");
+    this.name = "InvalidMemoryCursorError";
+  }
+}
+
+export { PersonalMemoryNotFoundError } from "./personal-store";
+
+function runtimeContext(actor: PluginUserPageActor): MemoryRuntimeContext {
+  if (actor.platform === "slack") {
+    return {
+      actor,
+      source: {
+        platform: "slack",
+        type: "priv",
+        teamId: actor.teamId,
+        channelId: "DDASHBOARD",
+      },
+    };
+  }
+  return {
+    actor,
+    source: {
+      platform: "local",
+      type: "priv",
+      conversationId: "local:dashboard:memories",
+    },
+  };
+}
+
+function decodeCursor(value: string | undefined, query: string | undefined) {
+  if (!value) return undefined;
+  try {
+    const parsed = cursorSchema.parse(
+      JSON.parse(Buffer.from(value, "base64url").toString("utf8")),
+    );
+    if (parsed.query !== query) {
+      throw new InvalidMemoryCursorError();
+    }
+    return { createdAtMs: parsed.createdAtMs, id: parsed.id };
+  } catch {
+    throw new InvalidMemoryCursorError();
+  }
+}
+
+function encodeCursor(
+  cursor: { createdAtMs: number; id: string },
+  query: string | undefined,
+): string {
+  return Buffer.from(
+    JSON.stringify({ ...cursor, ...(query ? { query } : {}), version: 1 }),
+    "utf8",
+  ).toString("base64url");
+}
+
+/** Build personal-memory operations authorized by a viewer's linked actors. */
+export function createViewerMemories(
+  db: MemoryDb,
+  actors: PluginUserPageActor[],
+) {
+  const collection = createPersonalMemoryCollection(
+    db,
+    actors.map(runtimeContext),
+  );
+  return {
+    async archive(id: string): Promise<MemoryRecord> {
+      return await collection.archive(id);
+    },
+    async get(id: string): Promise<MemoryRecord> {
+      return await collection.get(id);
+    },
+    async list(input: ViewerMemoryPageInput): Promise<ViewerMemoryPage> {
+      const query = input.query?.trim() || undefined;
+      const page = await collection.list({
+        cursor: decodeCursor(input.cursor, query),
+        limit: input.limit,
+        ...(query ? { query } : {}),
+      });
+      return {
+        memories: page.memories,
+        ...(page.nextCursor
+          ? { nextCursor: encodeCursor(page.nextCursor, query) }
+          : {}),
+      };
+    },
+  };
+}