@clawmem-ai/clawmem 0.1.15 → 0.1.17

package/src/state.test.ts

@@ -0,0 +1,119 @@
+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 === 4, "expected state version 4 after migration");
+    assert(Boolean(session), "expected migrated session to exist");
+    assert(session?.derived?.summary.status === "error", "expected finalized legacy sessions without a final summary to surface as needing manual attention");
+    assert(session?.derived?.memory.capturedCursor === 4, "expected legacy memory sync cursor to migrate into capturedCursor");
+  });
+}
+
+async function testNormalizesRunningTaskStates(): Promise<void> {
+  await withTempStateFile({
+    version: 3,
+    sessions: {
+      "main:s-2": {
+        sessionId: "s-2",
+        agentId: "main",
+        lastMirroredCount: 3,
+        turnCount: 3,
+        derived: {
+          summary: { basedOnCursor: 0, status: "running" },
+          memory: {
+            extractCursor: 1,
+            appliedCursor: 0,
+            extractStatus: "running",
+            reconcileStatus: "running",
+          },
+        },
+      },
+    },
+  }, async (filePath) => {
+    const state = await loadState(filePath);
+    const session = state.sessions["main:s-2"];
+    assert(session?.derived?.summary.status === "idle", "expected running summary tasks to normalize to idle on load");
+    assert(session?.derived?.memory.status === "idle", "expected running memory tasks to normalize to idle on load");
+    assert(session?.derived?.memory.capturedCursor === 0, "expected captured cursor to preserve the applied progress");
+  });
+}
+
+async function testPreservesCachedFinalArtifacts(): Promise<void> {
+  await withTempStateFile({
+    version: 4,
+    sessions: {
+      "main:s-3": {
+        sessionId: "s-3",
+        agentId: "main",
+        lastMirroredCount: 5,
+        turnCount: 5,
+        derived: {
+          summary: {
+            basedOnCursor: 5,
+            status: "idle",
+            text: "Recovered summary",
+            title: "Recovered title",
+          },
+          memory: {
+            capturedCursor: 0,
+            status: "error",
+            candidates: [
+              {
+                candidateId: "cand-1",
+                detail: "Store this durable fact.",
+                kind: "lesson",
+                topics: ["redis"],
+              },
+            ],
+          },
+        },
+      },
+    },
+  }, async (filePath) => {
+    const state = await loadState(filePath);
+    const session = state.sessions["main:s-3"];
+    assert(session?.derived?.summary.title === "Recovered title", "expected cached finalize title to survive state load");
+    assert(session?.derived?.memory.candidates?.length === 1, "expected cached memory candidates to survive state load");
+    assert(session?.derived?.memory.candidates?.[0]?.detail === "Store this durable fact.", "expected cached candidate detail to survive state load");
+  });
+}
+
+await testMigratesLegacyV2State();
+await testNormalizesRunningTaskStates();
+await testPreservesCachedFinalArtifacts();
+
+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: 4,
   sessions: {},
 };
 
@@ -38,10 +38,9 @@ function sanitizeState(value: unknown): PluginState {
     return structuredClone(EMPTY_STATE);
   }
   const raw = value as Record<string, unknown>;
