@joshuaswarren/openclaw-engram 9.1.28 → 9.1.29

package/dist/index.js

@@ -7549,7 +7549,8 @@ var GraphDashboardServer = class {
 
 // src/access-http.ts
 import { createServer as createServer3 } from "http";
-import { timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { AsyncLocalStorage } from "async_hooks";
 import { existsSync } from "fs";
 import { readFile as readFile15 } from "fs/promises";
 import path22 from "path";
@@ -8041,6 +8042,151 @@ ${body}`;
   }
 };
 
+// src/access-schema.ts
+import { z as z2 } from "zod";
+function formatZodError(error) {
+  return {
+    error: "request validation failed",
+    code: "validation_error",
+    details: error.issues.map((issue) => ({
+      field: issue.path.join(".") || "(root)",
+      message: issue.message
+    }))
+  };
+}
+var namespaceSchema = z2.string().trim().max(256).optional();
+var sessionKeySchema = z2.string().trim().min(1).max(512).optional();
+var idempotencyKeySchema = z2.string().trim().min(1).max(256).optional();
+var dryRunSchema = z2.boolean().optional();
+var schemaVersionSchema = z2.number().int().optional();
+var recallRequestSchema = z2.object({
+  query: z2.string().min(1, "query is required"),
+  sessionKey: sessionKeySchema,
+  namespace: namespaceSchema,
+  topK: z2.number().int().min(0).max(200).optional(),
+  mode: z2.enum(["auto", "no_recall", "minimal", "full", "graph_mode"]).optional(),
+  includeDebug: z2.boolean().optional()
+});
+var recallExplainRequestSchema = z2.object({
+  sessionKey: sessionKeySchema,
+  namespace: namespaceSchema
+});
+var messageSchema = z2.object({
+  role: z2.enum(["user", "assistant"]),
+  content: z2.string().min(1, "message content must be non-empty")
+});
+var observeRequestSchema = z2.object({
+  sessionKey: z2.string().trim().min(1, "sessionKey is required").max(512),
+  messages: z2.array(messageSchema).min(1, "messages must be a non-empty array"),
+  namespace: namespaceSchema,
+  skipExtraction: z2.boolean().optional()
+});
+var writeContentSchema = z2.string().min(1, "content is required").max(5e4);
+var categorySchema = z2.enum([
+  "fact",
+  "preference",
+  "correction",
+  "entity",
+  "decision",
+  "relationship",
+  "principle",
+  "commitment",
+  "moment",
+  "skill",
+  "rule"
+]).optional();
+var confidenceSchema = z2.number().min(0).max(1).optional();
+var tagsSchema = z2.array(z2.string().max(256)).max(50).optional();
+var entityRefSchema = z2.string().trim().max(512).optional();
+var ttlSchema = z2.string().trim().max(128).optional();
+var sourceReasonSchema = z2.string().trim().max(2e3).optional();
+var memoryStoreRequestSchema = z2.object({
+  schemaVersion: schemaVersionSchema,
+  idempotencyKey: idempotencyKeySchema,
+  dryRun: dryRunSchema,
+  sessionKey: sessionKeySchema,
+  content: writeContentSchema,
+  category: categorySchema,
+  confidence: confidenceSchema,
+  namespace: namespaceSchema,
+  tags: tagsSchema,
+  entityRef: entityRefSchema,
+  ttl: ttlSchema,
+  sourceReason: sourceReasonSchema
+});
+var suggestionSubmitRequestSchema = memoryStoreRequestSchema;
+var reviewDispositionRequestSchema = z2.object({
+  memoryId: z2.string().trim().min(1, "memoryId is required"),
+  status: z2.enum([
+    "active",
+    "pending_review",
+    "quarantined",
+    "rejected",
+    "superseded",
+    "archived"
+  ]),
+  reasonCode: z2.string().trim().min(1, "reasonCode is required"),
+  namespace: namespaceSchema
+});
+var trustZonePromoteRequestSchema = z2.object({
+  recordId: z2.string().trim().min(1, "recordId is required"),
+  targetZone: z2.enum(["working", "trusted"], {
+    errorMap: () => ({ message: "targetZone must be 'working' or 'trusted'" })
+  }),
+  promotionReason: z2.string().trim().min(1, "promotionReason is required"),
+  recordedAt: z2.string().trim().optional(),
+  summary: z2.string().trim().max(5e3).optional(),
+  dryRun: dryRunSchema,
+  namespace: namespaceSchema
+});
+var trustZoneDemoSeedRequestSchema = z2.object({
+  scenario: z2.string().trim().max(256).optional(),
+  recordedAt: z2.string().trim().optional(),
+  dryRun: dryRunSchema,
+  namespace: namespaceSchema
+});
+var lcmSearchRequestSchema = z2.object({
+  query: z2.string().min(1, "query is required"),
+  sessionKey: sessionKeySchema,
+  namespace: namespaceSchema,
+  limit: z2.number().int().min(1).max(100).optional()
+});
+var daySummaryRequestSchema = z2.object({
+  memories: z2.string().max(1e5).optional(),
+  sessionKey: sessionKeySchema,
+  namespace: namespaceSchema
+});
+var schemas = {
+  recall: recallRequestSchema,
+  recallExplain: recallExplainRequestSchema,
+  observe: observeRequestSchema,
+  memoryStore: memoryStoreRequestSchema,
+  suggestionSubmit: suggestionSubmitRequestSchema,
+  reviewDisposition: reviewDispositionRequestSchema,
+  trustZonePromote: trustZonePromoteRequestSchema,
+  trustZoneDemoSeed: trustZoneDemoSeedRequestSchema,
+  lcmSearch: lcmSearchRequestSchema,
+  daySummary: daySummaryRequestSchema
+};
+function validateRequest(schemaName, body) {
+  const schema = schemas[schemaName];
+  if (!schema) {
+    return {
+      success: false,
+      error: {
+        error: `unknown schema: ${schemaName}`,
+        code: "validation_error",
+        details: []
+      }
+    };
+  }
+  const result = schema.safeParse(body);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  return { success: false, error: formatZodError(result.error) };
+}
+
 // src/access-http.ts
 function resolveDefaultAdminConsolePublicDir() {
   const candidates = [
@@ -8050,15 +8196,20 @@ function resolveDefaultAdminConsolePublicDir() {
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 var defaultAdminConsolePublicDir = resolveDefaultAdminConsolePublicDir();
+var correlationIdStore = new AsyncLocalStorage();
 var WRITE_RATE_LIMIT_WINDOW_MS = 6e4;
 var WRITE_RATE_LIMIT_MAX_REQUESTS = 30;
 var TRUST_ZONE_RECORD_KINDS = ["memory", "artifact", "state", "trajectory", "external"];
 var TRUST_ZONE_SOURCE_CLASSES = ["tool_output", "web_content", "subagent_trace", "system_memory", "user_input", "manual"];
 var HttpError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, code, details) {
     super(message);
     this.status = status;
+    this.code = code ?? `http_${status}`;
+    this.details = details;
   }
+  code;
+  details;
 };
 function hostToUrlAuthority2(host) {
   if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
@@ -8071,21 +8222,21 @@ function parseTrustZoneKindFilter(raw) {
   if (TRUST_ZONE_RECORD_KINDS.includes(raw)) {
     return raw;
   }
-  throw new HttpError(400, `kind must be one of ${TRUST_ZONE_RECORD_KINDS.join("|")}`);
+  throw new HttpError(400, `kind must be one of ${TRUST_ZONE_RECORD_KINDS.join("|")}`, "invalid_kind_filter");
 }
 function parseTrustZoneSourceClassFilter(raw) {
   if (raw === null) return void 0;
   if (TRUST_ZONE_SOURCE_CLASSES.includes(raw)) {
     return raw;
   }
-  throw new HttpError(400, `sourceClass must be one of ${TRUST_ZONE_SOURCE_CLASSES.join("|")}`);
+  throw new HttpError(400, `sourceClass must be one of ${TRUST_ZONE_SOURCE_CLASSES.join("|")}`, "invalid_source_class_filter");
 }
 function parseTrustZoneFilter(raw) {
   if (raw === null) return void 0;
   if (isTrustZoneName(raw)) {
     return raw;
   }
-  throw new HttpError(400, "zone must be one of quarantine|working|trusted");
+  throw new HttpError(400, "zone must be one of quarantine|working|trusted", "invalid_zone_filter");
 }
 var EngramAccessHttpServer = class {
   service;
@@ -8119,21 +8270,26 @@ var EngramAccessHttpServer = class {
     }
     if (this.server) return this.status();
     const server = createServer3((req, res) => {
-      void this.handle(req, res).catch((err) => {
-        log.debug(`engram access HTTP request failed: ${err}`);
-        if (err instanceof HttpError) {
-          this.respondJson(res, err.status, { error: err.message });
-          return;
-        }
-        if (err instanceof EngramAccessInputError) {
-          this.respondJson(res, 400, { error: err.message });
-          return;
-        }
-        if (res.headersSent) {
-          res.destroy(err);
-          return;
-        }
-        this.respondJson(res, 500, { error: "internal_error" });
+      const correlationId = randomUUID2();
+      correlationIdStore.run(correlationId, () => {
+        void this.handle(req, res, correlationId).catch((err) => {
+          log.debug(`engram access HTTP request failed [${correlationId}]: ${err}`);
+          if (err instanceof HttpError) {
+            const payload = { error: err.message, code: err.code };
+            if (err.details) payload.details = err.details;
+            this.respondJson(res, err.status, payload);
+            return;
+          }
+          if (err instanceof EngramAccessInputError) {
+            this.respondJson(res, 400, { error: err.message, code: "input_error" });
+            return;
+          }
+          if (res.headersSent) {
+            res.destroy(err);
+            return;
+          }
+          this.respondJson(res, 500, { error: "internal_error", code: "internal_error" });
+        });
       });
     });
     try {
@@ -8189,18 +8345,20 @@ var EngramAccessHttpServer = class {
     }
     return this.authenticatedPrincipal;
   }
-  async handle(req, res) {
+  async handle(req, res, correlationId) {
     const parsed = new URL3(req.url ?? "/", `http://${hostToUrlAuthority2(this.host)}`);
     const pathname = parsed.pathname;
     if (this.adminConsoleEnabled && await this.handleAdminConsole(req, res, pathname)) {
       return;
     }
     if (!this.isAuthorized(req)) {
+      const body = JSON.stringify({ error: "unauthorized", code: "unauthorized" });
       res.writeHead(401, {
         "content-type": "application/json; charset=utf-8",
-        "www-authenticate": "Bearer"
+        "www-authenticate": "Bearer",
+        "x-request-id": correlationId
       });
-      res.end(JSON.stringify({ error: "unauthorized" }));
+      res.end(body);
       return;
     }
     if (req.method === "POST" && pathname === "/mcp") {
@@ -8212,34 +8370,34 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/recall") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "recall");
       const response = await this.service.recall({
-        query: typeof body.query === "string" ? body.query : "",
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
-        topK: typeof body.topK === "number" ? body.topK : void 0,
-        mode: typeof body.mode === "string" ? body.mode : void 0,
+        query: body.query ?? "",
+        sessionKey: body.sessionKey,
+        namespace: body.namespace,
+        topK: body.topK,
+        mode: body.mode,
         includeDebug: body.includeDebug === true
       });
       this.respondJson(res, 200, response);
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/recall/explain") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "recallExplain");
       const response = await this.service.recallExplain({
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0
+        sessionKey: body.sessionKey,
+        namespace: body.namespace
       });
       this.respondJson(res, 200, response);
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/observe") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "observe");
       this.ensureWriteRateLimitAvailable();
       const response = await this.service.observe({
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : "",
-        messages: Array.isArray(body.messages) ? body.messages : [],
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
+        sessionKey: body.sessionKey,
+        messages: body.messages,
+        namespace: body.namespace,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
         skipExtraction: body.skipExtraction === true
       });
@@ -8248,13 +8406,13 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/lcm/search") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "lcmSearch");
       const response = await this.service.lcmSearch({
-        query: typeof body.query === "string" ? body.query : "",
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
+        query: body.query,
+        sessionKey: body.sessionKey,
+        namespace: body.namespace,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
-        limit: typeof body.limit === "number" ? body.limit : void 0
+        limit: body.limit
       });
       this.respondJson(res, 200, response);
       return;
@@ -8264,21 +8422,21 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/memories") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "memoryStore");
       const request = {
-        schemaVersion: typeof body.schemaVersion === "number" ? body.schemaVersion : void 0,
-        idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0,
+        schemaVersion: body.schemaVersion,
+        idempotencyKey: body.idempotencyKey,
         dryRun: body.dryRun === true,
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
+        sessionKey: body.sessionKey,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
-        content: typeof body.content === "string" ? body.content : "",
-        category: typeof body.category === "string" ? body.category : void 0,
-        confidence: typeof body.confidence === "number" ? body.confidence : void 0,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
-        tags: Array.isArray(body.tags) ? body.tags.filter((tag) => typeof tag === "string") : void 0,
-        entityRef: typeof body.entityRef === "string" ? body.entityRef : void 0,
-        ttl: typeof body.ttl === "string" ? body.ttl : void 0,
-        sourceReason: typeof body.sourceReason === "string" ? body.sourceReason : void 0
+        content: body.content,
+        category: body.category,
+        confidence: body.confidence,
+        namespace: body.namespace,
+        tags: body.tags,
+        entityRef: body.entityRef,
+        ttl: body.ttl,
+        sourceReason: body.sourceReason
       };
       const idempotencyStatus = await this.service.peekMemoryStoreIdempotency(request);
       if (idempotencyStatus === "miss" && request.dryRun !== true) {
@@ -8292,21 +8450,21 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/suggestions") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "suggestionSubmit");
       const request = {
-        schemaVersion: typeof body.schemaVersion === "number" ? body.schemaVersion : void 0,
-        idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : void 0,
+        schemaVersion: body.schemaVersion,
+        idempotencyKey: body.idempotencyKey,
         dryRun: body.dryRun === true,
-        sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
+        sessionKey: body.sessionKey,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
-        content: typeof body.content === "string" ? body.content : "",
-        category: typeof body.category === "string" ? body.category : void 0,
-        confidence: typeof body.confidence === "number" ? body.confidence : void 0,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
-        tags: Array.isArray(body.tags) ? body.tags.filter((tag) => typeof tag === "string") : void 0,
-        entityRef: typeof body.entityRef === "string" ? body.entityRef : void 0,
-        ttl: typeof body.ttl === "string" ? body.ttl : void 0,
-        sourceReason: typeof body.sourceReason === "string" ? body.sourceReason : void 0
+        content: body.content,
+        category: body.category,
+        confidence: body.confidence,
+        namespace: body.namespace,
+        tags: body.tags,
+        entityRef: body.entityRef,
+        ttl: body.ttl,
+        sourceReason: body.sourceReason
       };
       const idempotencyStatus = await this.service.peekSuggestionSubmitIdempotency(request);
       if (idempotencyStatus === "miss" && request.dryRun !== true) {
@@ -8415,17 +8573,13 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/review-disposition") {
-      const body = await this.readJsonBody(req);
-      const status = typeof body.status === "string" ? body.status : "";
-      if (status !== "active" && status !== "pending_review" && status !== "quarantined" && status !== "rejected" && status !== "superseded" && status !== "archived") {
-        throw new HttpError(400, "invalid_review_status");
-      }
+      const body = await this.readValidatedBody(req, "reviewDisposition");
       this.ensureWriteRateLimitAvailable();
       const response = await this.service.reviewDisposition({
-        memoryId: typeof body.memoryId === "string" ? body.memoryId : "",
-        status,
-        reasonCode: typeof body.reasonCode === "string" ? body.reasonCode : "",
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
+        memoryId: body.memoryId,
+        status: body.status,
+        reasonCode: body.reasonCode,
+        namespace: body.namespace,
         authenticatedPrincipal: this.resolveRequestPrincipal(req)
       });
       if (this.shouldCountWriteRateLimit(response)) {
@@ -8435,31 +8589,19 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/trust-zones/promote") {
-      const body = await this.readJsonBody(req);
-      const recordId = typeof body.recordId === "string" ? body.recordId.trim() : "";
-      const targetZone = typeof body.targetZone === "string" ? body.targetZone.trim() : "";
-      const promotionReason = typeof body.promotionReason === "string" ? body.promotionReason.trim() : "";
+      const body = await this.readValidatedBody(req, "trustZonePromote");
       const dryRun = body.dryRun === true;
-      if (!recordId) {
-        throw new HttpError(400, "recordId is required");
-      }
-      if (!isTrustZoneName(targetZone)) {
-        throw new HttpError(400, "invalid_trust_zone_target");
-      }
-      if (!promotionReason) {
-        throw new HttpError(400, "promotionReason is required");
-      }
       if (!dryRun) {
         this.ensureWriteRateLimitAvailable();
       }
       const response = await this.service.trustZonePromote({
-        recordId,
-        targetZone,
-        promotionReason,
-        recordedAt: typeof body.recordedAt === "string" ? body.recordedAt : void 0,
-        summary: typeof body.summary === "string" ? body.summary : void 0,
+        recordId: body.recordId,
+        targetZone: body.targetZone,
+        promotionReason: body.promotionReason,
+        recordedAt: body.recordedAt,
+        summary: body.summary,
         dryRun,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
+        namespace: body.namespace,
         authenticatedPrincipal: this.resolveRequestPrincipal(req)
       });
       if (this.shouldCountWriteRateLimit(response)) {
@@ -8469,16 +8611,16 @@ var EngramAccessHttpServer = class {
       return;
     }
     if (req.method === "POST" && pathname === "/engram/v1/trust-zones/demo-seed") {
-      const body = await this.readJsonBody(req);
+      const body = await this.readValidatedBody(req, "trustZoneDemoSeed");
       const dryRun = body.dryRun === true;
       if (!dryRun) {
         this.ensureWriteRateLimitAvailable();
       }
       const response = await this.service.trustZoneDemoSeed({
-        scenario: typeof body.scenario === "string" ? body.scenario : void 0,
-        recordedAt: typeof body.recordedAt === "string" ? body.recordedAt : void 0,
+        scenario: body.scenario,
+        recordedAt: body.recordedAt,
         dryRun,
-        namespace: typeof body.namespace === "string" ? body.namespace : void 0,
+        namespace: body.namespace,
         authenticatedPrincipal: this.resolveRequestPrincipal(req)
       });
       if (this.shouldCountWriteRateLimit(response)) {
@@ -8487,7 +8629,7 @@ var EngramAccessHttpServer = class {
       this.respondJson(res, response.dryRun ? 200 : 201, response);
       return;
     }
-    this.respondJson(res, 404, { error: "not_found" });
+    this.respondJson(res, 404, { error: "not_found", code: "not_found" });
   }
   async handleMcpRequest(req, res) {
     const body = await this.readJsonBody(req);
@@ -8519,6 +8661,10 @@ var EngramAccessHttpServer = class {
     res.statusCode = status;
     res.setHeader("content-type", "application/json; charset=utf-8");
     res.setHeader("content-length", String(Buffer.byteLength(body)));
+    const cid = correlationIdStore.getStore();
+    if (cid) {
+      res.setHeader("x-request-id", cid);
+    }
     res.end(body);
   }
   async handleAdminConsole(req, res, pathname) {
@@ -8551,7 +8697,7 @@ var EngramAccessHttpServer = class {
       const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
       total += buffer.length;
       if (total > this.maxBodyBytes) {
-        throw new HttpError(413, "request_body_too_large");
+        throw new HttpError(413, "request_body_too_large", "request_body_too_large");
       }
       chunks.push(buffer);
     }
@@ -8562,13 +8708,21 @@ var EngramAccessHttpServer = class {
     try {
       parsed = JSON.parse(raw);
     } catch {
-      throw new HttpError(400, "invalid_json");
+      throw new HttpError(400, "invalid_json", "invalid_json");
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new HttpError(400, "invalid_json_object");
+      throw new HttpError(400, "invalid_json_object", "invalid_json_object");
     }
     return parsed;
   }
+  async readValidatedBody(req, schemaName) {
+    const raw = await this.readJsonBody(req);
+    const result = validateRequest(schemaName, raw);
+    if (!result.success) {
+      throw new HttpError(400, result.error.error, "validation_error", result.error.details);
+    }
+    return result.data;
+  }
   isAuthorized(req) {
     if (!this.authToken) return false;
     const raw = req.headers.authorization;
@@ -8605,7 +8759,7 @@ var EngramAccessHttpServer = class {
       this.writeRequestTimestamps.shift();
     }
     if (this.writeRequestTimestamps.length >= WRITE_RATE_LIMIT_MAX_REQUESTS) {
-      throw new HttpError(429, "write_rate_limited");
+      throw new HttpError(429, "write_rate_limited", "write_rate_limited");
     }
   }
   recordWriteRateLimitHit() {