@clawmem-ai/clawmem 0.1.15 → 0.1.16

package/src/state.test.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadState } from "./state.js";
+
+function assert(condition: unknown, message: string): void {
+  if (!condition) throw new Error(message);
+}
+
+async function withTempStateFile(payload: unknown, fn: (filePath: string) => Promise<void>): Promise<void> {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "clawmem-state-"));
+  const filePath = path.join(dir, "state.json");
+  try {
+    await fs.promises.writeFile(filePath, JSON.stringify(payload, null, 2), "utf8");
+    await fn(filePath);
+  } finally {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function testMigratesLegacyV2State(): Promise<void> {
+  await withTempStateFile({
+    version: 2,
+    sessions: {
+      "main:s-1": {
+        sessionId: "s-1",
+        agentId: "main",
+        issueNumber: 10,
+        lastMirroredCount: 6,
+        turnCount: 6,
+        lastMemorySyncCount: 4,
+        summaryStatus: "pending",
+        finalizedAt: "2026-04-03T10:00:00.000Z",
+      },
+    },
+  }, async (filePath) => {
+    const state = await loadState(filePath);
+    const session = state.sessions["main:s-1"];
+    assert(state.version === 3, "expected state version 3 after migration");
+    assert(Boolean(session), "expected migrated session to exist");
+    assert(session?.derived?.digest.cursor === 0, "expected legacy sessions to rebuild digest from cursor 0");
+    assert(session?.derived?.digest.status === "pending", "expected digest to become pending after migration");
+    assert(session?.derived?.summary.status === "pending", "expected finalized legacy sessions to keep summary pending");
+    assert(session?.derived?.memory.appliedCursor === 4, "expected legacy memory sync cursor to migrate into appliedCursor");
+    assert(session?.lastMemorySyncCount === 4, "expected compatibility field to mirror appliedCursor");
+  });
+}
+
+async function testNormalizesRunningTaskStates(): Promise<void> {
+  await withTempStateFile({
+    version: 3,
+    sessions: {
+      "main:s-2": {
+        sessionId: "s-2",
+        agentId: "main",
+        lastMirroredCount: 3,
+        turnCount: 3,
+        derived: {
+          digest: { cursor: 1, status: "running", attempt: 2, text: "digest" },
+          summary: { basedOnCursor: 0, status: "running" },
+          memory: {
+            extractCursor: 1,
+            appliedCursor: 0,
+            extractStatus: "running",
+            reconcileStatus: "running",
+            attempt: 1,
+            pendingCandidates: [
+              { candidateId: "abc", detail: "Remember Redis is atomic with Lua." },
+            ],
+          },
+        },
+      },
+    },
+  }, async (filePath) => {
+    const state = await loadState(filePath);
+    const session = state.sessions["main:s-2"];
+    assert(session?.derived?.digest.status === "pending", "expected running digest tasks to normalize to pending on load");
+    assert(session?.derived?.summary.status === "pending", "expected running summary tasks to normalize to pending on load");
+    assert(session?.derived?.memory.extractStatus === "pending", "expected running memory extract tasks to normalize to pending");
+    assert(session?.derived?.memory.reconcileStatus === "pending", "expected running memory reconcile tasks to normalize to pending");
+    assert(session?.derived?.memory.pendingCandidates.length === 1, "expected pending candidates to survive state reload");
+  });
+}
+
+await testMigratesLegacyV2State();
+await testNormalizesRunningTaskStates();
+
+console.log("state tests passed");

package/src/state.ts

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { PluginState } from "./types.js";
+import type { MemoryCandidate, PluginState, SessionDerivedState, SessionMirrorState, SessionTaskStatus } from "./types.js";
 import { normalizeAgentId, sessionScopeKey } from "./utils.js";
 
 const EMPTY_STATE: PluginState = {
-  version: 2,
+  version: 3,
   sessions: {},
 };
 
@@ -50,7 +50,7 @@ function sanitizeState(value: unknown): PluginState {
     }
   }
   const out: PluginState = {
-    version: 2,
+    version: 3,
     sessions: {},
     ...(Object.keys(migrations).length > 0 ? { migrations } : {}),
   };