-  const sessions =
-    raw.sessions && typeof raw.sessions === "object"
-      ? (raw.sessions as Record<string, unknown>)
-      : {};
+  const sessions = raw.sessions && typeof raw.sessions === "object"
+    ? (raw.sessions as Record<string, unknown>)
+    : {};
   const migrations: Record<string, string> = {};
   if (raw.migrations && typeof raw.migrations === "object") {
     for (const [k, v] of Object.entries(raw.migrations as Record<string, unknown>)) {
@@ -50,20 +49,19 @@ function sanitizeState(value: unknown): PluginState {
     }
   }
   const out: PluginState = {
-    version: 2,
+    version: 4,
     sessions: {},
     ...(Object.keys(migrations).length > 0 ? { migrations } : {}),
   };
   for (const [storedKey, sessionValue] of Object.entries(sessions)) {
-    if (!sessionValue || typeof sessionValue !== "object" || !storedKey.trim()) {
-      continue;
-    }
+    if (!sessionValue || typeof sessionValue !== "object" || !storedKey.trim()) continue;
     const rawSession = sessionValue as Record<string, unknown>;
     const sessionId = readString(rawSession.sessionId) ?? storedKey.trim();
-    if (!sessionId) {
-      continue;
-    }
+    if (!sessionId) continue;
     const agentId = normalizeAgentId(readString(rawSession.agentId));
+    const lastMirroredCount = readNumber(rawSession.lastMirroredCount) ?? 0;
+    const finalizedAt = readString(rawSession.finalizedAt);
+    const derived = sanitizeDerivedState(rawSession, lastMirroredCount, finalizedAt);
     out.sessions[sessionScopeKey(sessionId, agentId)] = {
       sessionId,
       sessionKey: readString(rawSession.sessionKey),
@@ -71,14 +69,12 @@ 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: readTitleSource(rawSession.titleSource),
+      lastMirroredCount,
       turnCount: readNumber(rawSession.turnCount) ?? 0,
-      lastMemorySyncCount: readNumber(rawSession.lastMemorySyncCount),
-      summaryStatus: readEnum(rawSession.summaryStatus, ["pending", "complete"]),
-      finalizedAt: readString(rawSession.finalizedAt),
+      finalizedAt,
       lastSummaryHash: readString(rawSession.lastSummaryHash),
-      lastTurnHash: readString(rawSession.lastTurnHash),
+      derived,
       createdAt: readString(rawSession.createdAt),
       updatedAt: readString(rawSession.updatedAt),
     };
@@ -86,10 +82,63 @@ function sanitizeState(value: unknown): PluginState {
   return out;
 }
 
+function sanitizeDerivedState(
+  rawSession: Record<string, unknown>,
+  lastMirroredCount: number,
+  finalizedAt?: string,
+): SessionDerivedState {
+  const rawDerived = asRecord(rawSession.derived);
+  const rawSummary = asRecord(rawDerived?.summary);
+  const rawMemory = asRecord(rawDerived?.memory);
+  const legacySummaryStatus = readEnum(rawSession.summaryStatus, ["pending", "complete"]);
+  const legacyMemoryCursor = readNumber(rawSession.lastMemorySyncCount);
+
+  const summaryText = readString(rawSummary?.text);
+  const summaryTitle = readString(rawSummary?.title);
+  const summaryStatus = readTaskStatus(
+    rawSummary?.status,
+    summaryText || legacySummaryStatus === "complete" ? "complete" : "idle",
+  );
+  const summaryCursor = clampCursor(
+    readNumber(rawSummary?.basedOnCursor),
+    summaryStatus === "complete" ? lastMirroredCount : 0,
+    lastMirroredCount,
+  );
+
+  const capturedCursor = clampCursor(
+    readNumber(rawMemory?.capturedCursor)
+      ?? readNumber(rawMemory?.appliedCursor)
+      ?? legacyMemoryCursor,
+    summaryStatus === "complete" ? lastMirroredCount : 0,
+    lastMirroredCount,
+  );
+  const memoryStatus = readTaskStatus(
+    rawMemory?.status ?? rawMemory?.extractStatus ?? rawMemory?.reconcileStatus,
+    capturedCursor >= lastMirroredCount && lastMirroredCount > 0 ? "complete" : "idle",
+  );
+  const candidates = readMemoryCandidates(rawMemory?.candidates);
+
+  return {
+    summary: {
+      basedOnCursor: summaryCursor,
+      status: finalizedAt && summaryStatus === "idle" && lastMirroredCount > 0 ? "error" : summaryStatus,
+      ...(summaryText ? { text: summaryText } : {}),
+      ...(summaryTitle ? { title: summaryTitle } : {}),
+      ...(readString(rawSummary?.lastError) ? { lastError: readString(rawSummary?.lastError) } : {}),
+      ...(readString(rawSummary?.updatedAt) ? { updatedAt: readString(rawSummary?.updatedAt) } : {}),
+    },
+    memory: {
+      capturedCursor,
+      status: memoryStatus,
+      ...(candidates ? { candidates } : {}),
+      ...(readString(rawMemory?.lastError) ? { lastError: readString(rawMemory?.lastError) } : {}),
+      ...(readString(rawMemory?.updatedAt) ? { updatedAt: readString(rawMemory?.updatedAt) } : {}),
+    },
+  };
+}
+
 function readString(value: unknown): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
+  if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   return trimmed ? trimmed : undefined;
 }
@@ -100,8 +149,58 @@ function readEnum<T extends string>(value: unknown, allowed: T[]): T | undefined
 }
 
 function readNumber(value: unknown): number | undefined {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    return undefined;
-  }
+  if (typeof value !== "number" || !Number.isFinite(value)) return 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;
+  if (status === "pending" || status === "running") return "idle";
+  return status;
+}
+
+function readTitleSource(value: unknown): "placeholder" | "llm" | undefined {
+  const source = readEnum(value, ["placeholder", "digest", "llm"]);
+  if (!source) return undefined;
+  return source === "digest" ? "llm" : source;
+}
+
+function readMemoryCandidates(value: unknown): MemoryCandidate[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value
+    .map((entry) => sanitizeMemoryCandidate(entry))
+    .filter((candidate): candidate is MemoryCandidate => candidate !== null);
+  return out;
+}
+
+function sanitizeMemoryCandidate(value: unknown): MemoryCandidate | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const candidateId = readString(record.candidateId);
+  const detail = readString(record.detail);
+  if (!candidateId || !detail) return null;
+  const title = readString(record.title);
+  const kind = readString(record.kind);
+  const topics = Array.isArray(record.topics)
+    ? record.topics.map((topic) => readString(topic)).filter((topic): topic is string => Boolean(topic))
+    : undefined;
+  const evidence = readString(record.evidence);
+  return {
+    candidateId,
+    detail,
+    ...(title ? { title } : {}),
+    ...(kind ? { kind } : {}),
+    ...(topics && topics.length > 0 ? { topics } : {}),
+    ...(evidence ? { evidence } : {}),
+  };
+}
+
+function clampCursor(value: number | undefined, fallback: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return Math.min(max, Math.max(0, fallback));
+  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

@@ -16,8 +16,8 @@ export type ClawMemPluginConfig = {
   agents: Record<string, ClawMemAgentConfig>;
   memoryRecallLimit: number;
   memoryAutoRecallLimit: number;
-  turnCommentDelayMs: number;
   summaryWaitTimeoutMs: number;
+  memoryExtractWaitTimeoutMs: number;
 };
 
 export type ClawMemResolvedRoute = {
@@ -32,16 +32,43 @@ 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" | "complete" | "error";
+export type MemoryCandidate = {
+  candidateId: string;
+  detail: string;
+  title?: string;
+  kind?: string;
+  topics?: string[];
+  evidence?: string;
+};
+export type SessionSummaryState = {
+  basedOnCursor: number;
+  status: SessionTaskStatus;
+  text?: string;
+  title?: string;
+  lastError?: string;
+  updatedAt?: string;
+};
+export type SessionMemoryState = {
+  capturedCursor: number;
+  status: SessionTaskStatus;
+  candidates?: MemoryCandidate[];
+  lastError?: string;
+  updatedAt?: string;
+};
+export type SessionDerivedState = {
+  summary: SessionSummaryState;
+  memory: SessionMemoryState;
+};
 export type SessionMirrorState = {
   sessionId: string; sessionKey?: string; sessionFile?: string; agentId?: string;
   issueNumber?: number; issueTitle?: string; titleSource?: "placeholder" | "llm";
-  lastMirroredCount: number; turnCount: number; lastAssistantText?: string;
-  lastMemorySyncCount?: number;
-  summaryStatus?: "pending" | "complete";
-  finalizedAt?: string; lastSummaryHash?: string; lastTurnHash?: string;
+  lastMirroredCount: number; turnCount: number;
+  finalizedAt?: string; lastSummaryHash?: string;
+  derived?: SessionDerivedState;
   createdAt?: string; updatedAt?: string;
 };
-export type PluginState = { version: 2; sessions: Record<string, SessionMirrorState>; migrations?: Record<string, string> };
+export type PluginState = { version: 4; 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")}`;
 }