agent-relay-server 0.32.1 → 0.32.3

package/src/routes/memory.ts

@@ -0,0 +1,337 @@
+// Auto-split from routes.ts (#299). Domain: memory.
+import { MAX_BODY_BYTES } from "../config";
+import { ValidationError, getAgent } from "../db";
+import { assertMemoryCreateAllowed, assertMemoryUpdateAllowed } from "../memory-security";
+import { authorizeRoute, emitCommand, error, json, memoryContext, memoryErrorResponse, parseBody, type Handler } from "./_shared";
+import { cleanParams, cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { getComponentAuth } from "../security";
+import { injectMemoryContext, memoryBroker, memoryBrokerConfig } from "../memory-service";
+import { isRecord } from "agent-relay-sdk";
+import { type ContextBudget, type CreateMemoryInput, type MemoryBrokerContext, type MemoryConfidence, type MemoryQuery, type MemoryRedactionState, type MemorySensitivity, type MemoryType, type MemoryVisibility, type TaskRoutingHints, type UpdateMemoryInput } from "../types";
+
+const VALID_MEMORY_TYPES = ["organization", "role", "project", "task", "interaction", "agent"] as const;
+
+const VALID_MEMORY_VISIBILITIES = ["private", "project", "org", "public"] as const;
+
+const VALID_MEMORY_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
+
+const VALID_MEMORY_CONFIDENCES = ["reported", "inferred", "verified"] as const;
+
+const VALID_MEMORY_REDACTION_STATES = ["raw", "redacted", "rejected"] as const;
+
+function cleanMemoryQueryFromParams(params: URLSearchParams): MemoryQuery {
+  const query: MemoryQuery = {};
+  const type = params.get("type");
+  const scope = params.get("scope");
+  const visibility = params.get("visibility");
+  const minRelevance = params.get("minRelevance");
+  const limit = params.get("limit");
+  if (type) query.type = optionalEnum(type, "type", VALID_MEMORY_TYPES) as MemoryType;
+  if (scope) query.scope = cleanString(scope, "scope", { max: 240 });
+  const tags = [...params.getAll("tag"), ...(params.get("tags")?.split(",") ?? [])].map((tag) => tag.trim()).filter(Boolean);
+  if (tags.length) query.tags = cleanStringArray(tags, "tags", { itemMax: 80, maxItems: 50 });
+  if (minRelevance !== null) {
+    const parsed = Number(minRelevance);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) throw new ValidationError("minRelevance must be between 0 and 1");
+    query.minRelevance = parsed;
+  }
+  if (limit !== null) {
+    const parsed = Number(limit);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > 100) throw new ValidationError("limit must be an integer between 1 and 100");
+    query.limit = parsed;
+  }
+  if (visibility) query.visibility = optionalEnum(visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility;
+  query.includeExpired = params.get("includeExpired") === "true" ? true : undefined;
+  query.includeSensitive = params.get("includeSensitive") === "true" ? true : undefined;
+  return query;
+}
+
+function cleanMemoryQueryFromBody(body: unknown): MemoryQuery {
+  if (!isRecord(body)) throw new ValidationError("memory query body must be an object");
+  const query: MemoryQuery = {};
+  query.type = optionalEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType | undefined;
+  query.scope = cleanString(body.scope, "scope", { max: 240 });
+  query.tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
+  if (body.minRelevance !== undefined) {
+    if (typeof body.minRelevance !== "number" || body.minRelevance < 0 || body.minRelevance > 1) throw new ValidationError("minRelevance must be between 0 and 1");
+    query.minRelevance = body.minRelevance;
+  }
+  if (body.limit !== undefined) {
+    if (typeof body.limit !== "number" || !Number.isSafeInteger(body.limit) || body.limit <= 0 || body.limit > 100) throw new ValidationError("limit must be an integer between 1 and 100");
+    query.limit = body.limit;
+  }
+  query.includeExpired = typeof body.includeExpired === "boolean" ? body.includeExpired : undefined;
+  query.visibility = optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
+  query.includeSensitive = typeof body.includeSensitive === "boolean" ? body.includeSensitive : undefined;
+  return query;
+}
+
+function authorizeMemoryScope(req: Request, scope: string | undefined, requiredScope: "memory:read" | "memory:write" | "memory:admin"): Response | null {
+  const component = getComponentAuth(req);
+  if (component?.constraints?.memoryScopes?.length && !scope) {
+    return error("memory scope required for constrained token", 403);
+  }
+  return authorizeRoute(req, {
+    scope: requiredScope,
+    resource: scope ? { memoryScope: scope } : undefined,
+  });
+}
+
+function cleanCreateMemoryInput(body: unknown, ctx: MemoryBrokerContext): CreateMemoryInput {
+  if (!isRecord(body)) throw new ValidationError("memory body must be an object");
+  const ttlMs = body.ttlMs === undefined
+    ? undefined
+    : cleanMemoryPositiveInteger(body.ttlMs, "ttlMs");
+  return {
+    type: optionalEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType,
+    scope: cleanString(body.scope, "scope", { required: true, max: 240 })!,
+    title: cleanString(body.title, "title", { required: true, max: 240 })!,
+    content: cleanString(body.content, "content", { required: true, max: MAX_BODY_BYTES })!,
+    tags: cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 }),
+    visibility: optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined,
+    sensitivity: optionalEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined,
+    confidence: optionalEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined,
+    redactionState: optionalEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined,
+    relevanceScore: cleanMemoryScore(body.relevanceScore, "relevanceScore"),
+    sourceAgent: cleanString(body.sourceAgent, "sourceAgent", { max: 200 }),
+    sourceTask: body.sourceTask === undefined ? undefined : cleanMemoryPositiveInteger(body.sourceTask, "sourceTask"),
+    createdBy: cleanString(body.createdBy, "createdBy", { max: 200 }) ?? ctx.actor,
+    metadata: cleanParams(body.metadata, "metadata"),
+    ttlMs,
+  };
+}
+
+function cleanUpdateMemoryInput(body: unknown): UpdateMemoryInput {
+  if (!isRecord(body)) throw new ValidationError("memory patch body must be an object");
+  const patch: UpdateMemoryInput = {};
+  const title = cleanString(body.title, "title", { max: 240 });
+  const content = cleanString(body.content, "content", { max: MAX_BODY_BYTES });
+  const tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
+  const visibility = optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
+  const sensitivity = optionalEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined;
+  const confidence = optionalEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined;
+  const redactionState = optionalEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined;
+  const relevanceScore = cleanMemoryScore(body.relevanceScore, "relevanceScore");
+  const metadata = cleanParams(body.metadata, "metadata");
+  if (title !== undefined) patch.title = title;
+  if (content !== undefined) patch.content = content;
+  if (tags !== undefined) patch.tags = tags;
+  if (visibility !== undefined) patch.visibility = visibility;
+  if (sensitivity !== undefined) patch.sensitivity = sensitivity;
+  if (confidence !== undefined) patch.confidence = confidence;
+  if (redactionState !== undefined) patch.redactionState = redactionState;
+  if (relevanceScore !== undefined) patch.relevanceScore = relevanceScore;
+  if (metadata !== undefined) patch.metadata = metadata;
+  if (Object.prototype.hasOwnProperty.call(body, "expiresAt")) {
+    patch.expiresAt = body.expiresAt === null ? null : cleanMemoryPositiveInteger(body.expiresAt, "expiresAt");
+  }
+  if (Object.keys(patch).length === 0) throw new ValidationError("memory patch must include at least one field");
+  return patch;
+}
+
+function cleanMemoryInjectInput(body: unknown): {
+  agentId: string;
+  memoryIds: string[];
+  query?: MemoryQuery;
+  task?: TaskRoutingHints;
+  budget?: ContextBudget;
+  reason: string;
+} {
+  if (!isRecord(body)) throw new ValidationError("memory injection body must be an object");
+  const agentId = cleanString(body.agentId ?? body.target, "agentId", { required: true, max: 200 })!;
+  const memoryIds = cleanStringArray(body.memoryIds, "memoryIds", { itemMax: 80, maxItems: 50 }) ?? [];
+  const query = body.query === undefined ? undefined : cleanMemoryQueryFromBody(body.query);
+  if (memoryIds.length === 0 && !query) throw new ValidationError("memoryIds or query required");
+  return {
+    agentId,
+    memoryIds,
+    query,
+    task: cleanTaskRoutingHints(body.task),
+    budget: cleanContextBudget(body.budget),
+    reason: cleanString(body.reason, "reason", { max: 200 }) ?? "manual",
+  };
+}
+
+function cleanTaskRoutingHints(value: unknown): TaskRoutingHints | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("task must be an object");
+  const id = value.id === undefined ? undefined : cleanMemoryPositiveInteger(value.id, "task.id");
+  return {
+    id,
+    title: cleanString(value.title, "task.title", { max: 240 }),
+    text: cleanString(value.text, "task.text", { max: 4000 }),
+    scope: cleanString(value.scope, "task.scope", { max: 240 }),
+    tags: cleanStringArray(value.tags, "task.tags", { itemMax: 80, maxItems: 50 }),
+    capabilities: cleanStringArray(value.capabilities, "task.capabilities", { itemMax: 80, maxItems: 50 }),
+    target: cleanString(value.target, "task.target", { max: 200 }),
+  };
+}
+
+function cleanContextBudget(value: unknown): ContextBudget | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("budget must be an object");
+  const maxTokens = cleanMemoryPositiveInteger(value.maxTokens, "budget.maxTokens");
+  const maxMemories = cleanMemoryPositiveInteger(value.maxMemories, "budget.maxMemories");
+  const priorityCutoff = value.priorityCutoff;
+  if (priorityCutoff !== 1 && priorityCutoff !== 2 && priorityCutoff !== 3) throw new ValidationError("budget.priorityCutoff must be 1, 2, or 3");
+  return { maxTokens, maxMemories, priorityCutoff };
+}
+
+function cleanMemoryPositiveInteger(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+function cleanMemoryScore(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) throw new ValidationError(`${field} must be between 0 and 1`);
+  return value;
+}
+
+export const getMemories: Handler = async (req) => {
+  try {
+    const query = cleanMemoryQueryFromParams(new URL(req.url).searchParams);
+    const denied = authorizeMemoryScope(req, query.scope, "memory:read");
+    if (denied) return denied;
+    return json(await memoryBroker.search(query, memoryContext(req)));
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const postMemorySearch: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const query = cleanMemoryQueryFromBody(parsed.body ?? {});
+    const denied = authorizeMemoryScope(req, query.scope, "memory:read");
+    if (denied) return denied;
+    return json(await memoryBroker.search(query, memoryContext(req)));
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const postMemory: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const ctx = memoryContext(req);
+    const input = cleanCreateMemoryInput(parsed.body, ctx);
+    const denied = authorizeMemoryScope(req, input.scope, "memory:write");
+    if (denied) return denied;
+    assertMemoryCreateAllowed(input, ctx);
+    return json(await memoryBroker.create(input, ctx), 201);
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const getMemoryStats: Handler = async (req) => {
+  try {
+    return json(await memoryBroker.stats(memoryContext(req)));
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const getMemoryBrokerInfo: Handler = async () => {
+  try {
+    const capabilities = await memoryBroker.capabilities();
+    return json({
+      type: memoryBrokerConfig.type,
+      external: capabilities.external,
+      capabilities,
+      config: publicMemoryBrokerConfig(),
+    });
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const postMemoryInject: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = cleanMemoryInjectInput(parsed.body);
+    const agent = getAgent(input.agentId);
+    if (!agent) return error("agent not found", 404);
+    const ctx = memoryContext(req);
+    const result = await injectMemoryContext({
+      agent,
+      memoryIds: input.memoryIds,
+      query: input.query,
+      task: input.task,
+      budget: input.budget,
+      reason: input.reason,
+      source: "system",
+      ctx,
+    });
+    if (!result) return error("no injectable memories matched", 400);
+    emitCommand(result.command);
+    return json(result, 202);
+  } catch (e) {
+    return memoryErrorResponse(e);
+  }
+};
+
+export const getMemoryById: Handler = async (req, params) => {
+  const ctx = memoryContext(req);
+  const memory = await memoryBroker.get(params.id!, ctx);
+  if (!memory) return error("memory not found", 404);
+  const denied = authorizeMemoryScope(req, memory.scope, "memory:read");
+  if (denied) return denied;
+  if (memory.redactionState === "rejected") return error("memory not found", 404);
+  if (memory.sensitivity === "secret" && !memoryContextHasAdmin(ctx)) return error("memory not found", 404);
+  return json(memory);
+};
+
+export const patchMemory: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const ctx = memoryContext(req);
+    const patch = cleanUpdateMemoryInput(parsed.body);
+    const current = await memoryBroker.get(params.id!, ctx);
+    if (!current) return error("memory not found", 404);
+    const denied = authorizeMemoryScope(req, current.scope, "memory:write");
+    if (denied) return denied;
+    assertMemoryUpdateAllowed(patch, ctx);
+    return json(await memoryBroker.update(params.id!, patch, ctx));
+  } catch (e) {
+    if (e instanceof ValidationError && e.message === "memory not found") return error(e.message, 404);
+    return memoryErrorResponse(e);
+  }
+};
+
+export const deleteMemoryRoute: Handler = async (req, params) => {
+  const ctx = memoryContext(req);
+  const current = await memoryBroker.get(params.id!, ctx);
+  if (!current) return error("memory not found", 404);
+  const denied = authorizeMemoryScope(req, current.scope, "memory:admin");
+  if (denied) return denied;
+  await memoryBroker.delete(params.id!, ctx);
+  return json({ ok: true });
+};
+
+function memoryContextHasAdmin(ctx: MemoryBrokerContext): boolean {
+  return ctx.scopes.includes("*") || ctx.scopes.includes("memory:admin");
+}
+
+function publicMemoryBrokerConfig(): Record<string, unknown> {
+  if (memoryBrokerConfig.type === "sqlite") return { type: "sqlite" };
+  if (memoryBrokerConfig.type === "http") {
+    return {
+      type: "http",
+      url: memoryBrokerConfig.url,
+      tokenEnv: memoryBrokerConfig.tokenEnv,
+      timeoutMs: memoryBrokerConfig.timeoutMs,
+    };
+  }
+  return {
+    type: "command",
+    command: memoryBrokerConfig.command,
+    args: memoryBrokerConfig.args,
+    timeoutMs: memoryBrokerConfig.timeoutMs,
+  };
+}