rol-websocket-channel 1.0.0

package/dist/src/admin/methods/agents-extended.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists, readJsonFile, writeJsonFile } from '../lib/fs.ts';
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
+const ALLOWED_AGENT_UPDATES = {
+    'name': true,
+    'workspace': true,
+    'agentDir': true,
+    'model.primary': true,
+    'model.provider': true,
+    'skills': true,
+    'tools.profile': true,
+    'behavior': true,
+};
+export const listAgents = async (_params, context) => {
+    const configPath = path.join(context.openclawRoot, 'openclaw.json');
+    const config = await loadConfig(context.openclawRoot);
+    const items = normalizeAgentList(config);
+    return {
+        sourceConfigFile: configPath,
+        count: items.length,
+        items
+    };
+};
+export const createAgent = async (params, context) => {
+    const objectParams = expectObject(params);
+    const rawAgentId = typeof objectParams.agentId === 'string'
+        ? objectParams.agentId
+        : typeof objectParams.id === 'string'
+            ? objectParams.id
+            : undefined;
+    const agentId = sanitizeAgentId(expectString(rawAgentId, 'agentId'));
+    const configPath = path.join(context.openclawRoot, 'openclaw.json');
+    const config = await loadConfig(context.openclawRoot);
+    const agents = ensureAgentList(config);
+    if (findNamedAgent(agents, agentId)) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Agent already exists: ${agentId}`);
+    }
+    const workspace = typeof objectParams.workspace === 'string' && objectParams.workspace.trim().length > 0
+        ? objectParams.workspace.trim()
+        : path.join(context.openclawRoot, 'workspace', agentId);
+    const agentDir = typeof objectParams.agentDir === 'string' && objectParams.agentDir.trim().length > 0
+        ? objectParams.agentDir.trim()
+        : path.join(context.openclawRoot, 'agents', agentId, 'agent');
+    const created = {
+        id: agentId,
+        name: typeof objectParams.name === 'string' && objectParams.name.trim().length > 0
+            ? objectParams.name.trim()
+            : agentId,
+        workspace,
+        agentDir
+    };
+    if (typeof objectParams.modelPrimary === 'string' && objectParams.modelPrimary.trim().length > 0) {
+        created.model = { ...(created.model ?? {}), primary: objectParams.modelPrimary.trim() };
+    }
+    if (typeof objectParams.modelProvider === 'string' && objectParams.modelProvider.trim().length > 0) {
+        created.model = { ...(created.model ?? {}), provider: objectParams.modelProvider.trim() };
+    }
+    if (Array.isArray(objectParams.skills)) {
+        created.skills = objectParams.skills.filter((item) => typeof item === 'string');
+    }
+    if (typeof objectParams.toolsProfile === 'string' && objectParams.toolsProfile.trim().length > 0) {
+        created.tools = { ...(created.tools ?? {}), profile: objectParams.toolsProfile.trim() };
+    }
+    if (isObject(objectParams.behavior)) {
+        created.behavior = objectParams.behavior;
+    }
+    agents.push(created);
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.mkdir(agentDir, { recursive: true });
+    await writeJsonFile(configPath, config);
+    return {
+        success: true,
+        configFile: configPath,
+        created
+    };
+};
+export const deleteAgent = async (params, context) => {
+    const objectParams = expectObject(params);
+    const rawAgentId = typeof objectParams.agentId === 'string'
+        ? objectParams.agentId
+        : typeof objectParams.id === 'string'
+            ? objectParams.id
+            : undefined;
+    const agentId = sanitizeAgentId(expectString(rawAgentId, 'agentId'));
+    const purgeFiles = objectParams.purgeFiles === true;
+    const configPath = path.join(context.openclawRoot, 'openclaw.json');
+    const config = await loadConfig(context.openclawRoot);
+    const agents = ensureAgentList(config);
+    const index = agents.findIndex((agent) => isMatchingAgent(agent, agentId));
+    if (index === -1) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Agent not found: ${agentId}`);
+    }
+    const [removed] = agents.splice(index, 1);
+    await writeJsonFile(configPath, config);
+    const removedPaths = [];
+    if (purgeFiles) {
+        const workspaceRoot = path.normalize(path.join(context.openclawRoot, 'workspace'));
+        const agentsRoot = path.normalize(path.join(context.openclawRoot, 'agents'));
+        const purgeCandidates = [
+            typeof removed.workspace === 'string' ? removed.workspace : null,
+            typeof removed.agentDir === 'string' ? path.dirname(removed.agentDir) : null
+        ].filter((value) => Boolean(value));
+        for (const candidate of purgeCandidates) {
+            const normalized = path.normalize(candidate);
+            const insideWorkspace = normalized === workspaceRoot || normalized.startsWith(`${workspaceRoot}${path.sep}`);
+            const insideAgents = normalized === agentsRoot || normalized.startsWith(`${agentsRoot}${path.sep}`);
+            if (!insideWorkspace && !insideAgents) {
+                continue;
+            }
+            if (await pathExists(candidate)) {
+                await fs.rm(candidate, { recursive: true, force: true });
+                removedPaths.push(candidate);
+            }
+        }
+    }
+    return {
+        success: true,
+        configFile: configPath,
+        removed,
+        purgeFiles,
+        removedPaths
+    };
+};
+export const updateAgent = async (params, context) => {
+    const objectParams = isObject(params) ? params : {};
+    const updates = isObject(objectParams.updates) ? objectParams.updates : null;
+    const rawAgentId = typeof objectParams.agentId === 'string'
+        ? objectParams.agentId
+        : typeof objectParams.agentName === 'string'
+            ? objectParams.agentName
+            : typeof objectParams.id === 'string'
+                ? objectParams.id
+                : 'defaults';
+    const agentId = typeof rawAgentId === 'string' && rawAgentId !== 'defaults'
+        ? sanitizeAgentId(rawAgentId)
+        : rawAgentId;
+    if (!updates) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Missing required parameter: updates (object with field paths and values)');
+    }
+    const configPath = path.join(context.openclawRoot, 'openclaw.json');
+    const config = await loadConfig(context.openclawRoot);
+    const target = resolveAgentTarget(config, agentId);
+    const changes = [];
+    for (const [fieldPath, value] of Object.entries(updates)) {
+        if (!ALLOWED_AGENT_UPDATES[fieldPath]) {
+            throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Field not allowed for update: ${fieldPath}. Allowed fields: ${Object.keys(ALLOWED_AGENT_UPDATES).join(', ')}`);
+        }
+        setNestedValue(target, fieldPath, value);
+        changes.push(`Updated ${fieldPath} to: ${JSON.stringify(value)}`);
+    }
+    await writeJsonFile(configPath, config);
+    return {
+        success: true,
+        configFile: configPath,
+        agentId,
+        changes,
+        updatedConfig: target
+    };
+};
+function setNestedValue(obj, pathExpression, value) {
+    const keys = pathExpression.split('.');
+    let current = obj;
+    for (let index = 0; index < keys.length - 1; index += 1) {
+        const key = keys[index];
+        if (!current[key] || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[keys[keys.length - 1]] = value;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function expectObject(value) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
+    }
+    return value;
+}
+function expectString(value, fieldName) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Field '${fieldName}' must be a non-empty string`);
+    }
+    return value.trim();
+}
+async function loadConfig(openclawRoot) {
+    return await readJsonFile(path.join(openclawRoot, 'openclaw.json'));
+}
+function ensureAgentList(config) {
+    if (!config.agents)
+        config.agents = {};
+    if (!Array.isArray(config.agents.list))
+        config.agents.list = [];
+    return config.agents.list;
+}
+function normalizeAgentList(config) {
+    const defaults = {
+        id: 'defaults',
+        name: 'defaults',
+        ...(config.agents?.defaults ?? {})
+    };
+    const named = Array.isArray(config.agents?.list) ? config.agents.list : [];
+    return [defaults, ...named];
+}
+function resolveAgentTarget(config, agentName) {
+    if (agentName === 'defaults') {
+        if (!config.agents)
+            config.agents = {};
+        if (!config.agents.defaults)
+            config.agents.defaults = {};
+        return config.agents.defaults;
+    }
+    const agents = ensureAgentList(config);
+    const found = findNamedAgent(agents, agentName);
+    if (!found) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Agent not found: ${agentName}`);
+    }
+    return found;
+}
+function findNamedAgent(agents, agentName) {
+    return agents.find((agent) => isMatchingAgent(agent, agentName)) ?? null;
+}
+function isMatchingAgent(agent, agentName) {
+    return agent.id === agentName || agent.name === agentName;
+}
+function sanitizeAgentId(value) {
+    return value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}

package/dist/src/admin/methods/index.js

@@ -0,0 +1,69 @@
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
+import { getAgents, getConfig } from './admin.ts';
+import { createAgent, deleteAgent, listAgents, updateAgent } from './agents-extended.ts';
+import { backupMemory, createMemoryBackupRecord, exportMemoryZip, getMemoryPresignedPost, getMemoryFile, importMemoryZip, listMemoryFiles } from './memory.ts';
+import { getModels } from './models.ts';
+import { updateModels } from './models-extended.ts';
+import { listSessions } from './sessions.ts';
+import { getSession, prepareMessage, attachSkill } from './sessions-extended.ts';
+import { installSkillFromNpm, listInstalledSkills } from './skills.ts';
+import { getInstalledSkill, uninstallSkill } from './skills-extended.ts';
+import { ping, restart, stop, doctorFix, logs } from './system.ts';
+import { getUsageBreakdown, getUsagePageSummary, getUsageSummary, getUsageTimeseries } from './usage.ts';
+const methods = new Map([
+    // System
+    ['system.ping', ping],
+    ['system.restart', restart],
+    ['system.stop', stop],
+    ['system.doctorFix', doctorFix],
+    ['system.logs', logs],
+    // Agents
+    ['agents.get', getAgents],
+    ['agents.list', listAgents],
+    ['agents.create', createAgent],
+    ['agents.delete', deleteAgent],
+    ['agents.update', updateAgent],
+    // Config
+    ['config.get', getConfig],
+    // Sessions
+    ['sessions.list', listSessions],
+    ['sessions.get', getSession],
+    ['sessions.prepareMessage', prepareMessage],
+    ['sessions.attachSkill', attachSkill],
+    // Models
+    ['models.get', getModels],
+    ['models.update', updateModels],
+    // Usage
+    ['usage.summary', getUsageSummary],
+    ['adminBridge.usagePageSummary', getUsagePageSummary],
+    ['adminBridge.usageTimeseries', getUsageTimeseries],
+    ['adminBridge.usageBreakdown', getUsageBreakdown],
+    ['admin.usagePageSummary', getUsagePageSummary],
+    ['admin.usageTimeseries', getUsageTimeseries],
+    ['admin.usageBreakdown', getUsageBreakdown],
+    // Skills
+    ['skills.listInstalled', listInstalledSkills],
+    ['skills.installFromNpm', installSkillFromNpm],
+    ['skills.getInstalled', getInstalledSkill],
+    ['skills.uninstall', uninstallSkill],
+    // Memory
+    ['memory.listFiles', listMemoryFiles],
+    ['memory.getFile', getMemoryFile],
+    ['memory.backup', backupMemory],
+    ['memory.exportZip', exportMemoryZip],
+    ['memory.getPresignedPost', getMemoryPresignedPost],
+    ['memory.createBackupRecord', createMemoryBackupRecord],
+    ['memory.importZip', importMemoryZip]
+]);
+export function getMethod(methodName) {
+    const handler = methods.get(methodName);
+    if (!handler) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.methodNotFound, 'Method not found', {
+            method: methodName
+        });
+    }
+    return handler;
+}
+export function listMethods() {
+    return [...methods.keys()];
+}

package/dist/src/admin/methods/memory.js

@@ -0,0 +1,360 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { copyIfExists, ensureDir, pathExists } from '../lib/fs.ts';
+import { ensureInside } from '../lib/paths.ts';
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
+const execFileAsync = promisify(execFile);
+const WORKSPACE_ROOT_FILES = [
+    'AGENTS.md',
+    'HEARTBEAT.md',
+    'IDENTITY.md',
+    'MEMORY.md',
+    'SoUL.md',
+    'TooLS.md',
+    'USER.md'
+];
+export const listMemoryFiles = async (_params, context) => {
+    const workspaceDir = path.join(context.openclawRoot, 'workspace');
+    const items = [];
+    for (const fileName of WORKSPACE_ROOT_FILES) {
+        const filePath = path.join(workspaceDir, fileName);
+        if (!(await pathExists(filePath))) {
+            continue;
+        }
+        const stat = await fs.stat(filePath);
+        items.push({
+            path: `workspace/${fileName}`,
+            size: stat.size,
+            updatedAt: stat.mtime.toISOString()
+        });
+    }
+    const rootConfigPath = path.join(context.openclawRoot, 'openclaw.json');
+    if (await pathExists(rootConfigPath)) {
+        const stat = await fs.stat(rootConfigPath);
+        items.push({
+            path: 'openclaw.json',
+            size: stat.size,
+            updatedAt: stat.mtime.toISOString()
+        });
+    }
+    const credentialsDir = path.join(context.openclawRoot, 'credentials');
+    if (await pathExists(credentialsDir)) {
+        const credentialEntries = await fs.readdir(credentialsDir, { withFileTypes: true });
+        for (const entry of credentialEntries) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const fullPath = path.join(credentialsDir, entry.name);
+            const stat = await fs.stat(fullPath);
+            items.push({
+                path: `credentials/${entry.name}`,
+                size: stat.size,
+                updatedAt: stat.mtime.toISOString()
+            });
+        }
+    }
+    return {
+        count: items.length,
+        items
+    };
+};
+export const getMemoryFile = async (params, context) => {
+    const objectParams = expectObject(params);
+    const filePath = expectString(objectParams.path, 'path');
+    const resolved = resolveMemoryPath(context.openclawRoot, filePath);
+    const content = await fs.readFile(resolved, 'utf8');
+    const stat = await fs.stat(resolved);
+    return {
+        path: filePath,
+        size: stat.size,
+        updatedAt: stat.mtime.toISOString(),
+        content
+    };
+};
+export const backupMemory = async (_params, context) => {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupRoot = path.join(context.projectRoot, 'backups', 'memory', stamp);
+    const manifest = {
+        createdAt: new Date().toISOString(),
+        files: []
+    };
+    await ensureDir(backupRoot);
+    if (await copyIfExists(path.join(context.openclawRoot, 'openclaw.json'), path.join(backupRoot, 'openclaw.json'))) {
+        manifest.files.push('openclaw.json');
+    }
+    for (const fileName of WORKSPACE_ROOT_FILES) {
+        const source = path.join(context.openclawRoot, 'workspace', fileName);
+        const dest = path.join(backupRoot, 'workspace', fileName);
+        if (await copyIfExists(source, dest)) {
+            manifest.files.push(path.relative(backupRoot, dest).replaceAll('\\', '/'));
+        }
+    }
+    const credentialsDir = path.join(context.openclawRoot, 'credentials');
+    if (await pathExists(credentialsDir)) {
+        const copiedCredentialFiles = await copyDirectoryTree(credentialsDir, path.join(backupRoot, 'credentials'));
+        manifest.files.push(...copiedCredentialFiles.map((file) => `credentials/${file}`));
+    }
+    await fs.writeFile(path.join(backupRoot, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+    return {
+        backupId: stamp,
+        backupPath: backupRoot,
+        files: manifest.files
+    };
+};
+export const exportMemoryZip = async (params, context) => {
+    const objectParams = (params ? expectObject(params) : {});
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const outputDirInput = objectParams.outputDir ?? path.join(context.projectRoot, 'exports', 'memory');
+    const outputDir = path.resolve(outputDirInput);
+    const zipFileName = sanitizeZipFileName(objectParams.zipFileName ?? `memory-backup-${stamp}.zip`);
+    await ensureDir(outputDir);
+    const snapshot = await backupMemory(undefined, context);
+    const snapshotRoot = expectString(snapshot.backupPath, 'backupPath');
+    const zipPath = path.join(outputDir, zipFileName);
+    await zipDirectory(snapshotRoot, zipPath);
+    const stat = await fs.stat(zipPath);
+    return {
+        ok: true,
+        zipPath,
+        size: stat.size,
+        snapshot
+    };
+};
+export const importMemoryZip = async (params, context) => {
+    const objectParams = expectObject(params);
+    const zipPath = path.resolve(expectString(objectParams.zipPath, 'zipPath'));
+    const createBackup = objectParams.createBackup !== false;
+    const includePaths = Array.isArray(objectParams.includePaths)
+        ? objectParams.includePaths.filter((item) => typeof item === 'string' && item.trim().length > 0)
+        : undefined;
+    if (!(await pathExists(zipPath))) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Zip file does not exist', { zipPath });
+    }
+    let backupResult = null;
+    if (createBackup) {
+        backupResult = await backupMemory(undefined, context);
+    }
+    const extractRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'openclaw-ts-memory-import-'));
+    try {
+        await unzipArchive(zipPath, extractRoot);
+        const importRoot = await resolveImportedRoot(extractRoot);
+        const restoredFiles = await restoreImportedMemory(importRoot, context.openclawRoot, includePaths);
+        return {
+            ok: true,
+            zipPath,
+            restoredFiles,
+            backup: backupResult
+        };
+    }
+    finally {
+        await fs.rm(extractRoot, { recursive: true, force: true });
+    }
+};
+export const getMemoryPresignedPost = async (params, context) => {
+    const objectParams = expectObject(params);
+    const body = isObject(objectParams.body) ? objectParams.body : null;
+    if (!body) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Missing required parameter: body');
+    }
+    const endpointConfig = await resolveApiCoreBotEndpoint(context.openclawRoot, objectParams.baseUrl, objectParams.authToken);
+    const response = await postJson(`${endpointConfig.baseUrl}/api-core-bot/front/s3/get-presigned-post`, body, endpointConfig.authToken);
+    return {
+        ok: true,
+        endpoint: '/api-core-bot/front/s3/get-presigned-post',
+        data: response
+    };
+};
+export const createMemoryBackupRecord = async (params, context) => {
+    const objectParams = expectObject(params);
+    const body = isObject(objectParams.body) ? objectParams.body : null;
+    if (!body) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Missing required parameter: body');
+    }
+    const endpointConfig = await resolveApiCoreBotEndpoint(context.openclawRoot, objectParams.baseUrl, objectParams.authToken);
+    const response = await postJson(`${endpointConfig.baseUrl}/api-core-bot/front/file/backup/create`, body, endpointConfig.authToken);
+    return {
+        ok: true,
+        endpoint: '/api-core-bot/front/file/backup/create',
+        data: response
+    };
+};
+function expectObject(value) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
+    }
+    return value;
+}
+function expectString(value, fieldName) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Field '${fieldName}' must be a non-empty string`);
+    }
+    return value;
+}
+function resolveMemoryPath(openclawRoot, relativePath) {
+    const workspaceDir = path.join(openclawRoot, 'workspace');
+    const allowedRoots = [
+        workspaceDir,
+        path.join(openclawRoot, 'credentials'),
+        openclawRoot
+    ];
+    const candidate = path.join(openclawRoot, relativePath);
+    for (const allowedRoot of allowedRoots) {
+        try {
+            return ensureInside(allowedRoot, candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Only workspace memory files are readable', { path: relativePath });
+}
+function sanitizeZipFileName(fileName) {
+    return fileName.endsWith('.zip') ? fileName : `${fileName}.zip`;
+}
+async function resolveApiCoreBotEndpoint(openclawRoot, overrideBaseUrl, overrideAuthToken) {
+    const config = await readJsonFile(path.join(openclawRoot, 'openclaw.json'));
+    const pluginConfig = config.plugins?.entries?.['rol-websocket-channel']?.config?.apiCoreBot ?? {};
+    const baseUrl = (overrideBaseUrl && overrideBaseUrl.trim()) || pluginConfig.baseUrl;
+    if (!baseUrl || !baseUrl.trim()) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'apiCoreBot.baseUrl is not configured');
+    }
+    const authToken = (overrideAuthToken && overrideAuthToken.trim()) || pluginConfig.authToken;
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        authToken
+    };
+}
+async function postJson(url, body, authToken) {
+    const headers = {
+        'Content-Type': 'application/json'
+    };
+    if (authToken && authToken.trim()) {
+        headers.Authorization = `Bearer ${authToken.trim()}`;
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+    });
+    const payload = await response.json().catch(async () => await response.text());
+    if (!response.ok) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `Request failed: ${response.status}`, {
+            url,
+            status: response.status,
+            payload
+        });
+    }
+    return payload;
+}
+async function zipDirectory(sourceDir, zipPath) {
+    await fs.rm(zipPath, { force: true });
+    if (process.platform === 'win32') {
+        await execFileAsync('powershell.exe', [
+            '-NoProfile',
+            '-Command',
+            `Compress-Archive -Path '${sourceDir}\\*' -DestinationPath '${zipPath}' -Force`
+        ]);
+        return;
+    }
+    await execFileAsync('zip', ['-r', zipPath, '.'], {
+        cwd: sourceDir
+    });
+}
+async function unzipArchive(zipPath, extractRoot) {
+    if (process.platform === 'win32') {
+        await execFileAsync('powershell.exe', [
+            '-NoProfile',
+            '-Command',
+            `Expand-Archive -Path '${zipPath}' -DestinationPath '${extractRoot}' -Force`
+        ]);
+        return;
+    }
+    await execFileAsync('unzip', ['-o', zipPath, '-d', extractRoot]);
+}
+async function resolveImportedRoot(extractRoot) {
+    const directWorkspace = path.join(extractRoot, 'workspace');
+    const directConfig = path.join(extractRoot, 'openclaw.json');
+    if ((await pathExists(directWorkspace)) || (await pathExists(directConfig))) {
+        return extractRoot;
+    }
+    const entries = await fs.readdir(extractRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = path.join(extractRoot, entry.name);
+        if ((await pathExists(path.join(candidate, 'workspace'))) || (await pathExists(path.join(candidate, 'openclaw.json')))) {
+            return candidate;
+        }
+    }
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Imported zip does not contain a valid memory snapshot');
+}
+async function restoreImportedMemory(importRoot, openclawRoot, includePaths) {
+    const restored = [];
+    const workspaceRoot = path.join(openclawRoot, 'workspace');
+    const importedCredentialsDir = path.join(importRoot, 'credentials');
+    if (shouldRestorePath('openclaw.json', includePaths) && await copyIfExists(path.join(importRoot, 'openclaw.json'), path.join(openclawRoot, 'openclaw.json'))) {
+        restored.push('openclaw.json');
+    }
+    for (const fileName of WORKSPACE_ROOT_FILES) {
+        const source = path.join(importRoot, 'workspace', fileName);
+        const dest = path.join(workspaceRoot, fileName);
+        const logicalPath = `workspace/${fileName}`;
+        if (shouldRestorePath(logicalPath, includePaths) && await copyIfExists(source, dest)) {
+            restored.push(`workspace/${fileName}`);
+        }
+    }
+    if ((shouldRestorePath('credentials/', includePaths) || hasNestedInclude('credentials/', includePaths)) && await pathExists(importedCredentialsDir)) {
+        const restoredCredentialFiles = await copyDirectoryTree(importedCredentialsDir, path.join(openclawRoot, 'credentials'), '', includePaths);
+        restored.push(...restoredCredentialFiles.map((file) => `credentials/${file}`));
+    }
+    return restored;
+}
+async function copyDirectoryTree(sourceDir, destDir, relativePrefix = '', includePaths) {
+    await ensureDir(destDir);
+    const copied = [];
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const source = path.join(sourceDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+        const logicalPath = `credentials/${relativePath.replaceAll('\\', '/')}`;
+        if (entry.isDirectory()) {
+            if (!hasNestedInclude(`${logicalPath}/`, includePaths) && !shouldRestorePath(`${logicalPath}/`, includePaths)) {
+                continue;
+            }
+            const nested = await copyDirectoryTree(source, dest, relativePath, includePaths);
+            copied.push(...nested);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (!shouldRestorePath(logicalPath, includePaths) && !shouldRestorePath('credentials/', includePaths)) {
+            continue;
+        }
+        await copyIfExists(source, dest);
+        copied.push(relativePath.replaceAll('\\', '/'));
+    }
+    return copied;
+}
+function shouldRestorePath(targetPath, includePaths) {
+    if (!includePaths || includePaths.length === 0) {
+        return true;
+    }
+    const normalizedTarget = normalizeLogicalPath(targetPath);
+    return includePaths.some((value) => normalizeLogicalPath(value) === normalizedTarget);
+}
+function hasNestedInclude(prefix, includePaths) {
+    if (!includePaths || includePaths.length === 0) {
+        return true;
+    }
+    const normalizedPrefix = normalizeLogicalPath(prefix).replace(/\/?$/, '/');
+    return includePaths.some((value) => normalizeLogicalPath(value).startsWith(normalizedPrefix));
+}
+function normalizeLogicalPath(value) {
+    return value.replaceAll('\\', '/').replace(/^\/+/, '').replace(/\/+$/, '');
+}