@echomem/echo-memory-cloud-openclaw-plugin 0.1.0 → 0.1.2

package/lib/sync.js

@@ -1,46 +1,191 @@
-import { scanOpenClawMemoryDir } from "./openclaw-memory-scan.js";
-import { resolveStatePath, readLastSyncState, writeLastSyncState } from "./state.js";
-
-function chunk(items, size) {
-  const batches = [];
-  for (let index = 0; index < items.length; index += size) {
-    batches.push(items.slice(index, index + size));
-  }
-  return batches;
-}
-
-function buildEmptySummary(fileCount = 0) {
-  return {
-    file_count: fileCount,
-    skipped_count: 0,
-    new_source_count: 0,
-    new_memory_count: 0,
-    duplicate_count: 0,
-    failed_file_count: 0,
-  };
-}
-
+import { scanOpenClawMemoryDir } from "./openclaw-memory-scan.js";
+import { resolveStatePath, readLastSyncState, writeLastSyncState } from "./state.js";
+
+function resolveRuntimeStateDir(api, fallbackStateDir = null) {
+  const runtimeStateDir = api?.runtime?.state?.resolveStateDir?.();
+  if (runtimeStateDir) {
+    return runtimeStateDir;
+  }
+  return fallbackStateDir;
+}
+
+function buildRunId() {
+  return `echo-sync-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function buildEmptySummary(fileCount = 0) {
+  return {
+    file_count: fileCount,
+    skipped_count: 0,
+    new_source_count: 0,
+    new_memory_count: 0,
+    duplicate_count: 0,
+    failed_file_count: 0,
+  };
+}
+
 function mergeSummary(target, next) {
-  target.file_count += next.file_count ?? 0;
-  target.skipped_count += next.skipped_count ?? 0;
-  target.new_source_count += next.new_source_count ?? 0;
-  target.new_memory_count += next.new_memory_count ?? 0;
-  target.duplicate_count += next.duplicate_count ?? 0;
-  target.failed_file_count += next.failed_file_count ?? 0;
+  target.file_count += next.file_count ?? 0;
+  target.skipped_count += next.skipped_count ?? 0;
+  target.new_source_count += next.new_source_count ?? 0;
+  target.new_memory_count += next.new_memory_count ?? 0;
+  target.duplicate_count += next.duplicate_count ?? 0;
+  target.failed_file_count += next.failed_file_count ?? 0;
   return target;
 }
 
+function countStatuses(results = []) {
+  const counts = {
+    successCount: 0,
+    failedCount: 0,
+    skippedCount: 0,
+    duplicateCount: 0,
+  };
+
+  for (const result of results) {
+    if (!result?.status) continue;
+    if (result.status === "failed") {
+      counts.failedCount += 1;
+      continue;
+    }
+    if (result.status === "skipped") {
+      counts.skippedCount += 1;
+      counts.successCount += 1;
+      continue;
+    }
+    if (result.status === "duplicate") {
+      counts.duplicateCount += 1;
+      counts.successCount += 1;
+      continue;
+    }
+    counts.successCount += 1;
+  }
+
+  return counts;
+}
+
+function applyManualFileSummary(summary, status) {
+  summary.file_count += 1;
+  if (status === "failed") {
+    summary.failed_file_count += 1;
+  } else if (status === "skipped") {
+    summary.skipped_count += 1;
+  } else if (status === "duplicate") {
+    summary.duplicate_count += 1;
+  } else {
+    summary.new_source_count += 1;
+  }
+}
+
+function normalizeStatus(rawStatus, fallback = "imported") {
+  const normalized = String(rawStatus || "").trim().toLowerCase();
+  if (!normalized) return fallback;
+  if (["failed", "error"].includes(normalized)) return "failed";
+  if (["skipped", "unchanged"].includes(normalized)) return "skipped";
+  if (["duplicate", "deduped"].includes(normalized)) return "duplicate";
+  if (["imported", "processed", "success", "saved", "synced"].includes(normalized)) return "imported";
+  return fallback;
+}
+
+function selectMatchingResult(response, filePath) {
+  const results = Array.isArray(response?.results)
+    ? response.results
+    : Array.isArray(response?.file_results)
+      ? response.file_results
+      : [];
+  if (results.length === 0) {
+    return null;
+  }
+
+  const exactMatch = results.find((result) => {
+    const candidate = result?.file_path || result?.filePath || result?.path;
+    return candidate === filePath;
+  });
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  return results.length === 1 ? results[0] : null;
+}
+
+function buildFileResult({
+  file,
+  response = null,
+  attemptAt,
+  previousResult = null,
+  error = null,
+}) {
+  const matchedResult = response ? selectMatchingResult(response, file.filePath) : null;
+  const rawError =
+    error
+    ?? matchedResult?.error
+    ?? matchedResult?.error_message
+    ?? matchedResult?.reason
+    ?? response?.error
+    ?? response?.message
+    ?? null;
+  const responseSummary = response?.summary ?? null;
+
+  let status = matchedResult?.status ? normalizeStatus(matchedResult.status) : null;
+  if (!status) {
+    if ((responseSummary?.failed_file_count ?? 0) > 0) {
+      status = "failed";
+    } else if ((responseSummary?.duplicate_count ?? 0) > 0) {
+      status = "duplicate";
+    } else if ((responseSummary?.skipped_count ?? 0) > 0) {
+      status = "skipped";
+    } else {
+      status = error ? "failed" : "imported";
+    }
+  }
+
+  const lastSuccessAt =
+    status === "failed"
+      ? previousResult?.lastSuccessAt ?? previousResult?.last_success_at ?? null
+      : attemptAt;
+  const lastSuccessfulContentHash =
+    status === "failed"
+      ? previousResult?.lastSuccessfulContentHash
+        ?? previousResult?.last_successful_content_hash
+        ?? previousResult?.contentHash
+        ?? previousResult?.content_hash
+        ?? null
+      : file.contentHash;
+
+  return {
+    filePath: file.filePath,
+    contentHash: file.contentHash,
+    status,
+    lastAttemptAt: attemptAt,
+    lastSuccessAt,
+    lastSuccessfulContentHash,
+    lastError: status === "failed" ? String(rawError || "Unknown import failure") : null,
+    stage: matchedResult?.stage ?? matchedResult?.stage_reached ?? null,
+    summary: {
+      file_count: responseSummary?.file_count ?? 1,
+      skipped_count: responseSummary?.skipped_count ?? (status === "skipped" ? 1 : 0),
+      new_source_count: responseSummary?.new_source_count ?? (status === "imported" ? 1 : 0),
+      new_memory_count: responseSummary?.new_memory_count ?? 0,
+      duplicate_count: responseSummary?.duplicate_count ?? (status === "duplicate" ? 1 : 0),
+      failed_file_count: responseSummary?.failed_file_count ?? (status === "failed" ? 1 : 0),
+    },
+  };
+}
+
 function buildProgressPayload({
   phase,
+  runId,
   trigger,
   startedAt,
   totalFiles,
   completedFiles,
-  batchIndex = 0,
-  batchCount = 0,
+  currentFileIndex = 0,
+  currentFilePath = null,
+  currentStage = null,
   currentFilePaths = [],
   completedFilePaths = [],
   failedFilePaths = [],
+  runResults = [],
   error = null,
 }) {
   const startedAtMs = new Date(startedAt).getTime();
@@ -50,69 +195,90 @@ function buildProgressPayload({
     completedFiles > 0 && remainingFiles > 0
       ? Math.round((elapsedMs / completedFiles) * remainingFiles)
       : null;
+  const counts = countStatuses(runResults);
+  const recentFileResult = runResults.length > 0 ? runResults[runResults.length - 1] : null;
 
   return {
     phase,
+    runId,
     trigger,
     startedAt,
     totalFiles,
     completedFiles,
     remainingFiles,
-    batchIndex,
-    batchCount,
+    currentFileIndex,
+    currentFilePath,
+    currentStage,
     currentFilePaths,
     completedFilePaths,
     failedFilePaths,
     elapsedMs,
     etaMs,
+    successCount: counts.successCount,
+    failedCount: counts.failedCount,
+    skippedCount: counts.skippedCount,
+    duplicateCount: counts.duplicateCount,
+    recentFileResult,
     error,
   };
 }
-
-export function formatStatusText(localState, remoteStatus = null) {
-  const lines = [];
-  lines.push("Echo Memory status:");
-
-  if (localState) {
-    lines.push(`- last_sync_at: ${localState.finished_at || "(unknown)"}`);
-    lines.push(`- last_sync_mode: ${localState.trigger || "(unknown)"}`);
-    lines.push(`- files_scanned: ${localState.summary?.file_count ?? 0}`);
-    lines.push(`- skipped: ${localState.summary?.skipped_count ?? 0}`);
-    lines.push(`- new_sources: ${localState.summary?.new_source_count ?? 0}`);
-    lines.push(`- new_memories: ${localState.summary?.new_memory_count ?? 0}`);
-    lines.push(`- duplicates: ${localState.summary?.duplicate_count ?? 0}`);
-    lines.push(`- failed_files: ${localState.summary?.failed_file_count ?? 0}`);
-    if (localState.error) {
-      lines.push(`- last_error: ${localState.error}`);
-    }
-  } else {
-    lines.push("- last_sync_at: (none)");
-  }
-
-  if (remoteStatus) {
-    lines.push("");
-    lines.push("Echo backend:");
-    lines.push(`- total_sources: ${remoteStatus.total_source_versions ?? 0}`);
-    lines.push(`- processed_sources: ${remoteStatus.processed_source_versions ?? 0}`);
-    lines.push(`- recent_memories: ${remoteStatus.recent_memory_count ?? 0}`);
-    lines.push(`- latest_imported_at: ${remoteStatus.latest_imported_at || "(none)"}`);
-  }
-
-  return lines.join("\n");
-}
-
-export function createSyncRunner({ api, cfg, client }) {
+
+export function formatStatusText(localState, remoteStatus = null) {
+  const lines = [];
+  lines.push("Echo Memory status:");
+
+  if (localState) {
+    lines.push(`- last_sync_at: ${localState.finished_at || "(unknown)"}`);
+    lines.push(`- last_sync_mode: ${localState.trigger || "(unknown)"}`);
+    lines.push(`- files_scanned: ${localState.summary?.file_count ?? 0}`);
+    lines.push(`- skipped: ${localState.summary?.skipped_count ?? 0}`);
+    lines.push(`- new_sources: ${localState.summary?.new_source_count ?? 0}`);
+    lines.push(`- new_memories: ${localState.summary?.new_memory_count ?? 0}`);
+    lines.push(`- duplicates: ${localState.summary?.duplicate_count ?? 0}`);
+    lines.push(`- failed_files: ${localState.summary?.failed_file_count ?? 0}`);
+    if (localState.error) {
+      lines.push(`- last_error: ${localState.error}`);
+    }
+  } else {
+    lines.push("- last_sync_at: (none)");
+  }
+
+  if (remoteStatus) {
+    lines.push("");
+    lines.push("Echo backend:");
+    lines.push(`- total_sources: ${remoteStatus.total_source_versions ?? 0}`);
+    lines.push(`- processed_sources: ${remoteStatus.processed_source_versions ?? 0}`);
+    lines.push(`- recent_memories: ${remoteStatus.recent_memory_count ?? 0}`);
+    lines.push(`- latest_imported_at: ${remoteStatus.latest_imported_at || "(none)"}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function createSyncRunner({ api, cfg, client, fallbackStateDir = null }) {
   let intervalHandle = null;
   let statePath = null;
   let activeRun = null;
+  let activeRunInfo = null;
   const progressListeners = new Set();
-
-  async function initialize(stateDir) {
-    statePath = resolveStatePath(stateDir || api.runtime.state.resolveStateDir());
-  }
-
+
+  async function initialize(stateDir) {
+    const resolvedStateDir = stateDir || resolveRuntimeStateDir(api, fallbackStateDir);
+    if (!resolvedStateDir) {
+      throw new Error("Echo memory state directory is unavailable");
+    }
+    statePath = resolveStatePath(resolvedStateDir);
+  }
+
   function getStatePath() {
-    return statePath || resolveStatePath(api.runtime.state.resolveStateDir());
+    if (statePath) {
+      return statePath;
+    }
+    const resolvedStateDir = resolveRuntimeStateDir(api, fallbackStateDir);
+    if (!resolvedStateDir) {
+      throw new Error("Echo memory state directory is unavailable");
+    }
+    return resolveStatePath(resolvedStateDir);
   }
 
   function emitProgress(event) {
@@ -129,43 +295,71 @@ export function createSyncRunner({ api, cfg, client }) {
     progressListeners.add(listener);
     return () => progressListeners.delete(listener);
   }
-
-  async function runSync(trigger = "manual", filterPaths = null) {
-    if (activeRun) {
-      return activeRun;
-    }
-
+
+  async function runSync(trigger = "manual", filterPaths = null) {
+    if (activeRun) {
+      return activeRun;
+    }
+
     activeRun = (async () => {
+      const runId = buildRunId();
       const startedAt = new Date().toISOString();
+      activeRunInfo = { runId, trigger, startedAt };
+
       let totalFiles = 0;
-      let batchCount = 0;
       let completedFiles = 0;
-      let currentBatchPaths = [];
+      let currentFilePath = null;
+      let currentFileIndex = 0;
+      const successfulPaths = [];
+      const failedPaths = [];
+      const runResults = [];
+
+      let prevState = null;
+      let prevResults = [];
+      const resultMap = new Map();
+
+      try {
+        prevState = await readLastSyncState(getStatePath());
+        prevResults = Array.isArray(prevState?.results) ? prevState.results : [];
+        for (const entry of prevResults) {
+          const key = entry?.filePath || entry?.file_path;
+          if (!key) continue;
+          resultMap.set(key, entry);
+        }
+      } catch {
+        prevState = null;
+        prevResults = [];
+      }
+
       try {
         if (!cfg.apiKey) {
+          const message = "Missing Echo API key";
           emitProgress(buildProgressPayload({
             phase: "failed",
+            runId,
             trigger,
             startedAt,
             totalFiles: 0,
             completedFiles: 0,
-            error: "Missing Echo API key",
+            runResults,
+            error: message,
           }));
           const state = {
-            trigger,
-            started_at: startedAt,
-            finished_at: new Date().toISOString(),
-            error: "Missing Echo API key",
-            summary: buildEmptySummary(0),
-            results: [],
-          };
-          await writeLastSyncState(getStatePath(), state);
-          return state;
-        }
-
-        await client.whoami();
-
-        let files = [];
+            trigger,
+            started_at: startedAt,
+            finished_at: new Date().toISOString(),
+            error: message,
+            summary: buildEmptySummary(0),
+            results: prevResults,
+            run_results: [],
+          };
+          await writeLastSyncState(getStatePath(), state);
+          return state;
+        }
+
+        await client.whoami();
+
+        let files = [];
         try {
           files = await scanOpenClawMemoryDir(cfg.memoryDir);
         } catch (error) {
@@ -174,182 +368,280 @@ export function createSyncRunner({ api, cfg, client }) {
             : String(error?.message ?? error);
           emitProgress(buildProgressPayload({
             phase: "failed",
+            runId,
             trigger,
             startedAt,
             totalFiles: 0,
             completedFiles: 0,
+            runResults,
             error: message,
           }));
           const state = {
-            trigger,
-            started_at: startedAt,
-            finished_at: new Date().toISOString(),
-            error: message,
-            summary: buildEmptySummary(0),
-            results: [],
-          };
-          await writeLastSyncState(getStatePath(), state);
-          return state;
-        }
-
-        // If filterPaths is provided (Set of absolute paths), only sync those files
-        if (filterPaths instanceof Set && filterPaths.size > 0) {
-          files = files.filter(f => filterPaths.has(f.filePath));
-        }
-
-        if (files.length === 0) {
+            trigger,
+            started_at: startedAt,
+            finished_at: new Date().toISOString(),
+            error: message,
+            summary: buildEmptySummary(0),
+            results: prevResults,
+            run_results: [],
+          };
+          await writeLastSyncState(getStatePath(), state);
+          return state;
+        }
+
+        if (filterPaths instanceof Set && filterPaths.size > 0) {
+          files = files.filter((file) => filterPaths.has(file.filePath));
+        }
+
+        totalFiles = files.length;
+        if (totalFiles === 0) {
           emitProgress(buildProgressPayload({
             phase: "finished",
+            runId,
             trigger,
             startedAt,
             totalFiles: 0,
             completedFiles: 0,
+            runResults,
           }));
           const state = {
-            trigger,
-            started_at: startedAt,
-            finished_at: new Date().toISOString(),
-            summary: buildEmptySummary(0),
-            results: [],
-          };
-          await writeLastSyncState(getStatePath(), state);
-          return state;
-        }
-
-        const summary = buildEmptySummary();
-        const batches = chunk(files, cfg.batchSize);
-        totalFiles = files.length;
-        batchCount = batches.length;
+            trigger,
+            started_at: startedAt,
+            finished_at: new Date().toISOString(),
+            summary: buildEmptySummary(0),
+            results: prevResults,
+            run_results: [],
+          };
+          await writeLastSyncState(getStatePath(), state);
+          return state;
+        }
 
         emitProgress(buildProgressPayload({
           phase: "started",
+          runId,
           trigger,
           startedAt,
           totalFiles,
           completedFiles: 0,
-          batchCount,
           currentFilePaths: files.map((file) => file.filePath),
+          runResults,
         }));
 
-        for (const [index, batch] of batches.entries()) {
-          currentBatchPaths = batch.map((file) => file.filePath);
-          emitProgress(buildProgressPayload({
-            phase: "batch-started",
-            trigger,
-            startedAt,
-            totalFiles,
-            completedFiles,
-            batchIndex: index + 1,
-            batchCount,
-            currentFilePaths: currentBatchPaths,
-          }));
-          const response = await client.importMarkdown(batch);
-          mergeSummary(summary, response.summary ?? {});
-          completedFiles += batch.length;
+        const summary = buildEmptySummary(0);
+
+        for (const [index, file] of files.entries()) {
+          currentFileIndex = index + 1;
+          currentFilePath = file.filePath;
           emitProgress(buildProgressPayload({
-            phase: "batch-finished",
+            phase: "file-started",
+            runId,
             trigger,
             startedAt,
             totalFiles,
             completedFiles,
-            batchIndex: index + 1,
-            batchCount,
-            completedFilePaths: currentBatchPaths,
+            currentFileIndex,
+            currentFilePath,
+            currentStage: "parse",
+            currentFilePaths: [file.filePath],
+            completedFilePaths: successfulPaths,
+            failedFilePaths: failedPaths,
+            runResults,
           }));
+
+          const attemptAt = new Date().toISOString();
+          const previousResult = resultMap.get(file.filePath) ?? null;
+
+          try {
+            const response = await client.importMarkdown([file], {
+              onStageEvent: (stageEvent) => {
+                emitProgress(buildProgressPayload({
+                  phase: "file-stage",
+                  runId,
+                  trigger,
+                  startedAt,
+                  totalFiles,
+                  completedFiles,
+                  currentFileIndex,
+                  currentFilePath,
+                  currentStage: stageEvent?.stage || null,
+                  currentFilePaths: [file.filePath],
+                  completedFilePaths: successfulPaths,
+                  failedFilePaths: failedPaths,
+                  runResults,
+                }));
+              },
+            });
+            if (response?.summary) {
+              mergeSummary(summary, response.summary);
+            }
+
+            const fileResult = buildFileResult({
+              file,
+              response,
+              attemptAt,
+              previousResult,
+            });
+
+            if (!response?.summary) {
+              applyManualFileSummary(summary, fileResult.status);
+            }
+
+            runResults.push(fileResult);
+            resultMap.set(file.filePath, fileResult);
+            completedFiles += 1;
+
+            if (fileResult.status === "failed") {
+              failedPaths.push(file.filePath);
+            } else {
+              successfulPaths.push(file.filePath);
+            }
+
+            emitProgress(buildProgressPayload({
+              phase: "file-finished",
+              runId,
+              trigger,
+              startedAt,
+              totalFiles,
+              completedFiles,
+              currentFileIndex,
+              currentFilePath,
+              currentStage: fileResult.stage,
+              currentFilePaths: [file.filePath],
+              completedFilePaths: fileResult.status === "failed" ? [] : [file.filePath],
+              failedFilePaths: fileResult.status === "failed" ? [file.filePath] : [],
+              runResults,
+            }));
+          } catch (error) {
+            const fileResult = buildFileResult({
+              file,
+              attemptAt,
+              previousResult,
+              error: String(error?.message ?? error),
+            });
+
+            applyManualFileSummary(summary, fileResult.status);
+            runResults.push(fileResult);
+            resultMap.set(file.filePath, fileResult);
+            completedFiles += 1;
+            failedPaths.push(file.filePath);
+
+            emitProgress(buildProgressPayload({
+              phase: "file-finished",
+              runId,
+              trigger,
+              startedAt,
+              totalFiles,
+              completedFiles,
+              currentFileIndex,
+              currentFilePath,
+              currentStage: fileResult.stage,
+              currentFilePaths: [file.filePath],
+              failedFilePaths: [file.filePath],
+              runResults,
+            }));
+          }
         }
-
-        const newResults = files.map((f) => ({ filePath: f.filePath, contentHash: f.contentHash, status: "imported" }));
-
-        // Merge with existing state — preserve previously synced files
-        let mergedResults = newResults;
-        if (filterPaths instanceof Set && filterPaths.size > 0) {
-          const prevState = await readLastSyncState(getStatePath());
-          const prevResults = Array.isArray(prevState?.results) ? prevState.results : [];
-          // Keep previous results that weren't in this batch, add new ones
-          const newPathSet = new Set(newResults.map(r => r.filePath));
-          mergedResults = [
-            ...prevResults.filter(r => !newPathSet.has(r.filePath || r.file_path)),
-            ...newResults,
-          ];
-        }
-
+
+        const mergedResults = [...resultMap.values()];
         const state = {
-          trigger,
-          started_at: startedAt,
-          finished_at: new Date().toISOString(),
-          summary,
-          results: mergedResults,
+          trigger,
+          started_at: startedAt,
+          finished_at: new Date().toISOString(),
+          summary,
+          results: mergedResults,
+          run_results: runResults,
         };
         await writeLastSyncState(getStatePath(), state);
+
         emitProgress(buildProgressPayload({
           phase: "finished",
+          runId,
           trigger,
           startedAt,
           totalFiles,
           completedFiles,
-          batchIndex: batchCount,
-          batchCount,
-          completedFilePaths: files.map((file) => file.filePath),
+          currentFileIndex,
+          currentFilePath,
+          completedFilePaths: successfulPaths,
+          failedFilePaths: failedPaths,
+          runResults,
         }));
+
         api.logger?.info?.(
-          `[echo-memory] sync complete: files=${summary.file_count} new_memories=${summary.new_memory_count} skipped=${summary.skipped_count} failed=${summary.failed_file_count}`,
-        );
-        return state;
+          `[echo-memory] sync complete: files=${summary.file_count} new_memories=${summary.new_memory_count} skipped=${summary.skipped_count} failed=${summary.failed_file_count}`,
+        );
+        return state;
       } catch (error) {
         const message = String(error?.message ?? error);
         emitProgress(buildProgressPayload({
           phase: "failed",
+          runId,
           trigger,
           startedAt,
           totalFiles,
           completedFiles,
-          batchCount,
-          currentFilePaths: currentBatchPaths,
-          failedFilePaths: currentBatchPaths,
+          currentFileIndex,
+          currentFilePath,
+          currentFilePaths: currentFilePath ? [currentFilePath] : [],
+          failedFilePaths: currentFilePath ? [currentFilePath] : [],
+          runResults,
           error: message,
         }));
+
         const state = {
-          trigger,
-          started_at: startedAt,
-          finished_at: new Date().toISOString(),
-          error: message,
-          summary: buildEmptySummary(0),
-          results: [],
-        };
-        await writeLastSyncState(getStatePath(), state);
-        return state;
-      }
-    })().finally(() => {
-      activeRun = null;
-    });
-
-    return activeRun;
-  }
-
-  function startInterval() {
-    stopInterval();
-    const intervalMs = cfg.syncIntervalMinutes * 60 * 1000;
-    intervalHandle = setInterval(() => {
-      runSync("scheduled").catch((error) => {
-        api.logger?.warn?.(`[echo-memory] scheduled sync failed: ${String(error?.message ?? error)}`);
-      });
-    }, intervalMs);
-    intervalHandle.unref?.();
-  }
-
-  function stopInterval() {
-    if (intervalHandle) {
-      clearInterval(intervalHandle);
-      intervalHandle = null;
-    }
-  }
-
+          trigger,
+          started_at: startedAt,
+          finished_at: new Date().toISOString(),
+          error: message,
+          summary: buildEmptySummary(0),
+          results: [...resultMap.values()],
+          run_results: runResults,
+        };
+        await writeLastSyncState(getStatePath(), state);
+        return state;
+      }
+    })().finally(() => {
+      activeRun = null;
+      activeRunInfo = null;
+    });
+
+    return activeRun;
+  }
+
+  function startInterval() {
+    stopInterval();
+    const intervalMs = cfg.syncIntervalMinutes * 60 * 1000;
+    intervalHandle = setInterval(() => {
+      runSync("scheduled").catch((error) => {
+        api.logger?.warn?.(`[echo-memory] scheduled sync failed: ${String(error?.message ?? error)}`);
+      });
+    }, intervalMs);
+    intervalHandle.unref?.();
+  }
+
+  function stopInterval() {
+    if (intervalHandle) {
+      clearInterval(intervalHandle);
+      intervalHandle = null;
+    }
+  }
+
+  function isRunning() {
+    return Boolean(activeRun);
+  }
+
+  function getActiveRunInfo() {
+    return activeRunInfo;
+  }
+
   return {
     initialize,
     getStatePath,
     onProgress,
     runSync,
-    startInterval,
-    stopInterval,
-  };
-}
+    startInterval,
+    stopInterval,
+    isRunning,
+    getActiveRunInfo,
+  };
+}