@joshuaswarren/openclaw-engram 9.0.19 → 9.0.20

package/README.md

@@ -31,6 +31,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Pluggable search** — Choose from six search backends: QMD (hybrid BM25+vector+reranking), LanceDB, Meilisearch, Orama, remote HTTP, or bring your own.
 - **Memory OS features** — Graph recall, temporal memory tree, lifecycle policy, compounding, shared context, memory boxes, and identity continuity can be enabled progressively as your install grows.
 - **Benchmark-first roadmap** — Engram now has an evaluation harness with live shadow recall recording and a CI benchmark delta gate, so memory improvements can be measured and regression-checked instead of argued from anecdotes.
+- **Objective-state foundation** — When `objectiveStateMemoryEnabled` and `objectiveStateSnapshotWritesEnabled` are enabled together, Engram records normalized file, process, and tool outcomes from `agent_end` tool activity into a dedicated objective-state store.
 - **Zero-config start** — Install, add an API key, restart. Engram works out of the box with sensible defaults and progressively unlocks advanced features as you enable them.
 
 ## Quick Start

package/dist/index.js

@@ -26056,6 +26056,13 @@ function assertIsoRecordedAt(value) {
   }
   return value;
 }
+function objectiveStateDay(recordedAt) {
+  const day = recordedAt.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) {
+    throw new Error("recordedAt must start with a valid YYYY-MM-DD date");
+  }
+  return day;
+}
 function optionalStringArray2(value, field) {
   if (value === void 0) return void 0;
   if (!Array.isArray(value)) throw new Error(`${field} must be an array of strings`);
@@ -26128,6 +26135,16 @@ function validateObjectiveStateSnapshot(raw) {
     metadata: validateMetadata(raw.metadata)
   };
 }