@@ -64,6 +64,16 @@ function sanitizeState(value: unknown): PluginState {
       continue;
     }
     const agentId = normalizeAgentId(readString(rawSession.agentId));
+    const lastMirroredCount = readNumber(rawSession.lastMirroredCount) ?? 0;
+    const finalizedAt = readString(rawSession.finalizedAt);
+    const summaryStatus = readEnum(rawSession.summaryStatus, ["pending", "complete"]);
+    const lastMemorySyncCount = readNumber(rawSession.lastMemorySyncCount);
+    const derived = sanitizeDerivedState(rawSession.derived, {
+      lastMirroredCount,
+      finalizedAt,
+      summaryStatus,
+      lastMemorySyncCount,
+    });
     out.sessions[sessionScopeKey(sessionId, agentId)] = {
       sessionId,
       sessionKey: readString(rawSession.sessionKey),
@@ -71,14 +81,15 @@ function sanitizeState(value: unknown): PluginState {
       agentId,
       issueNumber: readNumber(rawSession.issueNumber),
       issueTitle: readString(rawSession.issueTitle),
-      titleSource: readEnum(rawSession.titleSource, ["placeholder", "llm"]),
-      lastMirroredCount: readNumber(rawSession.lastMirroredCount) ?? 0,
+      titleSource: readEnum(rawSession.titleSource, ["placeholder", "digest", "llm"]),
+      lastMirroredCount,
       turnCount: readNumber(rawSession.turnCount) ?? 0,
-      lastMemorySyncCount: readNumber(rawSession.lastMemorySyncCount),
-      summaryStatus: readEnum(rawSession.summaryStatus, ["pending", "complete"]),
-      finalizedAt: readString(rawSession.finalizedAt),
+      lastMemorySyncCount: derived.memory.appliedCursor,
+      summaryStatus: derived.summary.status === "complete" ? "complete" : finalizedAt ? "pending" : undefined,
+      finalizedAt,
       lastSummaryHash: readString(rawSession.lastSummaryHash),
       lastTurnHash: readString(rawSession.lastTurnHash),
+      derived,
       createdAt: readString(rawSession.createdAt),
       updatedAt: readString(rawSession.updatedAt),
     };
@@ -86,6 +97,89 @@ function sanitizeState(value: unknown): PluginState {
   return out;
 }
 
+function sanitizeDerivedState(
+  value: unknown,
+  fallback: {
+    lastMirroredCount: number;
+    finalizedAt?: string;
+    summaryStatus?: "pending" | "complete";
+    lastMemorySyncCount?: number;
+  },
+): SessionDerivedState {
+  if (!value || typeof value !== "object") {
+    return migrateDerivedState(fallback);
+  }
+  const record = value as Record<string, unknown>;
+  const digest = asRecord(record.digest);
+  const summary = asRecord(record.summary);
+  const memory = asRecord(record.memory);
+  const lastMirroredCount = fallback.lastMirroredCount;
+  const extractCursor = clampCursor(readNumber(memory?.extractCursor), lastMirroredCount);
+  const appliedCursor = clampCursor(readNumber(memory?.appliedCursor), extractCursor);
+  return {
+    digest: {
+      cursor: clampCursor(readNumber(digest?.cursor), lastMirroredCount),
+      status: readTaskStatus(digest?.status, lastMirroredCount > 0 ? "pending" : "idle"),
+      attempt: readNumber(digest?.attempt) ?? 0,
+      text: readString(digest?.text),
+      title: readString(digest?.title),
+      lastError: readString(digest?.lastError),
+      updatedAt: readString(digest?.updatedAt),
+    },
+    summary: {
+      basedOnCursor: clampCursor(readNumber(summary?.basedOnCursor), lastMirroredCount),
+      status: readTaskStatus(summary?.status, fallback.finalizedAt ? "pending" : "idle"),
+      text: readString(summary?.text),
+      lastError: readString(summary?.lastError),
+      updatedAt: readString(summary?.updatedAt),
+    },
+    memory: {
+      extractCursor,
+      appliedCursor,
+      extractStatus: readTaskStatus(memory?.extractStatus, extractCursor < lastMirroredCount ? "pending" : "idle"),
+      reconcileStatus: readTaskStatus(memory?.reconcileStatus, appliedCursor < extractCursor ? "pending" : "idle"),
+      attempt: readNumber(memory?.attempt) ?? 0,
+      pendingCandidates: Array.isArray(memory?.pendingCandidates)
+        ? memory.pendingCandidates.map(sanitizeCandidate).filter((candidate): candidate is MemoryCandidate => Boolean(candidate))
+        : [],
+      lastError: readString(memory?.lastError),
+      updatedAt: readString(memory?.updatedAt),
+    },
+  };
+}
+
+function migrateDerivedState(fallback: {
+  lastMirroredCount: number;
+  finalizedAt?: string;
+  summaryStatus?: "pending" | "complete";
+  lastMemorySyncCount?: number;
+}): SessionDerivedState {
+  const mirrorCursor = fallback.lastMirroredCount;
+  const finalized = Boolean(fallback.finalizedAt);
+  const summaryComplete = fallback.summaryStatus === "complete";
+  const appliedCursor = clampCursor(fallback.lastMemorySyncCount, mirrorCursor);
+  const digestCursor = finalized && summaryComplete ? mirrorCursor : 0;
+  return {
+    digest: {
+      cursor: digestCursor,
+      status: digestCursor < mirrorCursor ? "pending" : "idle",
+      attempt: 0,
+    },
+    summary: {
+      basedOnCursor: summaryComplete ? mirrorCursor : 0,
+      status: finalized ? (summaryComplete ? "complete" : "pending") : "idle",
+    },
+    memory: {
+      extractCursor: appliedCursor,
+      appliedCursor,
+      extractStatus: appliedCursor < mirrorCursor ? "pending" : "idle",
+      reconcileStatus: "idle",
+      attempt: 0,
+      pendingCandidates: [],
+    },
+  };
+}
+
 function readString(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return undefined;
@@ -105,3 +199,40 @@ function readNumber(value: unknown): number | undefined {
   }
   return Math.max(0, Math.floor(value));
 }
+
+function readTaskStatus(value: unknown, fallback: SessionTaskStatus): SessionTaskStatus {
+  const status = readEnum(value, ["idle", "pending", "running", "complete", "error"]);
+  if (!status) return fallback;
+  return status === "running" ? "pending" : status;
+}
+
+function sanitizeCandidate(value: unknown): MemoryCandidate | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const detail = readString(record.detail);
+  const candidateId = readString(record.candidateId);
+  if (!detail) return null;
+  return {
+    candidateId: candidateId ?? detail,
+    detail,
+    ...(readString(record.title) ? { title: readString(record.title) } : {}),
+    ...(readString(record.kind) ? { kind: readString(record.kind) } : {}),
+    ...(Array.isArray(record.topics)
+      ? {
+          topics: record.topics
+            .map((topic) => readString(topic))
+            .filter((topic): topic is string => Boolean(topic)),
+        }
+      : {}),
+    ...(readString(record.evidence) ? { evidence: readString(record.evidence) } : {}),
+  };
+}
+
+function clampCursor(value: number | undefined, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  return Math.min(max, Math.max(0, Math.floor(value)));
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}

