@sentry/junior-memory 0.197.0 → 0.199.0

package/src/tools.ts

@@ -1,586 +0,0 @@
-import { Type, type Static } from "@sinclair/typebox";
-import { Value } from "@sinclair/typebox/value";
-import {
-  definePluginTool,
-  getSourceKey,
-  PluginToolInputError,
-  type PluginToolOutput,
-  type Source,
-  type Actor,
-  type Identity,
-  type User,
-  pluginToolOutputSchema,
-} from "@sentry/junior-plugin-api";
-import { z } from "zod";
-import {
-  createMemoryStore,
-  type CreateMemoryInput,
-  type MemoryEmbeddingProvider,
-  type MemoryDb,
-  type MemoryRecord,
-  type MemorySupersessionDecider,
-} from "./store";
-import {
-  parseCreateMemoryRequest,
-  parseMemoryReview,
-  type MemoryAgent,
-} from "./agent";
-import {
-  memoryRuntimeContextSchema,
-  type MemoryKind,
-  type MemoryRuntimeContext,
-} from "./types";
-
-export type MemoryReviewer = Pick<MemoryAgent, "reviewCreateRequest">;
-
-const MAX_TOOL_CONTENT_CHARS = 4_000;
-const DEFAULT_RESULT_LIMIT = 20;
-const DEFAULT_SEARCH_LIMIT = 10;
-
-const KNOWN_TOOL_INPUT_ERROR_MESSAGES = new Set([
-  "Conversation memory requires conversation context.",
-  "Conversation-subject memory requires conversation context.",
-  "Memory content is required.",
-  "Memory content exceeds the maximum length.",
-  "Memory id is required.",
-  "Memory was not found in the current context.",
-  "Memory id prefix is ambiguous.",
-  "Private memory requires a User.",
-  "User memory requires a User.",
-]);
-
-/** Runtime-owned context used to bind memory tools to visible scopes. */
-export interface MemoryToolContext {
-  agent: MemoryReviewer;
-  conversationId?: string;
-  db: MemoryDb;
-  embedder?: MemoryEmbeddingProvider;
-  locationId?: string;
-  actor?: Actor;
-  source: Source;
-  users: {
-    resolveActor(): Promise<{ identity: Identity; user?: User } | undefined>;
-  };
-  userText?: string;
-}
-
-export interface MemoryCreateToolContext extends MemoryToolContext {
-  supersessionDecider?: MemorySupersessionDecider;
-}
-
-function throwToolInputError(message: string): never {
-  throw new PluginToolInputError(message);
-}
-
-function asToolInputError(error: unknown): never {
-  if (error instanceof PluginToolInputError) {
-    throw error;
-  }
-  if (
-    error instanceof Error &&
-    KNOWN_TOOL_INPUT_ERROR_MESSAGES.has(error.message)
-  ) {
-    throw new PluginToolInputError(error.message, { cause: error });
-  }
-  throw error;
-}
-
-async function memoryRuntimeContext(
-  context: MemoryToolContext,
-): Promise<MemoryRuntimeContext> {
-  const actorUser = (await context.users.resolveActor())?.user;
-  return memoryRuntimeContextSchema.parse({
-    ...(context.conversationId
-      ? { conversationId: context.conversationId }
-      : undefined),
-    ...(context.actor ? { actor: context.actor } : undefined),
-    ...(context.locationId ? { locationId: context.locationId } : undefined),
-    source: context.source,
-    ...(actorUser ? { userId: actorUser.id } : undefined),
-  });
-}
-
-function memoryStore(
-  context: MemoryToolContext,
-  runtimeContext: MemoryRuntimeContext,
-  options: { supersessionDecider?: MemorySupersessionDecider } = {},
-) {
-  return createMemoryStore(context.db, runtimeContext, {
-    embedder: context.embedder,
-    ...(options.supersessionDecider
-      ? { supersessionDecider: options.supersessionDecider }
-      : undefined),
-  });
-}
-
-function boundedLimit(value: number | undefined, fallback: number): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    return fallback;
-  }
-  return Math.min(50, Math.max(1, Math.floor(value)));
-}
-
-function digitAt(value: string, index: number): boolean {
-  const code = value.charCodeAt(index);
-  return code >= 48 && code <= 57;
-}
-
-function readDigits(
-  value: string,
-  start: number,
-  length: number,
-): number | undefined {
-  for (let index = start; index < start + length; index++) {
-    if (!digitAt(value, index)) {
-      return undefined;
-    }
-  }
-  return Number(value.slice(start, start + length));
-}
-
-function parseIsoTimestampParts(value: string) {
-  if (
-    value.length < 20 ||
-    value[4] !== "-" ||
-    value[7] !== "-" ||
-    value[10] !== "T" ||
-    value[13] !== ":" ||
-    value[16] !== ":"
-  ) {
-    return undefined;
-  }
-  const year = readDigits(value, 0, 4);
-  const month = readDigits(value, 5, 2);
-  const day = readDigits(value, 8, 2);
-  const hour = readDigits(value, 11, 2);
-  const minute = readDigits(value, 14, 2);
-  const second = readDigits(value, 17, 2);
-  if (
-    year === undefined ||
-    month === undefined ||
-    day === undefined ||
-    hour === undefined ||
-    minute === undefined ||
-    second === undefined
-  ) {
-    return undefined;
-  }
-
-  let zoneStart = 19;
-  if (value[zoneStart] === ".") {
-    zoneStart += 1;
-    const fractionStart = zoneStart;
-    while (zoneStart < value.length && digitAt(value, zoneStart)) {
-      zoneStart += 1;
-    }
-    if (zoneStart === fractionStart) {
-      return undefined;
-    }
-  }
-
-  if (value[zoneStart] === "Z") {
-    if (zoneStart !== value.length - 1) {
-      return undefined;
-    }
-  } else if (value[zoneStart] === "+" || value[zoneStart] === "-") {
-    if (
-      zoneStart !== value.length - 6 ||
-      value[zoneStart + 3] !== ":" ||
-      readDigits(value, zoneStart + 1, 2) === undefined ||
-      readDigits(value, zoneStart + 4, 2) === undefined
-    ) {
-      return undefined;
-    }
-  } else {
-    return undefined;
-  }
-
-  return { day, hour, minute, month, second, year };
-}
-
-function parseExpiresAt(value: string | undefined): number | undefined {
-  if (!value) {
-    return undefined;
-  }
-  if (value === "never") {
-    return undefined;
-  }
-  const parts = parseIsoTimestampParts(value);
-  const expiresAtMs = Date.parse(value);
-  if (!parts || !Number.isFinite(expiresAtMs)) {
-    throwToolInputError('expires_at must be "never" or a valid ISO timestamp.');
-  }
-  const calendarDate = new Date(
-    Date.UTC(parts.year, parts.month - 1, parts.day),
-  );
-  if (
-    calendarDate.getUTCFullYear() !== parts.year ||
-    calendarDate.getUTCMonth() !== parts.month - 1 ||
-    calendarDate.getUTCDate() !== parts.day ||
-    parts.hour > 23 ||
-    parts.minute > 59 ||
-    parts.second > 59
-  ) {
-    throwToolInputError('expires_at must be "never" or a valid ISO timestamp.');
-  }
-  return expiresAtMs;
-}
-
-function requireToolCallId(value: string | undefined): string {
-  if (!value) {
-    throwToolInputError("Memory creation requires a tool call id.");
-  }
-  return value;
-}
-
-function requireMemoryContent(value: string): string {
-  if (value.trim().length === 0) {
-    throwToolInputError("Memory content is required.");
-  }
-  return value;
-}
-
-const createMemoryInputSchema = z
-  .object({
-    content: z
-      .string()
-      .min(1)
-      .max(MAX_TOOL_CONTENT_CHARS)
-      .describe(
-        "Self-contained memory candidate. Include the subject in natural language when it matters; do not rely on surrounding chat context.",
-      ),
-    expires_at: z
-      .string()
-      .min(1)
-      .describe(
-        'Expiration selector. Omit or use "never" when the memory should not expire, or use an exact ISO timestamp such as "2027-06-21T00:00:00Z".',
-      )
-      .optional(),
-  })
-  .strict();
-
-const removeMemoryInputSchema = z
-  .object({
-    id: z
-      .string()
-      .min(1)
-      .describe("Memory id or unambiguous short id prefix to remove."),
-  })
-  .strict();
-
-const listMemoriesInputSchema = z
-  .object({
-    limit: z
-      .number()
-      .min(1)
-      .max(50)
-      .describe("Maximum number of visible memories to return.")
-      .optional(),
-  })
-  .strict();
-
-const searchMemoriesInputSchema = z
-  .object({
-    query: z
-      .string()
-      .min(1)
-      .describe("Search query for visible memory content."),
-    limit: z
-      .number()
-      .min(1)
-      .max(50)
-      .describe("Maximum number of matching memories to return.")
-      .optional(),
-  })
-  .strict();
-
-const memoryToolProjectionSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1 }),
-    content: Type.String({ minLength: 1 }),
-    createdAtMs: Type.Number(),
-    observedAtMs: Type.Number(),
-    expiresAtMs: Type.Optional(Type.Number()),
-  },
-  { additionalProperties: false },
-);
-type MemoryToolProjection = Static<typeof memoryToolProjectionSchema>;
-
-type MemoryStructuredToolResult<TData extends Record<string, unknown>> =
-  PluginToolOutput &
-    TData & {
-      target: string;
-    };
-
-const memoryProjectionOutputSchema = z.object({
-  id: z.string(),
-  content: z.string(),
-  createdAtMs: z.number(),
-  observedAtMs: z.number(),
-  expiresAtMs: z.number().optional(),
-});
-
-const memoryCreateOutputSchema = pluginToolOutputSchema.extend({
-  target: z.string(),
-  created: z.boolean(),
-  memory: memoryProjectionOutputSchema,
-});
-
-const memorySingleOutputSchema = pluginToolOutputSchema.extend({
-  target: z.string(),
-  memory: memoryProjectionOutputSchema,
-});
-
-const memoryManyOutputSchema = pluginToolOutputSchema.extend({
-  target: z.string(),
-  memories: z.array(memoryProjectionOutputSchema),
-});
-
-function parseMemoryToolInput<T>(schema: z.ZodType<T>, input: unknown): T {
-  const result = schema.safeParse(input);
-  if (!result.success) {
-    throw new PluginToolInputError("Invalid memory tool input.", {
-      cause: result.error,
-    });
-  }
-  return result.data;
-}
-
-function sourceIdempotencyKey(context: MemoryToolContext): string {
-  const sourceKey = getSourceKey(context.source);
-  if (!sourceKey) {
-    throwToolInputError("Memory creation requires source message context.");
-  }
-  return sourceKey;
-}
-
-function createInput(
-  context: MemoryToolContext,
-  input: { content: string; expiresAtMs?: number; kind: MemoryKind },
-  toolCallId: string,
-) {
-  return {
-    content: requireMemoryContent(input.content),
-    idempotencyKey: `tool:${sourceIdempotencyKey(context)}:${toolCallId}`,
-    kind: input.kind,
-    ...(input.expiresAtMs !== undefined
-      ? { expiresAtMs: input.expiresAtMs }
-      : undefined),
-  } satisfies CreateMemoryInput;
-}
-
-function targetForKind(kind: MemoryKind): "actor" | "conversation" {
-  if (kind === "preference") {
-    return "actor";
-  }
-  return "conversation";
-}
-
-/** Return the model-visible projection without hidden ownership/source fields. */
-function compactMemory(memory: MemoryRecord): MemoryToolProjection {
-  return Value.Parse(memoryToolProjectionSchema, {
-    id: memory.id,
-    content: memory.content,
-    createdAtMs: memory.createdAtMs,
-    observedAtMs: memory.observedAtMs,
-    ...(memory.expiresAtMs !== undefined
-      ? { expiresAtMs: memory.expiresAtMs }
-      : undefined),
-  });
-}
-
-function memoryToolResult<TData extends Record<string, unknown>>(
-  target: string,
-  data: TData,
-): MemoryStructuredToolResult<TData> {
-  return {
-    target,
-    ...data,
-  };
-}
-
-/** Create a tool that submits an explicit memory candidate for storage. */
-export function createMemoryCreateTool(context: MemoryCreateToolContext) {
-  return definePluginTool({
-    approvalMode: "approve",
-    annotations: {
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-      readOnlyHint: false,
-    },
-    description:
-      "Explicit memory-write tool. Use only when the latest user message directly asks Junior to remember, store, save, or forget-and-replace a fact. Do not use for ordinary statements like 'I prefer X', 'I use Y', or 'X goes before Y' unless the user also asks you to remember/store/save it; passive memory learning handles those after the visible reply. Pass one self-contained natural-language candidate preserving the user's explicit memory intent. Do not ask the user to rephrase ordinary first-person facts, and do not rewrite them into display-name or third-person wording. Do not include secrets, private personal details, medical/legal/financial/sensitive facts, or another person's personal preference, opinion, habit, identity, relationship, workflow, or private life. Junior sets access, Location, Source, and subject. The memory agent rewrites the content and sets the memory kind.",
-    executionMode: "sequential",
-    inputSchema: createMemoryInputSchema,
-    outputSchema: memoryCreateOutputSchema,
-    execute: async (input, options) => {
-      const parsedInput = parseMemoryToolInput(createMemoryInputSchema, input);
-      const toolCallId = requireToolCallId(options.toolCallId);
-      const requestedExpiresAtMs = parseExpiresAt(parsedInput.expires_at);
-      const runtimeContext = await memoryRuntimeContext(context);
-      const store = memoryStore(context, runtimeContext, {
-        supersessionDecider: context.supersessionDecider,
-      });
-      const review = await (async () => {
-        try {
-          return parseMemoryReview(
-            await context.agent.reviewCreateRequest(
-              parseCreateMemoryRequest({
-                content: requireMemoryContent(parsedInput.content),
-                ...(requestedExpiresAtMs !== undefined
-                  ? { expiresAtMs: requestedExpiresAtMs }
-                  : undefined),
-                runtimeContext,
-                ...(context.userText?.trim()
-                  ? {
-                      sourceContext: {
-                        currentUserText: context.userText.trim(),
-                      },
-                    }
-                  : undefined),
-              }),
-            ),
-          );
-        } catch (error) {
-          if (error instanceof PluginToolInputError) {
-            throw error;
-          }
-          const detail =
-            error instanceof Error && error.message.trim()
-              ? `: ${error.message}`
-              : "";
-          throw new PluginToolInputError(
-            `Memory agent review failed${detail}`,
-            { cause: error },
-          );
-        }
-      })();
-      if (review.decision === "reject") {
-        throw new PluginToolInputError(
-          `Memory was not stored: ${review.reason}`,
-        );
-      }
-      const memoryInput = createInput(
-        context,
-        {
-          content: review.content,
-          kind: review.kind,
-          ...(review.expiresAtMs !== undefined
-            ? { expiresAtMs: review.expiresAtMs }
-            : requestedExpiresAtMs !== undefined
-              ? { expiresAtMs: requestedExpiresAtMs }
-              : {}),
-        },
-        toolCallId,
-      );
-      const result = await (async () => {
-        try {
-          if (targetForKind(review.kind) === "conversation") {
-            return await store.createConversationMemory(memoryInput);
-          }
-          return await store.createMemory(memoryInput);
-        } catch (error) {
-          asToolInputError(error);
-        }
-      })();
-      return memoryToolResult("createMemory", {
-        created: result.created,
-        memory: compactMemory(result.memory),
-      });
-    },
-  });
-}
-
-/** Create a tool that archives a visible memory in the active context. */
-export function createMemoryRemoveTool(context: MemoryToolContext) {
-  return definePluginTool({
-    annotations: {
-      destructiveHint: true,
-      idempotentHint: true,
-      openWorldHint: false,
-      readOnlyHint: false,
-    },
-    description:
-      "Forget one private memory owned by the current User. Public memories are read-only. Use only ids or short id prefixes returned by listMemories or searchMemories. Never remove memories by hidden Actor, provider, scope, or subject ids.",
-    executionMode: "sequential",
-    inputSchema: removeMemoryInputSchema,
-    outputSchema: memorySingleOutputSchema,
-    execute: async (input) => {
-      const parsedInput = parseMemoryToolInput(removeMemoryInputSchema, input);
-      const runtimeContext = await memoryRuntimeContext(context);
-      const memory = await (async () => {
-        try {
-          return await memoryStore(context, runtimeContext).archiveMemory({
-            id: parsedInput.id,
-            reason: "tool_removed",
-          });
-        } catch (error) {
-          asToolInputError(error);
-        }
-      })();
-      return memoryToolResult("removeMemory", {
-        memory: compactMemory(memory),
-      });
-    },
-  });
-}
-
-/** Create a tool that lists visible active memories in the active context. */
-export function createMemoryListTool(context: MemoryToolContext) {
-  return definePluginTool({
-    description:
-      "List active memories visible in the current context. Use when the user asks what Junior remembers or when memory ids are needed before removing a memory.",
-    annotations: {
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-      readOnlyHint: true,
-    },
-    inputSchema: listMemoriesInputSchema,
-    outputSchema: memoryManyOutputSchema,
-    execute: async (input) => {
-      const parsedInput = parseMemoryToolInput(listMemoriesInputSchema, input);
-      const runtimeContext = await memoryRuntimeContext(context);
-      const memories = await memoryStore(context, runtimeContext).listMemories({
-        limit: boundedLimit(parsedInput.limit, DEFAULT_RESULT_LIMIT),
-      });
-      return memoryToolResult("listMemories", {
-        memories: memories.map(compactMemory),
-      });
-    },
-  });
-}
-
-/** Create a tool that searches visible active memories in the active context. */
-export function createMemorySearchTool(context: MemoryToolContext) {
-  return definePluginTool({
-    description:
-      "Search active memories visible in the current context. Use when the model needs targeted memory recall. Public memories are visible everywhere. Private memories belong to the current User.",
-    annotations: {
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-      readOnlyHint: true,
-    },
-    inputSchema: searchMemoriesInputSchema,
-    outputSchema: memoryManyOutputSchema,
-    execute: async (input) => {
-      const parsedInput = parseMemoryToolInput(
-        searchMemoriesInputSchema,
-        input,
-      );
-      const runtimeContext = await memoryRuntimeContext(context);
-      const memories = await memoryStore(
-        context,
-        runtimeContext,
-      ).searchMemories({
-        query: parsedInput.query,
-        limit: boundedLimit(parsedInput.limit, DEFAULT_SEARCH_LIMIT),
-      });
-      return memoryToolResult("searchMemories", {
-        memories: memories.map(compactMemory),
-      });
-    },
-  });
-}