+async function recordObjectiveStateSnapshot(options) {
+  const rootDir = resolveObjectiveStateStoreDir(options.memoryDir, options.objectiveStateStoreDir);
+  const validated = validateObjectiveStateSnapshot(options.snapshot);
+  const day = objectiveStateDay(validated.recordedAt);
+  const snapshotsDir = path52.join(rootDir, "snapshots", day);
+  const filePath = path52.join(snapshotsDir, `${validated.snapshotId}.json`);
+  await mkdir34(snapshotsDir, { recursive: true });
+  await writeFile30(filePath, JSON.stringify(validated, null, 2), "utf8");
+  return filePath;
+}
 async function getObjectiveStateStoreStatus(options) {
   const rootDir = resolveObjectiveStateStoreDir(options.memoryDir, options.objectiveStateStoreDir);
   const snapshotsDir = path52.join(rootDir, "snapshots");
@@ -28555,6 +28572,303 @@ function parseDuration(duration) {
   return total || 12;
 }
 
+// src/objective-state-writers.ts
+import crypto2 from "crypto";
+function hashSha256(value) {
+  return crypto2.createHash("sha256").update(value).digest("hex");
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalString2(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function toolNameTokens(toolName) {
+  if (!toolName) return [];
+  return toolName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+}
+function normalizedToolName(toolName) {
+  return toolNameTokens(toolName).join("_");
+}
+function parseToolArguments(value) {
+  if (isRecord3(value)) return value;
+  if (typeof value !== "string") return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord3(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function extractTextContent(value) {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) {
+    return value.map((block) => {
+      if (typeof block === "string") return block.trim();
+      if (isRecord3(block) && block.type === "text" && typeof block.text === "string") {
+        return block.text.trim();
+      }
+      return "";
+    }).filter((item) => item.length > 0).join("\n");
+  }
+  if (isRecord3(value)) {
+    return JSON.stringify(value);
+  }
+  return "";
+}
+function parseToolResultPayload(content) {
+  const text = extractTextContent(content);
+  if (text.length === 0) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function resultHash(value) {
+  if (value === void 0) return void 0;
+  const canonical = typeof value === "string" ? value : JSON.stringify(value);
+  if (!canonical || canonical.length === 0) return void 0;
+  return `sha256:${hashSha256(canonical)}`;
+}
+function getToolCallContexts(messages) {
+  const contexts = /* @__PURE__ */ new Map();
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    const toolCalls = message.tool_calls ?? message.toolCalls;
+    if (!Array.isArray(toolCalls)) continue;
+    for (const call of toolCalls) {
+      if (!isRecord3(call)) continue;
+      const toolCallId = optionalString2(call.id) ?? optionalString2(call.toolCallId);
+      if (!toolCallId) continue;
+      const fn = isRecord3(call.function) ? call.function : void 0;
+      const toolName = optionalString2(fn?.name) ?? optionalString2(call.name);
+      const args = parseToolArguments(fn?.arguments) ?? parseToolArguments(call.arguments) ?? parseToolArguments(call.args) ?? parseToolArguments(call.input);
+      contexts.set(toolCallId, { toolCallId, toolName, args });
+    }
+  }
+  return contexts;
+}
+function toolCallIdForMessage(message) {
+  return optionalString2(message.tool_call_id) ?? optionalString2(message.toolCallId) ?? optionalString2(message.tool_use_id) ?? optionalString2(message.toolUseId);
+}
+function toolNameForMessage(message, context) {
+  return optionalString2(message.name) ?? optionalString2(message.toolName) ?? optionalString2(message.tool) ?? context?.toolName;
+}
+function pickString(args, keys) {
+  if (!args) return void 0;
+  for (const key of keys) {
+    const value = optionalString2(args[key]);
+    if (value) return value;
+  }
+  return void 0;
+}
+function pickFirstStringArrayValue(args, key) {
+  const value = args?.[key];
+  if (!Array.isArray(value)) return void 0;
+  for (const item of value) {
+    const candidate = optionalString2(item);
+    if (candidate) return candidate;
+  }
+  return void 0;
+}
+function fileScopeFromArgs(args) {
+  const destinationPath = pickString(args, ["destination", "dest", "targetPath", "target", "to"]) ?? pickString(args, ["path", "filePath", "workspacePath", "projectPath"]) ?? pickFirstStringArrayValue(args, "paths");
+  const sourcePath = pickString(args, ["source", "src", "from", "oldPath"]);
+  const scope = destinationPath ?? sourcePath;
+  return { scope, sourcePath, destinationPath };
+}
+function fileContentHash(args) {
+  const content = pickString(args, ["content", "patch", "diff", "text", "value"]) ?? args?.updates;
+  return resultHash(content);
+}
+function inferOutcome(message, parsedPayload) {
+  if (message.isError === true) return "failure";
+  if (isRecord3(parsedPayload)) {
+    if (parsedPayload.partial === true || parsedPayload.status === "partial") return "partial";
+    if (parsedPayload.success === false || parsedPayload.ok === false) return "failure";
+    if (parsedPayload.success === true || parsedPayload.ok === true) return "success";
+    if (typeof parsedPayload.exitCode === "number") {
+      return parsedPayload.exitCode === 0 ? "success" : "failure";
+    }
+    if (optionalString2(parsedPayload.error)) return "failure";
+    if (parsedPayload.status === "error" || parsedPayload.status === "failed") return "failure";
+    if (parsedPayload.status === "ok" || parsedPayload.status === "success") return "success";
+  }
+  if (typeof parsedPayload === "string") {
+    const lowered = parsedPayload.toLowerCase();
+    if (lowered.includes("error") || lowered.includes("failed") || lowered.includes("exception")) {
+      return "failure";
+    }
+  }
+  return "unknown";
+}
+function isProcessTool(toolName, args) {
+  const tokens = toolNameTokens(toolName);
+  const normalizedName = normalizedToolName(toolName);
+  if (pickString(args, ["cmd", "command", "script"])) return true;
+  return ["exec", "shell", "bash", "terminal", "run_command", "exec_command"].some(
+    (token) => token.includes("_") ? normalizedName === token : tokens.includes(token)
+  );
+}
+function isFileTool(toolName, args) {
+  const tokens = toolNameTokens(toolName);
+  const fileScope = fileScopeFromArgs(args);
+  if (fileScope.scope) return true;
+  return ["file", "path", "patch", "directory", "mkdir", "rename", "move"].some(
+    (token) => tokens.includes(token)
+  );
+}
+function inferFileChangeKind(toolName, outcome) {
+  if (outcome === "failure") return "failed";
+  const tokens = toolNameTokens(toolName);
+  if (["delete", "remove", "unlink"].some((token) => tokens.includes(token))) return "deleted";
+  if (["create", "mkdir", "new"].some((token) => tokens.includes(token))) return "created";
+  if (["write", "edit", "patch", "update", "append", "move", "rename"].some((token) => tokens.includes(token))) {
+    return "updated";
+  }
+  return "observed";
+}
+function buildFileValueRefs(args, changeKind) {
+  const { sourcePath, destinationPath, scope } = fileScopeFromArgs(args);
+  const contentHash = fileContentHash(args);
+  if (changeKind === "failed") {
+    if (sourcePath && destinationPath && sourcePath !== destinationPath) {
+      return {
+        before: { ref: sourcePath },
+        after: { ref: destinationPath }
+      };
+    }
+    return {
+      before: sourcePath ? { ref: sourcePath } : void 0,
+      after: scope ? { ref: scope } : void 0
+    };
+  }
+  if (changeKind === "deleted") {
+    return {
+      before: scope ? { exists: true, ref: scope } : void 0,
+      after: { exists: false }
+    };
+  }
+  if (changeKind === "created") {
+    return {
+      after: {
+        exists: true,
+        ref: scope,
+        valueHash: contentHash
+      }
+    };
+  }
+  if (sourcePath && destinationPath && sourcePath !== destinationPath) {
+    return {
+      before: { exists: true, ref: sourcePath },
+      after: {
+        exists: true,
+        ref: destinationPath
+      }
+    };
+  }
+  return {
+    after: {
+      exists: true,
+      ref: scope,
+      valueHash: contentHash
+    }
+  };
+}
+function summarizeSnapshot(kind, changeKind, toolName, scope) {
+  const action = changeKind === "executed" ? "Executed" : changeKind === "failed" ? "Failed" : changeKind === "created" ? "Created" : changeKind === "deleted" ? "Deleted" : changeKind === "updated" ? "Updated" : "Observed";
+  if (kind === "process") return `${action} process via ${toolName}: ${scope}`;
+  if (kind === "file") return `${action} file via ${toolName}: ${scope}`;
+  return `${action} tool result from ${toolName}: ${scope}`;
+}
+function buildGenericToolAfterRef(outcome, parsedPayload) {
+  const valueHash = resultHash(parsedPayload);
+  return valueHash ? { valueHash } : { exists: outcome !== "failure" };
+}
+function snapshotIdFor(sessionKey, recordedAt, index, toolName, scope) {
+  const digest = crypto2.createHash("sha256").update(`${sessionKey}|${recordedAt}|${index}|${toolName}|${scope}`).digest("hex").slice(0, 12);
+  return `obj-${digest}`;
+}
+function deriveObjectiveStateSnapshotsFromAgentMessages(options) {
+  const toolCallsById = getToolCallContexts(options.messages);
+  const snapshots = [];
+  for (const message of options.messages) {
+    if (message.role !== "tool") continue;
+    const toolCallId = toolCallIdForMessage(message);
+    const context = toolCallId ? toolCallsById.get(toolCallId) : void 0;
+    const toolName = toolNameForMessage(message, context);
+    if (!toolName) continue;
+    const parsedPayload = parseToolResultPayload(message.content);
+    const outcome = inferOutcome(message, parsedPayload);
+    const args = context?.args;
+    const command = pickString(args, ["cmd", "command", "script"]);
+    let kind = "tool";
+    let changeKind = outcome === "failure" ? "failed" : "observed";
+    let scope = toolName;
+    let before;
+    let after;
+    if (isProcessTool(toolName, args)) {
+      kind = "process";
+      changeKind = outcome === "failure" ? "failed" : "executed";
+      scope = command ?? toolName;
+      after = { exists: outcome !== "failure", valueHash: resultHash(parsedPayload) };
+    } else if (isFileTool(toolName, args)) {
+      kind = "file";
+      changeKind = inferFileChangeKind(toolName, outcome);
+      const fileScope = fileScopeFromArgs(args);
+      scope = fileScope.scope ?? toolName;
+      const refs = buildFileValueRefs(args, changeKind);
+      before = refs.before;
+      after = refs.after;
+    } else {
+      after = buildGenericToolAfterRef(outcome, parsedPayload);
+    }
+    snapshots.push({
+      schemaVersion: 1,
+      snapshotId: snapshotIdFor(options.sessionKey, options.recordedAt, snapshots.length, toolName, scope),
+      recordedAt: options.recordedAt,
+      sessionKey: options.sessionKey,
+      source: "tool_result",
+      kind,
+      changeKind,
+      scope,
+      summary: summarizeSnapshot(kind, changeKind, toolName, scope),
+      toolName,
+      command,
+      outcome,
+      before,
+      after,
+      tags: ["agent-end", `tool:${toolName}`],
+      metadata: toolCallId ? { toolCallId } : void 0
+    });
+  }
+  return snapshots;
+}
+async function recordObjectiveStateSnapshotsFromAgentMessages(options) {
+  if (!options.objectiveStateMemoryEnabled || !options.objectiveStateSnapshotWritesEnabled) {
+    return { snapshots: [], filePaths: [] };
+  }
+  const snapshots = deriveObjectiveStateSnapshotsFromAgentMessages({
+    sessionKey: options.sessionKey,
+    recordedAt: options.recordedAt,
+    messages: options.messages
+  });
+  const filePaths = [];
+  for (const snapshot of snapshots) {
+    filePaths.push(
+      await recordObjectiveStateSnapshot({
+        memoryDir: options.memoryDir,
+        objectiveStateStoreDir: options.objectiveStateStoreDir,
+        snapshot
+      })
+    );
+  }
+  return { snapshots, filePaths };
+}
+
 // src/index.ts
 import { readFile as readFile39, writeFile as writeFile31 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
@@ -28698,6 +29012,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
         try {
           const messages = event.messages;
           const lastTurn = extractLastTurn(messages);
+          const eventTimestamp = (/* @__PURE__ */ new Date()).toISOString();
           if (orchestrator.config.hourlySummariesIncludeToolStats) {
             const toolNames = [];
             for (const msg of messages) {
@@ -28716,23 +29031,35 @@ Use this context naturally when relevant. Never quote or expose this memory cont
                 }
               }
             }
-            const ts = (/* @__PURE__ */ new Date()).toISOString();
             for (const tool of toolNames) {
-              await orchestrator.transcript.appendToolUse({ timestamp: ts, sessionKey, tool });
+              await orchestrator.transcript.appendToolUse({ timestamp: eventTimestamp, sessionKey, tool });
             }
           }
+          try {
+            await recordObjectiveStateSnapshotsFromAgentMessages({
+              memoryDir: orchestrator.config.memoryDir,
+              objectiveStateStoreDir: orchestrator.config.objectiveStateStoreDir,
+              objectiveStateMemoryEnabled: orchestrator.config.objectiveStateMemoryEnabled,
+              objectiveStateSnapshotWritesEnabled: orchestrator.config.objectiveStateSnapshotWritesEnabled,
+              sessionKey,
+              recordedAt: eventTimestamp,
+              messages
+            });
+          } catch (error) {
+            log.debug(`agent_end objective-state writer skipped due to error: ${error}`);
+          }
           for (const msg of lastTurn) {
             const rawRole = typeof msg.role === "string" ? msg.role : "";
             if (rawRole !== "user" && rawRole !== "assistant") {
               continue;
             }
             const role = rawRole;
-            const content = extractTextContent(msg);
+            const content = extractTextContent2(msg);
             if (content.length < 10) continue;
             const cleaned = role === "user" ? cleanUserMessage(content) : content;
             if (orchestrator.config.transcriptEnabled) {
               await orchestrator.transcript.append({
-                timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+                timestamp: eventTimestamp,
                 role,
                 content: cleaned,
                 sessionKey,
@@ -28920,7 +29247,7 @@ function extractLastTurn(messages) {
   }
   return lastUserIdx >= 0 ? messages.slice(lastUserIdx) : messages.slice(-2);
 }
-function extractTextContent(msg) {
+function extractTextContent2(msg) {
   if (typeof msg.content === "string") return msg.content;
   if (Array.isArray(msg.content)) {
     return msg.content.filter(