package/src/types.ts

@@ -17,7 +17,10 @@ export type ClawMemPluginConfig = {
   memoryRecallLimit: number;
   memoryAutoRecallLimit: number;
   turnCommentDelayMs: number;
+  digestWaitTimeoutMs: number;
   summaryWaitTimeoutMs: number;
+  memoryExtractWaitTimeoutMs: number;
+  memoryReconcileWaitTimeoutMs: number;
 };
 
 export type ClawMemResolvedRoute = {
@@ -32,16 +35,57 @@ export type ClawMemResolvedRoute = {
 export type BootstrapIdentityResponse = { token: string; repo_full_name: string };
 export type AgentRegistrationResponse = BootstrapIdentityResponse & { login: string };
 export type AnonymousSessionResponse = BootstrapIdentityResponse & { owner_login: string; repo_name: string };
+export type SessionTaskStatus = "idle" | "pending" | "running" | "complete" | "error";
+export type MemoryCandidate = {
+  candidateId: string;
+  detail: string;
+  title?: string;
+  kind?: string;
+  topics?: string[];
+  evidence?: string;
+};
+export type SessionDigestState = {
+  cursor: number;
+  status: SessionTaskStatus;
+  attempt: number;
+  text?: string;
+  title?: string;
+  lastError?: string;
+  updatedAt?: string;
+};
+export type SessionSummaryState = {
+  basedOnCursor: number;
+  status: SessionTaskStatus;
+  text?: string;
+  lastError?: string;
+  updatedAt?: string;
+};
+export type SessionMemoryState = {
+  extractCursor: number;
+  appliedCursor: number;
+  extractStatus: SessionTaskStatus;
+  reconcileStatus: SessionTaskStatus;
+  attempt: number;
+  pendingCandidates: MemoryCandidate[];
+  lastError?: string;
+  updatedAt?: string;
+};
+export type SessionDerivedState = {
+  digest: SessionDigestState;
+  summary: SessionSummaryState;
+  memory: SessionMemoryState;
+};
 export type SessionMirrorState = {
   sessionId: string; sessionKey?: string; sessionFile?: string; agentId?: string;
-  issueNumber?: number; issueTitle?: string; titleSource?: "placeholder" | "llm";
+  issueNumber?: number; issueTitle?: string; titleSource?: "placeholder" | "digest" | "llm";
   lastMirroredCount: number; turnCount: number; lastAssistantText?: string;
   lastMemorySyncCount?: number;
   summaryStatus?: "pending" | "complete";
   finalizedAt?: string; lastSummaryHash?: string; lastTurnHash?: string;
+  derived?: SessionDerivedState;
   createdAt?: string; updatedAt?: string;
 };
-export type PluginState = { version: 2; sessions: Record<string, SessionMirrorState>; migrations?: Record<string, string> };
+export type PluginState = { version: 3; sessions: Record<string, SessionMirrorState>; migrations?: Record<string, string> };
 export type NormalizedMessage = { role: string; text: string; toolName?: string; timestamp?: string; stopReason?: string };
 export type TranscriptSnapshot = { sessionId?: string; messages: NormalizedMessage[] };
 export type MemoryDraft = { title?: string; detail: string; kind?: string; topics?: string[] };

package/src/utils.ts

@@ -46,6 +46,25 @@ export function fmtTranscript(msgs: NormalizedMessage[]): string {
   return msgs.map((m, i) => `${i + 1}. ${m.role === "assistant" ? "assistant" : "user"}: ${m.text}`).join("\n\n");
 }
 
+export function fmtTranscriptFrom(msgs: NormalizedMessage[], startIndex: number): string {
+  return msgs.map((m, i) => `${startIndex + i + 1}. ${m.role === "assistant" ? "assistant" : "user"}: ${m.text}`).join("\n\n");
+}
+
+export function sliceTranscriptDelta(
+  msgs: NormalizedMessage[],
+  fromIndex: number,
+  anchorCount = 2,
+): { anchorStart: number; deltaStart: number; anchorMessages: NormalizedMessage[]; deltaMessages: NormalizedMessage[] } {
+  const deltaStart = Math.min(Math.max(0, Math.floor(fromIndex)), msgs.length);
+  const anchorStart = Math.max(0, deltaStart - Math.max(0, Math.floor(anchorCount)));
+  return {
+    anchorStart,
+    deltaStart,
+    anchorMessages: msgs.slice(anchorStart, deltaStart),
+    deltaMessages: msgs.slice(deltaStart),
+  };
+}
+
 export function localDate(d: Date = new Date()): string {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 }