@joshuaswarren/openclaw-engram 9.0.107 → 9.0.108

package/dist/chunk-PKKCGNF2.js

@@ -0,0 +1,15 @@
+// openclaw-engram: Local-first memory plugin
+
+// src/version-utils.ts
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+export {
+  compareVersions
+};
+//# sourceMappingURL=chunk-PKKCGNF2.js.map

package/dist/chunk-PKKCGNF2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version-utils.ts"],"sourcesContent":["export type VersionTriple = readonly [number, number, number];\n\nexport function compareVersions(a: VersionTriple, b: VersionTriple): number {\n  for (let i = 0; i < 3; i += 1) {\n    if (a[i] > b[i]) return 1;\n    if (a[i] < b[i]) return -1;\n  }\n  return 0;\n}\n"],"mappings":";;;AAEO,SAAS,gBAAgB,GAAkB,GAA0B;AAC1E,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG;AAC7B,QAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAG,QAAO;AACxB,QAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAG,QAAO;AAAA,EAC1B;AACA,SAAO;AACT;","names":[]}

package/dist/index.js

@@ -1,4 +1,7 @@
 // openclaw-engram: Local-first memory plugin
+import {
+  compareVersions
+} from "./chunk-PKKCGNF2.js";
 import {
   EngramAccessInputError,
   EngramAccessService,
@@ -127,6 +130,30 @@ import {
   log
 } from "./chunk-SSIIJJKA.js";
 
+// src/index.ts
+import { createRequire } from "module";
+
+// src/sdk-compat.ts
+function detectSdkCapabilities(api) {
+  const hasRegisterMemoryPromptSection = typeof api.registerMemoryPromptSection === "function";
+  const hasRuntimeNamespace = typeof api.runtime === "object" && api.runtime !== null;
+  const hasRegistrationMode = typeof api.registrationMode === "string";
+  const sdkVersion = (hasRuntimeNamespace && typeof api.runtime?.version === "string" ? api.runtime.version : null) ?? (typeof process?.env?.OPENCLAW_SERVICE_VERSION === "string" ? process.env.OPENCLAW_SERVICE_VERSION : null) ?? "legacy";
+  const isNewSdk = hasRegisterMemoryPromptSection || hasRuntimeNamespace || hasRegistrationMode;
+  const hasNewHookSystem = hasRegisterMemoryPromptSection || hasRegistrationMode;
+  return {
+    hasBeforePromptBuild: hasNewHookSystem,
+    hasRegisterMemoryPromptSection,
+    hasDefinePluginEntry: isNewSdk,
+    // entry point is less risky, keep broad detection
+    hasRuntimeNamespace,
+    hasRegistrationMode,
+    hasTypedHooks: hasNewHookSystem,
+    sdkVersion,
+    registrationMode: hasRegistrationMode ? api.registrationMode : void 0
+  };
+}
+
 // src/tools.ts
 import { createHash } from "crypto";
 import { Type } from "@sinclair/typebox";
@@ -8314,18 +8341,8 @@ var EngramAccessHttpServer = class {
 import { access as access3, readFile as readFile16 } from "fs/promises";
 import path23 from "path";
 import { spawn as spawn2 } from "child_process";
-
-// src/version-utils.ts
-function compareVersions(a, b) {
-  for (let i = 0; i < 3; i += 1) {
-    if (a[i] > b[i]) return 1;
-    if (a[i] < b[i]) return -1;
-  }
-  return 0;
-}
-
-// src/compat/checks.ts
-var REQUIRED_HOOKS = ["before_agent_start", "agent_end"];
+var REQUIRED_HOOKS_LEGACY = ["before_agent_start", "agent_end"];
+var REQUIRED_HOOKS_NEW = ["before_prompt_build", "agent_end"];
 function isSafeCommandToken(command) {
   return /^[a-zA-Z0-9._-]+$/.test(command);
 }
@@ -8627,7 +8644,12 @@ async function runCompatChecks(options) {
     const indexRaw = await readFile16(indexPath, "utf-8");
     const structuralSource = stripCommentsAndStrings(indexRaw);
     const hooks = parseHookRegistrations(indexRaw);
-    const missingHooks = REQUIRED_HOOKS.filter((hook) => !hooks.has(hook));
+    const missingLegacy = REQUIRED_HOOKS_LEGACY.filter((hook) => !hooks.has(hook));
+    const missingNew = REQUIRED_HOOKS_NEW.filter((hook) => !hooks.has(hook));
+    const hasMemoryPromptSection = structuralSource.includes(".registerMemoryPromptSection(");
+    const missingLegacyAdj = hasMemoryPromptSection ? missingLegacy.filter((h) => h !== "before_agent_start") : missingLegacy;
+    const missingNewAdj = hasMemoryPromptSection ? missingNew.filter((h) => h !== "before_prompt_build") : missingNew;
+    const missingHooks = missingNewAdj.length <= missingLegacyAdj.length ? missingNewAdj : missingLegacyAdj;
     const hasGatewayStartHook = hooks.has("gateway_start");
     const hasServiceStart = hasServiceStartRegistration(structuralSource);
     if (missingHooks.length === 0 && (hasGatewayStartHook || hasServiceStart)) {
@@ -8650,7 +8672,7 @@ async function runCompatChecks(options) {
         title: "Core hook registration",
         level: "error",
         message: `Missing expected registration(s): ${missingParts.join("; ")}`,
-        remediation: "Ensure src/index.ts registers before_agent_start and agent_end, plus either gateway_start or api.registerService({ start })."
+        remediation: "Ensure src/index.ts registers before_prompt_build (or before_agent_start) and agent_end, plus either gateway_start or api.registerService({ start })."
       });
     }
     const cliWired = hasCliRegistration(structuralSource);
@@ -13117,34 +13139,6 @@ async function recordObjectiveStateSnapshotsFromAgentMessages(options) {
   return { snapshots, filePaths };
 }
 
-// src/legacy-hook-compat.ts
-var FIRST_PUBLISHED_RUNTIME_WITHOUT_AGENT_HEARTBEAT = [2026, 1, 29];
-var OPENCLAW_VERSION_PREFIX = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
-function parseOpenClawVersion(value) {
-  if (typeof value !== "string") return null;
-  const match = value.trim().match(OPENCLAW_VERSION_PREFIX);
-  if (!match) return null;
-  return {
-    triple: [
-      Number.parseInt(match[1], 10),
-      Number.parseInt(match[2], 10),
-      Number.parseInt(match[3], 10)
-    ],
-    prerelease: typeof match[4] === "string" && match[4].length > 0
-  };
-}
-function shouldRegisterTypedAgentHeartbeat(runtimeVersion) {
-  const parsed = parseOpenClawVersion(runtimeVersion);
-  if (!parsed) return false;
-  const comparison = compareVersions(
-    parsed.triple,
-    FIRST_PUBLISHED_RUNTIME_WITHOUT_AGENT_HEARTBEAT
-  );
-  if (comparison < 0) return true;
-  if (comparison > 0) return false;
-  return parsed.prerelease;
-}
-
 // src/index.ts
 import { readFile as readFile18, writeFile as writeFile12 } from "fs/promises";
 import { readFileSync as readFileSync2 } from "fs";
@@ -13511,20 +13505,27 @@ var ENGRAM_ACCESS_SERVICE = "__openclawEngramAccessService";
 var ENGRAM_ACCESS_HTTP_SERVER = "__openclawEngramAccessHttpServer";
 var ENGRAM_SERVICE_STARTED = "__openclawEngramServiceStarted";
 var ENGRAM_INIT_PROMISE = "__openclawEngramInitPromise";
-function loadPluginConfigFromFile() {
+function loadPluginEntryFromFile() {
   try {
     const explicitConfigPath = process.env.OPENCLAW_ENGRAM_CONFIG_PATH || process.env.OPENCLAW_CONFIG_PATH;
     const homeDir = process.env.HOME ?? os3.homedir();
     const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path27.join(homeDir, ".openclaw", "openclaw.json");
     const content = readFileSync2(configPath, "utf-8");
     const config = JSON.parse(content);
-    const pluginEntry = config?.plugins?.entries?.["openclaw-engram"];
-    return pluginEntry?.config;
+    return config?.plugins?.entries?.["openclaw-engram"];
   } catch (err) {
     log.warn(`Failed to load config from file: ${err}`);
     return void 0;
   }
 }
+function loadPluginConfigFromFile() {
+  return loadPluginEntryFromFile()?.config;
+}
+function readPluginHooksPolicy(apiConfig) {
+  const fromApi = apiConfig?.plugins?.entries?.["openclaw-engram"]?.hooks;
+  if (fromApi && typeof fromApi === "object") return fromApi;
+  return loadPluginEntryFromFile()?.hooks;
+}
 function wildcardToRegExp(pattern) {
   const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
   return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
@@ -13543,20 +13544,31 @@ function shouldSkipRecallForSession(sessionKey, cfg) {
     }
   });
 }
-function observeSessionHeartbeat(orchestrator, ctx) {
-  if (orchestrator.config.sessionObserverEnabled !== true) return;
-  const sessionKey = ctx?.sessionKey ?? "default";
-  void orchestrator.observeSessionHeartbeat(sessionKey).catch((err) => {
-    log.debug(`agent_heartbeat observer failed: ${err}`);
-  });
+function tryDefinePluginEntry(def) {
+  try {
+    const _require = createRequire(import.meta.url);
+    const { definePluginEntry } = _require("openclaw/plugin-sdk/plugin-entry");
+    return definePluginEntry(def);
+  } catch {
+    return def;
+  }
 }
-var index_default = {
+var sdkCaps;
+var pluginDefinition = {
   id: "openclaw-engram",
   name: "Engram (Local Memory)",
   description: "Local-first memory plugin. Uses GPT-5.2 for intelligent extraction and QMD for storage/retrieval.",
   kind: "memory",
   register(api) {
     initLogger(api.logger, false);
+    sdkCaps = detectSdkCapabilities(api);
+    log.info(
+      `SDK detection: version=${sdkCaps.sdkVersion}, beforePromptBuild=${sdkCaps.hasBeforePromptBuild}, memoryPromptSection=${sdkCaps.hasRegisterMemoryPromptSection}, typedHooks=${sdkCaps.hasTypedHooks}`
+    );
+    if (sdkCaps.registrationMode === "setup-only") {
+      log.info("registrationMode=setup-only \u2014 skipping full initialization");
+      return;
+    }
     const fileConfig = loadPluginConfigFromFile();
     const cfg = parseConfig({
       ...api.pluginConfig,
@@ -13599,65 +13611,112 @@ var index_default = {
       maxBodyBytes: cfg.agentAccessHttp.maxBodyBytes
     });
     globalThis[ENGRAM_ACCESS_HTTP_SERVER] = accessHttpServer;
-    api.on(
-      "before_agent_start",
-      async (event, ctx) => {
-        const prompt = event.prompt;
-        if (!prompt || prompt.length < 5) return;
-        const sessionKey = ctx?.sessionKey ?? "default";
-        log.debug(`before_agent_start: sessionKey=${sessionKey}, promptLen=${prompt.length}`);
+    const hooksPolicy = readPluginHooksPolicy(api.config);
+    const promptInjectionAllowed = hooksPolicy?.allowPromptInjection !== false;
+    const useMemoryPromptSection = sdkCaps.hasRegisterMemoryPromptSection && typeof api.registerMemoryPromptSection === "function" && promptInjectionAllowed;
+    async function recallHookHandler(hookLabel, event, ctx) {
+      let prompt = event.prompt;
+      if ((!prompt || prompt.length < 5) && Array.isArray(event.messages)) {
+        const msgs = event.messages;
+        for (let i = msgs.length - 1; i >= 0; i--) {
+          if (msgs[i]?.role === "user") {
+            const text = extractTextContent2(msgs[i]);
+            if (text.length >= 5) {
+              prompt = text;
+              break;
+            }
+          }
+        }
+      }
+      if (!prompt || prompt.length < 5) return;
+      const sessionKey = ctx?.sessionKey ?? "default";
+      log.debug(`${hookLabel}: sessionKey=${sessionKey}, promptLen=${prompt.length}`);
+      log.debug(
+        `${hookLabel}: cronRecallMode=${cfg.cronRecallMode}, allowlistCount=${cfg.cronRecallAllowlist.length}`
+      );
+      if (sessionKey.includes(":cron:") && cfg.cronRecallMode === "allowlist") {
+        const matchedPattern = cfg.cronRecallAllowlist.find((pattern) => {
+          const re = wildcardToRegExp(pattern);
+          return re.test(sessionKey);
+        });
         log.debug(
-          `before_agent_start: cronRecallMode=${cfg.cronRecallMode}, allowlistCount=${cfg.cronRecallAllowlist.length}`
+          `${hookLabel}: cron allowlist match=${matchedPattern ? "yes" : "no"} pattern=${matchedPattern ?? "none"}`
         );
-        if (sessionKey.includes(":cron:") && cfg.cronRecallMode === "allowlist") {
-          const matchedPattern = cfg.cronRecallAllowlist.find((pattern) => {
-            const re = wildcardToRegExp(pattern);
-            return re.test(sessionKey);
-          });
-          log.debug(
-            `before_agent_start: cron allowlist match=${matchedPattern ? "yes" : "no"} pattern=${matchedPattern ?? "none"}`
-          );
+      }
+      if (shouldSkipRecallForSession(sessionKey, cfg)) {
+        log.debug(
+          `${hookLabel}: skip recall for cron session ${sessionKey} (mode=${cfg.cronRecallMode})`
+        );
+        return;
+      }
+      try {
+        await orchestrator.maybeRunFileHygiene().catch(() => void 0);
+        if (orchestrator.config.compactionResetEnabled) {
+          const agentWorkspace = ctx?.workspaceDir;
+          if (agentWorkspace) {
+            orchestrator.setRecallWorkspaceOverride(sessionKey, agentWorkspace);
+          }
         }
-        if (shouldSkipRecallForSession(sessionKey, cfg)) {
-          log.debug(
-            `before_agent_start: skip recall for cron session ${sessionKey} (mode=${cfg.cronRecallMode})`
-          );
-          return;
+        const context = await orchestrator.recall(prompt, sessionKey);
+        log.debug(`${hookLabel}: recall returned ${context?.length ?? 0} chars`);
+        if (!context) return;
+        const maxChars = cfg.recallBudgetChars;
+        if (maxChars === 0) return;
+        const trimmed = context.length > maxChars ? context.slice(0, maxChars) + "\n\n...(memory context trimmed)" : context;
+        const memoryContextPrompt = `## Memory Context (Engram)
+
+${trimmed}
+
+Use this context naturally when relevant. Never quote or expose this memory context to the user.`;
+        log.debug(`${hookLabel}: returning system prompt with ${trimmed.length} chars`);
+        if (hookLabel === "before_prompt_build") {
+          return { prependSystemContext: memoryContextPrompt };
         }
-        try {
-          await orchestrator.maybeRunFileHygiene().catch(() => void 0);
-          if (orchestrator.config.compactionResetEnabled) {
-            const agentWorkspace = ctx?.workspaceDir;
-            if (agentWorkspace) {
-              orchestrator.setRecallWorkspaceOverride(sessionKey, agentWorkspace);
-            }
-          }
-          const context = await orchestrator.recall(prompt, sessionKey);
-          log.debug(`before_agent_start: recall returned ${context?.length ?? 0} chars`);
-          if (!context) return;
-          const maxChars = cfg.recallBudgetChars;
-          if (maxChars === 0) return;
-          const trimmed = context.length > maxChars ? context.slice(0, maxChars) + "\n\n...(memory context trimmed)" : context;
-          const memoryContextPrompt = `## Memory Context (Engram)
+        return {
+          prependSystemContext: memoryContextPrompt,
+          prependContext: memoryContextPrompt
+        };
+      } catch (err) {
+        log.error("recall failed", err);
+        if (orchestrator.config.compactionResetEnabled) {
+          orchestrator.clearRecallWorkspaceOverride(sessionKey);
+        }
+        return;
+      }
+    }
+    if (!useMemoryPromptSection) {
+      if (sdkCaps.hasBeforePromptBuild) {
+        api.on("before_prompt_build", async (event, ctx) => recallHookHandler("before_prompt_build", event, ctx));
+      } else {
+        api.on("before_agent_start", async (event, ctx) => recallHookHandler("before_agent_start", event, ctx));
+      }
+    }
+    if (useMemoryPromptSection && api.registerMemoryPromptSection) {
+      api.registerMemoryPromptSection({
+        id: "engram-memory",
+        label: "Engram Memory Context",
+        build: async ({ prompt, sessionKey }) => {
+          if (!prompt || prompt.length < 5) return null;
+          if (shouldSkipRecallForSession(sessionKey, cfg)) return null;
+          try {
+            await orchestrator.maybeRunFileHygiene().catch(() => void 0);
+            const context = await orchestrator.recall(prompt, sessionKey);
+            if (!context) return null;
+            const maxChars = cfg.recallBudgetChars;
+            if (maxChars === 0) return null;
+            const trimmed = context.length > maxChars ? context.slice(0, maxChars) + "\n\n...(memory context trimmed)" : context;
+            return `## Memory Context (Engram)
 
 ${trimmed}
 
 Use this context naturally when relevant. Never quote or expose this memory context to the user.`;
-          log.debug(`before_agent_start: returning system prompt with ${trimmed.length} chars`);
-          return {
-            prependSystemContext: memoryContextPrompt,
-            // Backward-compat path for gateway builds that consume prependContext.
-            prependContext: memoryContextPrompt
-          };
-        } catch (err) {
-          log.error("recall failed", err);
-          if (orchestrator.config.compactionResetEnabled) {
-            orchestrator.clearRecallWorkspaceOverride(sessionKey);
+          } catch (err) {
+            log.error("registerMemoryPromptSection build failed", err);
+            return null;
           }
-          return;
         }
-      }
-    );
+      });
+    }
     api.on(
       "agent_end",
       async (event, ctx) => {
@@ -13772,30 +13831,6 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         }
       }
     );
-    const runtimeApi = api;
-    runtimeApi.registerHook?.(
-      ["agent_heartbeat", "agent:heartbeat"],
-      (event) => {
-        observeSessionHeartbeat(orchestrator, event.context);
-      },
-      {
-        name: "engram_agent_heartbeat_legacy",
-        description: "Observe legacy OpenClaw heartbeat events when the runtime still emits them."
-      }
-    );
-    const runtimeVersion = runtimeApi.runtime?.version || process.env.OPENCLAW_SERVICE_VERSION || "unknown";
-    if (shouldRegisterTypedAgentHeartbeat(runtimeVersion)) {
-      api.on("agent_heartbeat", (_event, ctx) => {
-        observeSessionHeartbeat(orchestrator, ctx);
-      });
-      log.info(
-        `registered legacy typed agent_heartbeat hook for OpenClaw ${runtimeVersion}`
-      );
-    } else {
-      log.debug(
-        `skipping legacy typed agent_heartbeat hook for OpenClaw ${runtimeVersion}; published builds from 2026.1.29 onward do not expose it`
-      );
-    }
     const lcmTokensBefore = /* @__PURE__ */ new Map();
     api.on(
       "before_compaction",
@@ -13848,7 +13883,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
     api.on(
       "after_compaction",
       async (event, ctx) => {
-        const sessionKey = ctx?.sessionKey ?? "default";
+        const sessionKey = ctx?.sessionKey ?? event?.sessionKey ?? "default";
         try {
           if (orchestrator.lcmEngine?.enabled) {
             try {
@@ -13919,6 +13954,98 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         }
       }
     );
+    if (sdkCaps.hasBeforePromptBuild) {
+      api.on(
+        "session_start",
+        async (event, _ctx) => {
+          const sessionKey = event.sessionKey ?? "default";
+          log.debug(`session_start: ${sessionKey}`);
+          try {
+            await orchestrator.maybeRunFileHygiene().catch(() => void 0);
+          } catch (err) {
+            log.debug(`session_start file hygiene failed: ${err}`);
+          }
+        }
+      );
+      api.on(
+        "session_end",
+        async (event, _ctx) => {
+          const sessionKey = event.sessionKey ?? "default";
+          log.debug(`session_end: ${sessionKey}`);
+          if (orchestrator.config.compactionResetEnabled) {
+            orchestrator.clearRecallWorkspaceOverride(sessionKey);
+          }
+        }
+      );
+      api.on(
+        "before_tool_call",
+        async (event, _ctx) => {
+          if (event.toolName) {
+            log.debug(`before_tool_call: ${event.toolName}`);
+          }
+        }
+      );
+      api.on(
+        "after_tool_call",
+        async (event, _ctx) => {
+          if (event.toolName) {
+            log.debug(`after_tool_call: ${event.toolName} (${event.durationMs ?? "?"}ms)`);
+          }
+        }
+      );
+      api.on(
+        "llm_output",
+        async (event, ctx) => {
+          const sessionKey = ctx?.sessionKey ?? "default";
+          if (event.tokenUsage) {
+            log.debug(
+              `llm_output: model=${event.model ?? "?"}, tokens=${event.tokenUsage.input ?? 0}/${event.tokenUsage.output ?? 0}, ${event.durationMs ?? "?"}ms, session=${sessionKey}`
+            );
+          }
+        }
+      );
+      api.on(
+        "subagent_spawning",
+        async (event, _ctx) => {
+          log.debug(`subagent_spawning: ${event.subagentId ?? "?"} purpose=${event.purpose ?? "?"}`);
+        }
+      );
+      api.on(
+        "subagent_ended",
+        async (event, _ctx) => {
+          log.debug(
+            `subagent_ended: ${event.subagentId ?? "?"} success=${event.success ?? "?"} ${event.durationMs ?? "?"}ms`
+          );
+        }
+      );
+    } else {
+      const runtimeApi = api;
+      runtimeApi.registerHook?.(
+        ["agent_heartbeat", "agent:heartbeat"],
+        (event) => {
+          if (orchestrator.config.sessionObserverEnabled !== true) return;
+          const sessionKey = event?.context?.sessionKey ?? "default";
+          void orchestrator.observeSessionHeartbeat(sessionKey).catch((err) => {
+            log.debug(`agent_heartbeat observer failed: ${err}`);
+          });
+        },
+        { name: "engram_agent_heartbeat_legacy", description: "Observe legacy heartbeat events for session observation." }
+      );
+      const runtimeVersion = runtimeApi.runtime?.version || process.env.OPENCLAW_SERVICE_VERSION || "unknown";
+      void import("./legacy-hook-compat-722BG5XG.js").then(({ shouldRegisterTypedAgentHeartbeat }) => {
+        if (shouldRegisterTypedAgentHeartbeat(runtimeVersion)) {
+          api.on("agent_heartbeat", (_event, ctx) => {
+            if (orchestrator.config.sessionObserverEnabled !== true) return;
+            const sessionKey = ctx?.sessionKey ?? "default";
+            void orchestrator.observeSessionHeartbeat(sessionKey).catch((err) => {
+              log.debug(`agent_heartbeat typed observer failed: ${err}`);
+            });
+          });
+          log.info(`registered typed agent_heartbeat hook for OpenClaw ${runtimeVersion}`);
+        }
+      }).catch(() => {
+      });
+    }
     async function ensureHourlySummaryCron(api2) {
       const jobId = "engram-hourly-summary";
       const cronFilePath = path27.join(os3.homedir(), ".openclaw", "cron", "jobs.json");
@@ -14086,6 +14213,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
     });
   }
 };
+var index_default = tryDefinePluginEntry(pluginDefinition);
 function extractLastTurn(messages) {
   let lastUserIdx = -1;
   for (let i = messages.length - 1; i >= 0; i--) {