@engramx/client 0.1.0

package/dist/migrate.js

@@ -0,0 +1,882 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { EngramClient } from './EngramClient';
+function getOpenClawDir() {
+    return process.env['OPENCLAW_CONFIG_DIR'] || path.join(process.env['HOME'] || '', '.openclaw');
+}
+function loadOpenClawConfig(openclawDir) {
+    const configPath = process.env['OPENCLAW_CONFIG_PATH'] ?? path.join(openclawDir, 'openclaw.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve the memory directory from openclaw.json config.
+ *
+ * Priority:
+ *   1. EngramX plugin config memoryDir (plugins.entries["memory-engramx"].config.memoryDir)
+ *   2. Store path base directory (agents.defaults.memorySearch.store.path)
+ *   3. Default: {openclawDir}/memory
+ */
+function resolveMemoryDir(openclawDir, ocConfig) {
+    // Check EngramX plugin config for a memoryDir override
+    const engramxEntry = ocConfig.plugins?.entries?.['memory-engramx'];
+    if (engramxEntry?.config?.memoryDir) {
+        const dir = engramxEntry.config.memoryDir;
+        // Handle relative paths as relative to openclawDir
+        return path.isAbsolute(dir) ? dir : path.join(openclawDir, dir);
+    }
+    // Check store path for base directory
+    const storePath = ocConfig.agents?.defaults?.memorySearch?.store?.path;
+    if (storePath) {
+        // Store path may contain {agentId} tokens — derive the base directory
+        const withoutToken = storePath.replace(/\{agentId\}.*$/, '');
+        const resolved = path.isAbsolute(withoutToken)
+            ? path.dirname(withoutToken)
+            : path.join(openclawDir, path.dirname(withoutToken));
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    return path.join(openclawDir, 'memory');
+}
+/**
+ * Resolve the workspace directory from openclaw.json config.
+ *
+ * Priority:
+ *   1. agents.defaults.workspace
+ *   2. Default: {openclawDir}/workspace
+ *
+ * The workspace contains the agent's identity files (SOUL.md, USER.md,
+ * IDENTITY.md, AGENTS.md, etc.) and is separate from the memory directory.
+ */
+function resolveWorkspaceDir(openclawDir, ocConfig) {
+    const workspace = ocConfig.agents?.defaults?.workspace;
+    if (workspace) {
+        return path.isAbsolute(workspace) ? workspace : path.join(openclawDir, workspace);
+    }
+    return path.join(openclawDir, 'workspace');
+}
+/**
+ * Resolve the SOUL.md path from openclaw.json config.
+ *
+ * Priority:
+ *   1. agents.defaults.soul.path (explicit override)
+ *   2. {workspaceDir}/SOUL.md
+ *   3. {openclawDir}/SOUL.md (legacy fallback)
+ */
+function resolveSoulPath(openclawDir, ocConfig) {
+    const soulPath = ocConfig.agents?.defaults?.soul?.path;
+    if (soulPath) {
+        return path.isAbsolute(soulPath) ? soulPath : path.join(openclawDir, soulPath);
+    }
+    // Check workspace directory first
+    const workspaceDir = resolveWorkspaceDir(openclawDir, ocConfig);
+    const workspaceSoul = path.join(workspaceDir, 'SOUL.md');
+    if (fs.existsSync(workspaceSoul))
+        return workspaceSoul;
+    // Legacy fallback: directly in openclawDir
+    return path.join(openclawDir, 'SOUL.md');
+}
+// ── EngramX directory ─────────────────────────────────────────────
+function getEngramXDir() {
+    return path.join(process.env['HOME'] || '', '.engramx');
+}
+function getCheckpointsDir() {
+    return path.join(getEngramXDir(), 'checkpoints');
+}
+function makeCheckpointId() {
+    // Filesystem-safe ISO timestamp: 2026-02-23T10-30-00-000Z
+    return new Date().toISOString().replace(/:/g, '-').replace('.', '-');
+}
+// ── Pairing validation ────────────────────────────────────────────
+export async function hasValidPairing(options) {
+    const resolved = options.sessionKeyPath.startsWith('~')
+        ? path.join(process.env['HOME'] || '', options.sessionKeyPath.slice(1))
+        : options.sessionKeyPath;
+    if (!fs.existsSync(resolved))
+        return false;
+    try {
+        const client = new EngramClient({
+            canisterId: options.canisterId,
+            sessionKeyPath: options.sessionKeyPath,
+            host: options.host,
+        });
+        // Lightweight authenticated query — succeeds only if the operator is registered
+        await client.listBackups();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Database detection (config-driven) ────────────────────────────
+function detectDatabases(openclawDir, ocConfig) {
+    const databases = [];
+    const backend = ocConfig.memory?.backend;
+    if (!backend || backend === 'builtin') {
+        // SQLite: collect .sqlite files from openclawDir
+        const sqliteFiles = fs.existsSync(openclawDir)
+            ? fs
+                .readdirSync(openclawDir)
+                .filter((f) => f.endsWith('.sqlite'))
+                .map((f) => path.join(openclawDir, f))
+            : [];
+        if (sqliteFiles.length > 0) {
+            databases.push({ type: 'sqlite', paths: sqliteFiles });
+        }
+    }
+    if (backend === 'qmd') {
+        // QMD: agents/*/qmd/*.sqlite + *.db
+        const agentsDir = path.join(openclawDir, 'agents');
+        if (fs.existsSync(agentsDir)) {
+            const qmdPaths = [];
+            for (const agent of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+                if (!agent.isDirectory())
+                    continue;
+                const qmdDir = path.join(agentsDir, agent.name, 'qmd');
+                if (!fs.existsSync(qmdDir))
+                    continue;
+                for (const f of fs.readdirSync(qmdDir)) {
+                    if (f.endsWith('.sqlite') || f.endsWith('.db')) {
+                        qmdPaths.push(path.join(qmdDir, f));
+                    }
+                }
+            }
+            if (qmdPaths.length > 0) {
+                databases.push({ type: 'qmd', paths: qmdPaths });
+            }
+        }
+    }
+    const memorySlot = ocConfig.plugins?.slots?.memory;
+    if (memorySlot === 'memory-lancedb') {
+        const lanceDir = path.join(openclawDir, 'lancedb');
+        if (fs.existsSync(lanceDir)) {
+            databases.push({ type: 'lancedb', paths: [lanceDir] });
+        }
+    }
+    return databases;
+}
+// ── Checkpoint & Rollback ─────────────────────────────────────────
+function copyRecursive(src, dest) {
+    if (fs.statSync(src).isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            copyRecursive(path.join(src, entry.name), path.join(dest, entry.name));
+        }
+    }
+    else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+}
+export function createCheckpoint(mode, openclawDir, memoryDir, ocConfig) {
+    const checkpointId = makeCheckpointId();
+    const checkpointDir = path.join(getCheckpointsDir(), checkpointId);
+    fs.mkdirSync(checkpointDir, { recursive: true });
+    const savedFiles = [];
+    const filesDir = path.join(checkpointDir, 'files');
+    fs.mkdirSync(filesDir, { recursive: true });
+    // Copy top-level special files
+    const soulPath = resolveSoulPath(openclawDir, ocConfig);
+    if (fs.existsSync(soulPath)) {
+        fs.copyFileSync(soulPath, path.join(filesDir, 'SOUL.md'));
+        savedFiles.push(soulPath);
+    }
+    const memoryMdPath = path.join(openclawDir, 'MEMORY.md');
+    if (fs.existsSync(memoryMdPath)) {
+        fs.copyFileSync(memoryMdPath, path.join(filesDir, 'MEMORY.md'));
+        savedFiles.push(memoryMdPath);
+    }
+    // Recursively copy *.md from memory directory
+    if (fs.existsSync(memoryDir)) {
+        const memoryDest = path.join(filesDir, 'memory');
+        copyMarkdownTree(memoryDir, memoryDest);
+        collectMarkdownPaths(memoryDir, savedFiles);
+    }
+    // Copy databases
+    const databases = detectDatabases(openclawDir, ocConfig);
+    const dbsDir = path.join(checkpointDir, 'databases');
+    const savedDatabases = [];
+    for (const db of databases) {
+        const dbDest = path.join(dbsDir, db.type);
+        fs.mkdirSync(dbDest, { recursive: true });
+        for (const dbPath of db.paths) {
+            if (!fs.existsSync(dbPath))
+                continue;
+            if (fs.statSync(dbPath).isDirectory()) {
+                copyRecursive(dbPath, path.join(dbDest, path.basename(dbPath)));
+            }
+            else {
+                fs.copyFileSync(dbPath, path.join(dbDest, path.basename(dbPath)));
+            }
+        }
+        savedDatabases.push({ type: db.type, paths: db.paths });
+    }
+    // Write checkpoint metadata
+    const metadata = {
+        timestamp: new Date().toISOString(),
+        mode,
+        memoryDir,
+        openclawDir,
+        paths: { files: savedFiles, databases: savedDatabases },
+    };
+    fs.writeFileSync(path.join(checkpointDir, 'checkpoint.json'), JSON.stringify(metadata, null, 2) + '\n');
+    return checkpointDir;
+}
+export function listCheckpoints() {
+    const checkpointsDir = getCheckpointsDir();
+    if (!fs.existsSync(checkpointsDir))
+        return [];
+    const summaries = [];
+    for (const entry of fs.readdirSync(checkpointsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const metaPath = path.join(checkpointsDir, entry.name, 'checkpoint.json');
+        if (!fs.existsSync(metaPath))
+            continue;
+        try {
+            const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+            summaries.push({
+                id: entry.name,
+                timestamp: meta.timestamp,
+                mode: meta.mode,
+                dir: path.join(checkpointsDir, entry.name),
+            });
+        }
+        catch (err) {
+            console.warn(`engramx: skipping corrupted checkpoint ${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Sort newest first
+    summaries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return summaries;
+}
+export function rollbackCheckpoint(checkpointId) {
+    const checkpoints = listCheckpoints();
+    if (checkpoints.length === 0) {
+        throw new Error('No checkpoints to roll back. Run "npx @engramx/client pair" first to create a checkpoint.');
+    }
+    let target;
+    if (checkpointId) {
+        const found = checkpoints.find((c) => c.id === checkpointId);
+        if (!found) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        target = found;
+    }
+    else {
+        target = checkpoints[0]; // latest — length already checked above
+    }
+    const checkpointDir = target.dir;
+    const metadata = JSON.parse(fs.readFileSync(path.join(checkpointDir, 'checkpoint.json'), 'utf-8'));
+    const restoredFiles = [];
+    const restoredDatabases = [];
+    // Restore each file tracked in checkpoint metadata
+    const filesDir = path.join(checkpointDir, 'files');
+    const ocConfig = loadOpenClawConfig(metadata.openclawDir);
+    const soulPath = resolveSoulPath(metadata.openclawDir, ocConfig);
+    const workspaceDir = resolveWorkspaceDir(metadata.openclawDir, ocConfig);
+    // Build a helper to map checkpoint-relative path → original absolute path
+    function checkpointRelToOriginal(rel) {
+        // Guard: reject traversal sequences in checkpoint-relative paths
+        if (rel.includes('..') || rel.includes('\0')) {
+            throw new Error(`Unsafe checkpoint path: ${rel}`);
+        }
+        if (rel.startsWith('memory/') || rel.startsWith('memory\\')) {
+            const resolved = path.resolve(metadata.memoryDir, rel.slice('memory/'.length));
+            if (!resolved.startsWith(metadata.memoryDir + path.sep) && resolved !== metadata.memoryDir)
+                throw new Error(`Path escapes memory dir: ${rel}`);
+            return resolved;
+        }
+        // Top-level .md files are workspace files (SOUL.md, USER.md, IDENTITY.md, etc.)
+        if (rel.endsWith('.md') && !rel.includes('/')) {
+            if (rel === 'SOUL.md')
+                return soulPath;
+            if (fs.existsSync(workspaceDir))
+                return path.join(workspaceDir, rel);
+            return path.join(metadata.openclawDir, rel);
+        }
+        const resolved = path.resolve(metadata.openclawDir, rel);
+        if (!resolved.startsWith(metadata.openclawDir + path.sep) && resolved !== metadata.openclawDir)
+            throw new Error(`Path escapes openclaw dir: ${rel}`);
+        return resolved;
+    }
+    function originalToCheckpointRel(originalPath) {
+        // Check if it's a memory dir file
+        const memRel = path.relative(metadata.memoryDir, originalPath);
+        if (!memRel.startsWith('..')) {
+            return path.join('memory', memRel);
+        }
+        // Check if it's a workspace file
+        if (fs.existsSync(workspaceDir)) {
+            const wsRel = path.relative(workspaceDir, originalPath);
+            if (!wsRel.startsWith('..'))
+                return wsRel;
+        }
+        // Legacy: file directly in openclawDir
+        return path.relative(metadata.openclawDir, originalPath);
+    }
+    // Restore files tracked in metadata
+    const restoredRelPaths = new Set();
+    for (const originalPath of metadata.paths.files) {
+        const checkpointRelative = originalToCheckpointRel(originalPath);
+        restoredRelPaths.add(checkpointRelative);
+        const srcPath = path.join(filesDir, checkpointRelative);
+        if (!fs.existsSync(srcPath)) {
+            restoredFiles.push({ path: originalPath, status: 'skipped' });
+            continue;
+        }
+        try {
+            fs.mkdirSync(path.dirname(originalPath), { recursive: true });
+            fs.copyFileSync(srcPath, originalPath);
+            restoredFiles.push({ path: originalPath, status: 'restored' });
+        }
+        catch (err) {
+            restoredFiles.push({ path: originalPath, status: 'failed', error: err.message });
+        }
+    }
+    // Scan for physical checkpoint files not tracked in metadata
+    // (handles crash between unlinkSync and metadata write)
+    if (fs.existsSync(filesDir)) {
+        const physicalFiles = collectAllFiles(filesDir, filesDir);
+        for (const relPath of physicalFiles) {
+            if (restoredRelPaths.has(relPath))
+                continue;
+            const originalPath = checkpointRelToOriginal(relPath);
+            const srcPath = path.join(filesDir, relPath);
+            try {
+                fs.mkdirSync(path.dirname(originalPath), { recursive: true });
+                fs.copyFileSync(srcPath, originalPath);
+                restoredFiles.push({ path: originalPath, status: 'restored' });
+            }
+            catch (err) {
+                restoredFiles.push({ path: originalPath, status: 'failed', error: err.message });
+            }
+        }
+    }
+    // Restore databases
+    const dbsDir = path.join(checkpointDir, 'databases');
+    if (fs.existsSync(dbsDir)) {
+        for (const dbEntry of metadata.paths.databases) {
+            const dbSrc = path.join(dbsDir, dbEntry.type);
+            if (!fs.existsSync(dbSrc))
+                continue;
+            for (const originalPath of dbEntry.paths) {
+                const basename = path.basename(originalPath);
+                const srcPath = path.join(dbSrc, basename);
+                if (!fs.existsSync(srcPath))
+                    continue;
+                fs.mkdirSync(path.dirname(originalPath), { recursive: true });
+                if (fs.statSync(srcPath).isDirectory()) {
+                    if (fs.existsSync(originalPath)) {
+                        fs.rmSync(originalPath, { recursive: true, force: true });
+                    }
+                    copyRecursive(srcPath, originalPath);
+                }
+                else {
+                    fs.copyFileSync(srcPath, originalPath);
+                }
+            }
+            restoredDatabases.push(dbEntry.type);
+        }
+    }
+    const partial = restoredFiles.some((f) => f.status !== 'restored');
+    if (partial) {
+        // Keep checkpoint dir on partial failure so user can retry
+    }
+    else {
+        // Remove the rolled-back checkpoint on full success
+        fs.rmSync(checkpointDir, { recursive: true, force: true });
+    }
+    return { restoredFiles, restoredDatabases, checkpointTimestamp: metadata.timestamp, partial };
+}
+// ── Checkpoint metadata helper ─────────────────────────────────────
+function writeCheckpointMeta(checkpointDir, metadata) {
+    const metaPath = path.join(checkpointDir, 'checkpoint.json');
+    const tmpPath = metaPath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(metadata, null, 2) + '\n');
+    fs.renameSync(tmpPath, metaPath);
+}
+async function withRetry(fn, attempts = 3, delayMs = 1000, onRetry) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (i === attempts - 1)
+                throw err;
+            onRetry?.(i + 1, attempts);
+            await new Promise((r) => setTimeout(r, delayMs * 2 ** i));
+        }
+    }
+    throw new Error('unreachable');
+}
+// ── Migration ──────────────────────────────────────────────────────
+function collectOpenClawFiles(openclawDir, ocConfig) {
+    const memoryDir = resolveMemoryDir(openclawDir, ocConfig);
+    const soulPath = resolveSoulPath(openclawDir, ocConfig);
+    const workspaceDir = resolveWorkspaceDir(openclawDir, ocConfig);
+    const scannedDirs = [openclawDir];
+    if (fs.existsSync(workspaceDir) && workspaceDir !== openclawDir) {
+        scannedDirs.push(workspaceDir);
+    }
+    if (fs.existsSync(memoryDir) && memoryDir !== openclawDir && memoryDir !== workspaceDir) {
+        scannedDirs.push(memoryDir);
+    }
+    const files = [];
+    const seen = new Set();
+    // Workspace .md files: SOUL.md, USER.md, IDENTITY.md, AGENTS.md, TOOLS.md, HEARTBEAT.md, etc.
+    // These are the agent's identity/config files. BOOTSTRAP.md is excluded (one-time use).
+    if (fs.existsSync(workspaceDir)) {
+        for (const entry of fs.readdirSync(workspaceDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            if (entry.name === 'BOOTSTRAP.md')
+                continue; // One-time onboarding file
+            const absolutePath = path.join(workspaceDir, entry.name);
+            files.push({ relativePath: entry.name, absolutePath });
+            seen.add(absolutePath);
+        }
+    }
+    // Legacy fallback: check for top-level files directly in openclawDir
+    // (for setups without a separate workspace directory)
+    const legacyFiles = [
+        { name: 'SOUL.md', absolutePath: soulPath },
+        { name: 'MEMORY.md', absolutePath: path.join(openclawDir, 'MEMORY.md') },
+    ];
+    for (const { name, absolutePath } of legacyFiles) {
+        if (!seen.has(absolutePath) && fs.existsSync(absolutePath)) {
+            files.push({ relativePath: name, absolutePath });
+            seen.add(absolutePath);
+        }
+    }
+    // Memory directory: *.md files stored by the memory plugin
+    if (fs.existsSync(memoryDir)) {
+        collectMarkdownFiles(memoryDir, memoryDir, files);
+    }
+    return { files, scannedDirs, memoryDir, soulPath };
+}
+async function migrateFiles(client, files, filesDir, metadata, checkpointDir, options, result, onProgress) {
+    for (const file of files) {
+        try {
+            const content = fs.readFileSync(file.absolutePath, 'utf-8');
+            if (!content.trim()) {
+                const event = {
+                    type: 'skipped',
+                    relativePath: file.relativePath,
+                    absolutePath: file.absolutePath,
+                    reason: 'empty',
+                };
+                result.files.push(event);
+                result.skipped++;
+                onProgress?.(event);
+                continue;
+            }
+            if (options.dryRun) {
+                const event = {
+                    type: 'skipped',
+                    relativePath: file.relativePath,
+                    absolutePath: file.absolutePath,
+                    reason: 'dry-run',
+                };
+                result.files.push(event);
+                result.skipped++;
+                onProgress?.(event);
+                continue;
+            }
+            // Idempotency check: if the file already exists on the canister, skip upload
+            // but still checkpoint and delete the local copy.
+            let alreadyOnEngram = false;
+            try {
+                await client.readMemory(file.relativePath);
+                alreadyOnEngram = true;
+            }
+            catch {
+                /* doesn't exist — proceed with upload */
+            }
+            if (alreadyOnEngram) {
+                // Checkpoint and delete the local file even though we skip the upload
+                if (filesDir) {
+                    const checkpointFilePath = path.join(filesDir, file.relativePath);
+                    fs.mkdirSync(path.dirname(checkpointFilePath), { recursive: true });
+                    fs.copyFileSync(file.absolutePath, checkpointFilePath);
+                }
+                try {
+                    fs.unlinkSync(file.absolutePath);
+                }
+                catch (unlinkErr) {
+                    if (unlinkErr.code !== 'ENOENT')
+                        throw unlinkErr;
+                }
+                metadata.paths.files.push(file.absolutePath);
+                if (checkpointDir)
+                    writeCheckpointMeta(checkpointDir, metadata);
+                const event = {
+                    type: 'skipped',
+                    relativePath: file.relativePath,
+                    absolutePath: file.absolutePath,
+                    reason: 'already on engram',
+                };
+                result.files.push(event);
+                result.skipped++;
+                onProgress?.(event);
+                continue;
+            }
+            // Upload to engram with retry
+            await withRetry(() => client.appendMemory(file.relativePath, content), 3, 1000, (attempt, maxAttempts) => {
+                onProgress?.({
+                    type: 'retry',
+                    relativePath: file.relativePath,
+                    absolutePath: file.absolutePath,
+                    attempt,
+                    maxAttempts,
+                });
+            });
+            // Copy file to checkpoint dir
+            const checkpointFilePath = path.join(filesDir, file.relativePath);
+            fs.mkdirSync(path.dirname(checkpointFilePath), { recursive: true });
+            fs.copyFileSync(file.absolutePath, checkpointFilePath);
+            // Delete from disk
+            try {
+                fs.unlinkSync(file.absolutePath);
+            }
+            catch (unlinkErr) {
+                if (unlinkErr.code !== 'ENOENT')
+                    throw unlinkErr;
+            }
+            // Update checkpoint metadata incrementally
+            metadata.paths.files.push(file.absolutePath);
+            writeCheckpointMeta(checkpointDir, metadata);
+            const event = {
+                type: 'migrated',
+                relativePath: file.relativePath,
+                absolutePath: file.absolutePath,
+            };
+            result.files.push(event);
+            result.migrated++;
+            onProgress?.(event);
+        }
+        catch (err) {
+            const event = {
+                type: 'error',
+                relativePath: file.relativePath,
+                absolutePath: file.absolutePath,
+                error: err.message,
+            };
+            result.files.push(event);
+            result.errors.push(`${file.relativePath}: ${err.message}`);
+            onProgress?.(event);
+            // Stop on first error — file is still on disk, already-migrated files are in checkpoint
+            break;
+        }
+    }
+}
+export async function migrateOpenClawMemory(options, onProgress) {
+    const openclawDir = getOpenClawDir();
+    const ocConfig = loadOpenClawConfig(openclawDir);
+    const { files, scannedDirs, memoryDir } = collectOpenClawFiles(openclawDir, ocConfig);
+    // Emit scan event
+    onProgress?.({ type: 'scan', relativePath: '', absolutePath: '', totalFiles: files.length });
+    const result = {
+        checkpointDir: '',
+        scannedDirs,
+        files: [],
+        migrated: 0,
+        skipped: 0,
+        errors: [],
+    };
+    if (files.length === 0) {
+        return result;
+    }
+    if (options.dryRun) {
+        // Dry-run: skip checkpoint creation, DB backup, and client instantiation
+        await migrateFiles(null, files, '', {
+            timestamp: '',
+            mode: 'migration',
+            memoryDir,
+            openclawDir,
+            paths: { files: [], databases: [] },
+        }, '', options, result, onProgress);
+        return result;
+    }
+    // Create checkpoint dir (empty — no upfront bulk file copy)
+    const checkpointId = makeCheckpointId();
+    const checkpointDir = path.join(getCheckpointsDir(), checkpointId);
+    fs.mkdirSync(checkpointDir, { recursive: true });
+    const filesDir = path.join(checkpointDir, 'files');
+    fs.mkdirSync(filesDir, { recursive: true });
+    // Checkpoint databases upfront (safety copy, not migrated file-by-file)
+    const databases = detectDatabases(openclawDir, ocConfig);
+    const dbsDir = path.join(checkpointDir, 'databases');
+    const savedDatabases = [];
+    for (const db of databases) {
+        const dbDest = path.join(dbsDir, db.type);
+        fs.mkdirSync(dbDest, { recursive: true });
+        for (const dbPath of db.paths) {
+            if (!fs.existsSync(dbPath))
+                continue;
+            if (fs.statSync(dbPath).isDirectory()) {
+                copyRecursive(dbPath, path.join(dbDest, path.basename(dbPath)));
+            }
+            else {
+                fs.copyFileSync(dbPath, path.join(dbDest, path.basename(dbPath)));
+            }
+        }
+        savedDatabases.push({ type: db.type, paths: db.paths });
+    }
+    // Initialize checkpoint metadata (grows incrementally as files are migrated)
+    const metadata = {
+        timestamp: new Date().toISOString(),
+        mode: 'migration',
+        memoryDir,
+        openclawDir,
+        paths: { files: [], databases: savedDatabases },
+    };
+    writeCheckpointMeta(checkpointDir, metadata);
+    result.checkpointDir = checkpointDir;
+    const client = new EngramClient({
+        canisterId: options.canisterId,
+        sessionKeyPath: options.sessionKeyPath,
+        host: options.host,
+    });
+    await migrateFiles(client, files, filesDir, metadata, checkpointDir, options, result, onProgress);
+    return result;
+}
+// ── Resume / Incomplete checkpoint detection ──────────────────────
+function collectAllFiles(dir, baseDir) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectAllFiles(fullPath, baseDir));
+        }
+        else if (entry.isFile()) {
+            results.push(path.relative(baseDir, fullPath));
+        }
+    }
+    return results;
+}
+export function findIncompleteCheckpoint() {
+    const checkpoints = listCheckpoints();
+    const migrationCheckpoints = checkpoints.filter((c) => c.mode === 'migration');
+    for (const checkpoint of migrationCheckpoints) {
+        const metaPath = path.join(checkpoint.dir, 'checkpoint.json');
+        if (!fs.existsSync(metaPath))
+            continue;
+        let metadata;
+        try {
+            metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        // Re-scan source dirs to find files that still exist on disk
+        const openclawDir = metadata.openclawDir;
+        const ocConfig = loadOpenClawConfig(openclawDir);
+        const { files: currentFiles } = collectOpenClawFiles(openclawDir, ocConfig);
+        if (currentFiles.length > 0) {
+            // There are source files that haven't been migrated yet
+            return {
+                checkpoint,
+                metadata,
+                migratedCount: metadata.paths.files.length,
+                remainingCount: currentFiles.length,
+            };
+        }
+    }
+    return null;
+}
+export async function resumeMigration(options, onProgress) {
+    const incomplete = findIncompleteCheckpoint();
+    if (!incomplete) {
+        throw new Error('No incomplete migration found to resume.');
+    }
+    const { checkpoint, metadata } = incomplete;
+    const checkpointDir = checkpoint.dir;
+    const filesDir = path.join(checkpointDir, 'files');
+    if (!fs.existsSync(filesDir)) {
+        fs.mkdirSync(filesDir, { recursive: true });
+    }
+    // Re-scan source dirs for remaining files
+    const openclawDir = metadata.openclawDir;
+    const ocConfig = loadOpenClawConfig(openclawDir);
+    const { files: allFiles, scannedDirs } = collectOpenClawFiles(openclawDir, ocConfig);
+    // Filter out already-migrated files (tracked in metadata.paths.files)
+    const migratedSet = new Set(metadata.paths.files);
+    const remainingFiles = allFiles.filter((f) => !migratedSet.has(f.absolutePath));
+    // Emit scan event
+    onProgress?.({
+        type: 'scan',
+        relativePath: '',
+        absolutePath: '',
+        totalFiles: remainingFiles.length,
+    });
+    const result = {
+        checkpointDir,
+        scannedDirs,
+        files: [],
+        migrated: 0,
+        skipped: 0,
+        errors: [],
+    };
+    if (remainingFiles.length === 0) {
+        return result;
+    }
+    const client = new EngramClient({
+        canisterId: options.canisterId,
+        sessionKeyPath: options.sessionKeyPath,
+        host: options.host,
+    });
+    await migrateFiles(client, remainingFiles, filesDir, metadata, checkpointDir, options, result, onProgress);
+    return result;
+}
+// ── Recovery ──────────────────────────────────────────────────────
+export async function recoverOpenClaw(options) {
+    const openclawDir = getOpenClawDir();
+    const ocConfig = loadOpenClawConfig(openclawDir);
+    const memoryDir = resolveMemoryDir(openclawDir, ocConfig);
+    // Checkpoint local state before recovery
+    const checkpointDir = createCheckpoint('recovery', openclawDir, memoryDir, ocConfig);
+    const result = { checkpointDir, restoredBackups: [], errors: [] };
+    const client = new EngramClient({
+        canisterId: options.canisterId,
+        sessionKeyPath: options.sessionKeyPath,
+        host: options.host,
+    });
+    // List all backups and pick latest Finalized per dbType
+    let backups;
+    try {
+        backups = await client.listBackups();
+    }
+    catch (err) {
+        result.errors.push(`Failed to list backups: ${err.message}`);
+        return result;
+    }
+    const finalized = backups.filter((b) => 'Finalized' in b.status);
+    const latestByType = new Map();
+    for (const backup of finalized) {
+        const existing = latestByType.get(backup.dbType);
+        if (!existing || backup.createdAt > existing.createdAt) {
+            latestByType.set(backup.dbType, backup);
+        }
+    }
+    for (const [dbType, backup] of latestByType) {
+        try {
+            // Download all chunks (parallel batches of 4)
+            const BATCH_SIZE = 4;
+            const chunkCount = Number(backup.chunkCount);
+            const chunks = new Array(chunkCount);
+            for (let start = 0; start < chunkCount; start += BATCH_SIZE) {
+                const batch = Array.from({ length: Math.min(BATCH_SIZE, chunkCount - start) }, (_, i) => client.pullBackupChunk(backup.backupId, start + i).then((chunk) => {
+                    chunks[start + i] = chunk;
+                }));
+                await Promise.all(batch);
+            }
+            // Concatenate chunks
+            const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+            const data = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const chunk of chunks) {
+                data.set(chunk, offset);
+                offset += chunk.length;
+            }
+            // Write to disk based on type
+            restoreBackupData(openclawDir, ocConfig, dbType, data);
+            result.restoredBackups.push({
+                dbType,
+                backupId: backup.backupId,
+                size: totalLength,
+            });
+        }
+        catch (err) {
+            result.errors.push(`${dbType} (${backup.backupId}): ${err.message}`);
+        }
+    }
+    return result;
+}
+function restoreBackupData(openclawDir, ocConfig, dbType, data) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(dbType)) {
+        throw new Error(`Invalid dbType: ${dbType}`);
+    }
+    if (dbType === 'sqlite') {
+        // Single .sqlite file — write directly
+        const destDir = openclawDir;
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.writeFileSync(path.join(destDir, 'openclaw.sqlite'), data);
+    }
+    else {
+        // tar.gz archive (qmd, lancedb, multi-sqlite) — extract to target directory
+        let extractDir;
+        if (dbType === 'qmd') {
+            extractDir = path.join(openclawDir, 'agents');
+        }
+        else if (dbType === 'lancedb') {
+            extractDir = path.join(openclawDir, 'lancedb');
+        }
+        else {
+            extractDir = openclawDir;
+        }
+        fs.mkdirSync(extractDir, { recursive: true });
+        const tmpFile = path.join(getEngramXDir(), `restore-${dbType}-${Date.now()}.tar.gz`);
+        try {
+            fs.writeFileSync(tmpFile, data);
+            execFileSync('tar', ['--no-same-owner', '-xzf', tmpFile, '-C', extractDir], {
+                timeout: 120000,
+                stdio: 'pipe',
+            });
+        }
+        finally {
+            if (fs.existsSync(tmpFile))
+                fs.unlinkSync(tmpFile);
+        }
+    }
+}
+// ── File helpers ──────────────────────────────────────────────────
+function collectMarkdownFiles(dir, baseDir, files) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectMarkdownFiles(fullPath, baseDir, files);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            const relativePath = path.relative(baseDir, fullPath);
+            files.push({ relativePath: `memory/${relativePath}`, absolutePath: fullPath });
+        }
+    }
+}
+function copyMarkdownTree(srcDir, destDir) {
+    if (!fs.existsSync(srcDir))
+        return;
+    fs.mkdirSync(destDir, { recursive: true });
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const src = path.join(srcDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyMarkdownTree(src, dest);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            fs.copyFileSync(src, dest);
+        }
+    }
+}
+function collectMarkdownPaths(dir, out) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectMarkdownPaths(fullPath, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            out.push(fullPath);
+        }
+    }
+}
+//# sourceMappingURL=migrate.js.map