package/src/types.ts

@@ -1,37 +0,0 @@
-import { actorSchema, sourceSchema } from "@sentry/junior-plugin-api";
-import { z } from "zod";
-
-export const MEMORY_KINDS = ["preference", "procedure", "knowledge"] as const;
-
-export const MEMORY_SCOPES = ["private", "public"] as const;
-export const MEMORY_SUBJECT_TYPES = [
-  "user",
-  "conversation",
-  "general",
-] as const;
-// Durable attribution follows Source kind, including dashboard roots.
-export const MEMORY_SOURCE_PLATFORMS = ["slack", "local", "web"] as const;
-export const MEMORY_EMBEDDING_METRICS = ["cosine"] as const;
-export const MEMORY_EMBEDDING_DIMENSIONS = 1536;
-
-export type MemoryKind = (typeof MEMORY_KINDS)[number];
-export type MemoryScope = (typeof MEMORY_SCOPES)[number];
-export type MemorySubjectType = (typeof MEMORY_SUBJECT_TYPES)[number];
-export type MemorySourcePlatform = (typeof MEMORY_SOURCE_PLATFORMS)[number];
-export type MemoryEmbeddingMetric = (typeof MEMORY_EMBEDDING_METRICS)[number];
-
-const nonEmptyStringSchema = z.string().min(1);
-
-/** Host data used to set memory access, subject, and source. */
-export const memoryRuntimeContextSchema = z
-  .object({
-    conversationId: nonEmptyStringSchema.optional(),
-    locationId: nonEmptyStringSchema.optional(),
-    actor: actorSchema.optional(),
-    source: sourceSchema,
-    /** User linked to the active Actor. */
-    userId: nonEmptyStringSchema.optional(),
-  })
-  .strict();
-
-export type MemoryRuntimeContext = z.output<typeof memoryRuntimeContextSchema>;