@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.5

package/services/agent-export.js

@@ -0,0 +1,767 @@
+/**
+ * Agent Export/Import Service
+ *
+ * Provides encrypted, portable agent archives for migrating agents between
+ * machines. Captures all database state (character, memories, entities,
+ * relationships, rooms, participants, worlds, tasks, and optionally logs)
+ * into a single password-encrypted binary file (.eliza-agent).
+ *
+ * Encryption: PBKDF2-SHA256 key derivation + AES-256-GCM
+ * Compression: gzip
+ *
+ * File format (binary):
+ *   ELIZA_AGENT_V1\n   (15 bytes magic header)
+ *   iterations           (4 bytes uint32 BE — PBKDF2 iteration count)
+ *   salt                 (32 bytes — PBKDF2 salt)
+ *   iv                   (12 bytes — AES-256-GCM nonce)
+ *   tag                  (16 bytes — AES-GCM authentication tag)
+ *   ciphertext           (variable — gzip-compressed JSON, encrypted)
+ */
+import * as crypto from "node:crypto";
+import { Readable } from "node:stream";
+import { createGunzip, gzipSync } from "node:zlib";
+import { logger } from "@elizaos/core";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAGIC_HEADER = "ELIZA_AGENT_V1\n";
+const MAGIC_BYTES = Buffer.from(MAGIC_HEADER, "utf-8"); // 15 bytes
+const PBKDF2_ITERATIONS = 600_000; // OWASP 2024 recommendation for SHA-256
+const MAX_PBKDF2_ITERATIONS = 1_200_000; // 2× the default — reject anything higher on import
+const SALT_LEN = 32;
+const IV_LEN = 12; // AES-256-GCM standard nonce
+const TAG_LEN = 16; // AES-GCM authentication tag
+const KEY_LEN = 32; // AES-256
+const MIN_PASSWORD_LENGTH = 4;
+const HEADER_SIZE = MAGIC_BYTES.length + 4 + SALT_LEN + IV_LEN + TAG_LEN; // 15 + 4 + 32 + 12 + 16 = 79
+const EXPORT_VERSION = 1;
+const MAX_IMPORT_DECOMPRESSED_BYTES = 16 * 1024 * 1024; // 16 MiB safety cap
+// Memory table names we need to export. The adapter's getMemories requires
+// a tableName parameter. These are the known built-in table names used by
+// elizaOS. We query each individually and merge the results.
+const MEMORY_TABLES = [
+    "messages",
+    "facts",
+    "documents",
+    "fragments",
+    "descriptions",
+    "character_modifications",
+    "custom",
+];
+// ---------------------------------------------------------------------------
+// Validation schema for the decrypted payload
+// ---------------------------------------------------------------------------
+function hasStringId(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.id === "string");
+}
+function typedIdRecordSchema() {
+    return z.custom((value) => hasStringId(value), {
+        message: "Expected object with string id",
+    });
+}
+const EntitySchema = typedIdRecordSchema();
+const MemorySchema = typedIdRecordSchema();
+const ComponentSchema = typedIdRecordSchema();
+const RoomSchema = typedIdRecordSchema();
+const RelationshipSchema = typedIdRecordSchema();
+const WorldSchema = typedIdRecordSchema();
+const TaskSchema = typedIdRecordSchema();
+// Logs don't need IDs (they're created fresh on import)
+const LogSchema = z.custom((value) => typeof value === "object" && value !== null && !Array.isArray(value), { message: "Expected log object" });
+const PayloadSchema = z.object({
+    version: z.number().int().min(1),
+    exportedAt: z.string(),
+    sourceAgentId: z.string(),
+    agent: z.custom((value) => typeof value === "object" && value !== null && !Array.isArray(value), { message: "Expected agent object" }),
+    characterConfig: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .transform((v) => v),
+    entities: z.array(EntitySchema),
+    memories: z.array(MemorySchema),
+    components: z.array(ComponentSchema),
+    rooms: z.array(RoomSchema),
+    participants: z.array(z.object({
+        entityId: z.string(),
+        roomId: z.string(),
+        userState: z.string().nullable(),
+    })),
+    relationships: z.array(RelationshipSchema),
+    worlds: z.array(WorldSchema),
+    tasks: z.array(TaskSchema),
+    logs: z.array(LogSchema),
+});
+function toAgentExportPayload(payload) {
+    return {
+        version: payload.version,
+        exportedAt: payload.exportedAt,
+        sourceAgentId: payload.sourceAgentId,
+        agent: payload.agent,
+        characterConfig: payload.characterConfig,
+        entities: payload.entities,
+        memories: payload.memories,
+        components: payload.components,
+        rooms: payload.rooms,
+        participants: payload.participants.map((participant) => ({
+            entityId: participant.entityId,
+            roomId: participant.roomId,
+            userState: participant.userState ?? null,
+        })),
+        relationships: payload.relationships,
+        worlds: payload.worlds,
+        tasks: payload.tasks,
+        logs: payload.logs,
+    };
+}
+// ---------------------------------------------------------------------------
+// Crypto helpers
+// ---------------------------------------------------------------------------
+function deriveKey(password, salt, iterations) {
+    return new Promise((resolve, reject) => {
+        crypto.pbkdf2(password, salt, iterations, KEY_LEN, "sha256", (err, key) => {
+            if (err)
+                reject(err);
+            else
+                resolve(key);
+        });
+    });
+}
+async function encrypt(plaintext, password) {
+    const salt = crypto.randomBytes(SALT_LEN);
+    const iv = crypto.randomBytes(IV_LEN);
+    const key = await deriveKey(password, salt, PBKDF2_ITERATIONS);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { salt, iv, tag, ciphertext, iterations: PBKDF2_ITERATIONS };
+}
+async function decrypt(ciphertext, password, salt, iv, tag, iterations) {
+    const key = await deriveKey(password, salt, iterations);
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return plaintext;
+}
+// ---------------------------------------------------------------------------
+// Binary file packing / unpacking
+// ---------------------------------------------------------------------------
+function packFile(encrypted) {
+    const iterBuf = Buffer.alloc(4);
+    iterBuf.writeUInt32BE(encrypted.iterations, 0);
+    return Buffer.concat([
+        MAGIC_BYTES,
+        iterBuf,
+        encrypted.salt,
+        encrypted.iv,
+        encrypted.tag,
+        encrypted.ciphertext,
+    ]);
+}
+function unpackFile(fileBuffer) {
+    if (fileBuffer.length < HEADER_SIZE) {
+        throw new AgentExportError("File is too small to be a valid .eliza-agent export.");
+    }
+    const magic = fileBuffer.subarray(0, MAGIC_BYTES.length);
+    if (!magic.equals(MAGIC_BYTES)) {
+        throw new AgentExportError("Invalid file format — this does not appear to be an .eliza-agent export file.");
+    }
+    let offset = MAGIC_BYTES.length;
+    const iterations = fileBuffer.readUInt32BE(offset);
+    offset += 4;
+    if (iterations < 1 || iterations > MAX_PBKDF2_ITERATIONS) {
+        throw new AgentExportError(`Invalid PBKDF2 iteration count (${iterations}). ` +
+            `Expected between 1 and ${MAX_PBKDF2_ITERATIONS.toLocaleString()}.`);
+    }
+    const salt = fileBuffer.subarray(offset, offset + SALT_LEN);
+    offset += SALT_LEN;
+    const iv = fileBuffer.subarray(offset, offset + IV_LEN);
+    offset += IV_LEN;
+    const tag = fileBuffer.subarray(offset, offset + TAG_LEN);
+    offset += TAG_LEN;
+    const ciphertext = fileBuffer.subarray(offset);
+    if (ciphertext.length === 0) {
+        throw new AgentExportError("Export file contains no encrypted data.");
+    }
+    return { salt, iv, tag, ciphertext, iterations };
+}
+// ---------------------------------------------------------------------------
+// Custom error class
+// ---------------------------------------------------------------------------
+export class AgentExportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentExportError";
+    }
+}
+async function gunzipWithSizeLimit(compressed, maxBytes = MAX_IMPORT_DECOMPRESSED_BYTES) {
+    const source = Readable.from([compressed]);
+    const gunzip = createGunzip();
+    const chunks = [];
+    let total = 0;
+    source.pipe(gunzip);
+    for await (const chunk of gunzip) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            source.destroy();
+            gunzip.destroy();
+            throw new AgentExportError(`Decompressed payload exceeds import limit (${maxBytes} bytes).`);
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks, total);
+}
+// ---------------------------------------------------------------------------
+// Data extraction
+// ---------------------------------------------------------------------------
+/** Read agentId from a Task, accounting for proto vs DB naming. */
+function taskAgentId(t) {
+    const rec = t;
+    return (rec.agentId ?? rec.agent_id);
+}
+async function extractAgentData(runtime, options) {
+    const db = runtime.adapter;
+    const agentId = runtime.agentId;
+    logger.info(`[agent-export] Extracting data for agent ${agentId}`);
+    // 1. Agent record
+    const agents = await db.getAgentsByIds([agentId]);
+    const agent = agents[0];
+    if (!agent) {
+        throw new AgentExportError(`Agent ${agentId} not found in database.`);
+    }
+    // 2. Worlds owned by this agent
+    const allWorlds = await db.getAllWorlds();
+    const agentWorlds = allWorlds.filter((w) => w.agentId === agentId);
+    logger.info(`[agent-export] Found ${agentWorlds.length} worlds`);
+    // 3. Rooms — gather from worlds and from participant list
+    const roomMap = new Map();
+    for (const world of agentWorlds) {
+        if (!world.id)
+            continue;
+        const worldRooms = await db.getRoomsByWorlds([world.id]);
+        for (const room of worldRooms) {
+            if (room.id)
+                roomMap.set(room.id, room);
+        }
+    }
+    // Also get rooms the agent participates in directly
+    const participantRoomIds = await db.getRoomsForParticipants([agentId]);
+    if (participantRoomIds.length > 0) {
+        const participantRooms = await db.getRoomsByIds(participantRoomIds);
+        if (participantRooms) {
+            for (const room of participantRooms) {
+                if (room.id)
+                    roomMap.set(room.id, room);
+            }
+        }
+    }
+    const rooms = Array.from(roomMap.values());
+    logger.info(`[agent-export] Found ${rooms.length} rooms`);
+    // 4. Entities and participants for each room
+    const entityMap = new Map();
+    const participantRecords = [];
+    for (const room of rooms) {
+        if (!room.id)
+            continue;
+        const entitiesResult = await db.getEntitiesForRooms([room.id], true);
+        const roomEntities = entitiesResult[0]?.entities ?? [];
+        for (const entity of roomEntities) {
+            if (entity.id)
+                entityMap.set(entity.id, entity);
+        }
+        const participantsResult = await db.getParticipantsForRooms([room.id]);
+        const participantIds = participantsResult[0]?.entityIds ?? [];
+        for (const entityId of participantIds) {
+            const userStates = await db.getParticipantUserStates([
+                { roomId: room.id, entityId },
+            ]);
+            const userState = userStates[0] ?? null;
+            participantRecords.push({
+                entityId,
+                roomId: room.id,
+                userState,
+            });
+        }
+    }
+    const entities = Array.from(entityMap.values());
+    logger.info(`[agent-export] Found ${entities.length} entities, ${participantRecords.length} participant records`);
+    // 5. Components for all entities (deduplicated by ID)
+    const componentIds = new Set();
+    const allComponents = [];
+    const addComponent = (c) => {
+        if (c.id && !componentIds.has(c.id)) {
+            componentIds.add(c.id);
+            allComponents.push(c);
+        }
+    };
+    for (const entity of entities) {
+        if (!entity.id)
+            continue;
+        for (const c of await db.getComponentsForEntities([entity.id]))
+            addComponent(c);
+        for (const world of agentWorlds) {
+            if (!world.id)
+                continue;
+            for (const c of await db.getComponentsForEntities([entity.id], world.id))
+                addComponent(c);
+        }
+    }
+    logger.info(`[agent-export] Found ${allComponents.length} components`);
+    // 6. Memories — query all known table names
+    const allMemories = [];
+    const memoryIdSet = new Set();
+    for (const tableName of MEMORY_TABLES) {
+        const memories = await db.getMemories({
+            agentId,
+            tableName,
+            limit: Number.MAX_SAFE_INTEGER,
+        });
+        for (const mem of memories) {
+            if (mem.id && !memoryIdSet.has(mem.id)) {
+                memoryIdSet.add(mem.id);
+                // Strip embeddings to reduce file size — they can be regenerated
+                allMemories.push({ ...mem, embedding: undefined });
+            }
+        }
+    }
+    // Also try querying memories by world
+    for (const world of agentWorlds) {
+        if (!world.id)
+            continue;
+        for (const tableName of MEMORY_TABLES) {
+            const worldMemories = await db.getMemoriesByWorldId({
+                worldIds: [world.id],
+                limit: Number.MAX_SAFE_INTEGER,
+                tableName,
+            });
+            for (const mem of worldMemories) {
+                if (mem.id && !memoryIdSet.has(mem.id)) {
+                    memoryIdSet.add(mem.id);
+                    allMemories.push({ ...mem, embedding: undefined });
+                }
+            }
+        }
+    }
+    logger.info(`[agent-export] Found ${allMemories.length} memories`);
+    // 7. Relationships
+    const relationships = await db.getRelationships({ entityIds: [agentId] });
+    logger.info(`[agent-export] Found ${relationships.length} relationships`);
+    // 8. Tasks
+    // The Task proto type does not declare agentId, but the DB schema stores
+    // agent_id. Filter using a dynamic property access to handle both shapes.
+    const allTasks = await db.getTasks({ agentIds: [agentId] });
+    const agentTasks = allTasks.filter((t) => taskAgentId(t) === agentId);
+    logger.info(`[agent-export] Found ${agentTasks.length} tasks`);
+    // 9. Logs (optional)
+    let logs = [];
+    if (options.includeLogs) {
+        logs = await db.getLogs({ limit: Number.MAX_SAFE_INTEGER });
+        logger.info(`[agent-export] Found ${logs.length} logs`);
+    }
+    // 10. Runtime character config — captures fields from buildCharacterFromConfig
+    // that may not be persisted in the DB agent record (style, topics, adjectives,
+    // messageExamples, postExamples, knowledge sources, etc.)
+    let characterConfig;
+    if (runtime.character) {
+        // Clone and strip secrets/sensitive fields
+        const { secrets: _secrets, ...safeChar } = runtime.character;
+        characterConfig = safeChar;
+        logger.info(`[agent-export] Captured runtime character config (${Object.keys(safeChar).length} fields)`);
+    }
+    return {
+        version: EXPORT_VERSION,
+        exportedAt: new Date().toISOString(),
+        sourceAgentId: agentId,
+        agent,
+        characterConfig,
+        entities,
+        memories: allMemories,
+        components: allComponents,
+        rooms,
+        participants: participantRecords,
+        relationships,
+        worlds: agentWorlds,
+        tasks: agentTasks,
+        logs,
+    };
+}
+// ---------------------------------------------------------------------------
+// ID remapping for import
+// ---------------------------------------------------------------------------
+function createIdRemapper(fixed) {
+    const map = new Map(fixed);
+    return (oldId) => {
+        if (!oldId)
+            return oldId;
+        const existing = map.get(oldId);
+        if (existing)
+            return existing;
+        const newId = crypto.randomUUID();
+        map.set(oldId, newId);
+        return newId;
+    };
+}
+// ---------------------------------------------------------------------------
+// Data restoration
+// ---------------------------------------------------------------------------
+async function restoreAgentData(runtime, payload) {
+    const db = runtime.adapter;
+    const newAgentId = crypto.randomUUID();
+    const remap = createIdRemapper(new Map([[payload.sourceAgentId, newAgentId]]));
+    logger.info(`[agent-import] Importing agent "${payload.agent.name}" as ${newAgentId}`);
+    // 1. Create agent — merge characterConfig (if present) as a base so
+    //    style/topics/adjectives/messageExamples survive the round-trip even
+    //    if the DB agent record didn't persist them.
+    // Spread and explicitly exclude secrets. characterConfig is already typed as
+    // Omit<Character, "secrets">, but strip the field defensively for runtime safety.
+    const { secrets: _secrets, ...charBase } = payload.characterConfig
+        ? { ...payload.characterConfig }
+        : {};
+    const agentData = { ...charBase, ...payload.agent };
+    agentData.id = newAgentId;
+    agentData.enabled = true;
+    agentData.createdAt = Date.now();
+    agentData.updatedAt = Date.now();
+    const agentCreatedIds = await db.createAgents([agentData]);
+    if (!agentCreatedIds || agentCreatedIds.length === 0) {
+        throw new AgentExportError("Failed to create agent in database.");
+    }
+    logger.info(`[agent-import] Created agent record${payload.characterConfig ? " (merged with characterConfig)" : ""}`);
+    // 2. Create worlds
+    let worldsImported = 0;
+    for (const world of payload.worlds) {
+        const newWorld = {
+            ...world,
+            id: remap(world.id),
+            agentId: newAgentId,
+        };
+        await db.createWorlds([newWorld]);
+        worldsImported++;
+    }
+    logger.info(`[agent-import] Imported ${worldsImported} worlds`);
+    // 3. Create rooms
+    let roomsImported = 0;
+    const roomBatch = [];
+    for (const room of payload.rooms) {
+        const newRoom = {
+            ...room,
+            id: remap(room.id),
+            agentId: newAgentId,
+            worldId: room.worldId ? remap(room.worldId) : undefined,
+        };
+        roomBatch.push(newRoom);
+    }
+    if (roomBatch.length > 0) {
+        await db.createRooms(roomBatch);
+        roomsImported = roomBatch.length;
+    }
+    logger.info(`[agent-import] Imported ${roomsImported} rooms`);
+    // 4. Create entities
+    let entitiesImported = 0;
+    const entityBatch = [];
+    for (const entity of payload.entities) {
+        const newEntity = {
+            ...entity,
+            id: remap(entity.id ?? ""),
+            agentId: newAgentId,
+            // Strip components — we'll recreate them separately
+            components: undefined,
+        };
+        entityBatch.push(newEntity);
+    }
+    if (entityBatch.length > 0) {
+        await db.createEntities(entityBatch);
+        entitiesImported = entityBatch.length;
+    }
+    logger.info(`[agent-import] Imported ${entitiesImported} entities`);
+    // 5. Add participants to rooms
+    let participantsImported = 0;
+    for (const p of payload.participants) {
+        const newEntityId = remap(p.entityId);
+        const newRoomId = remap(p.roomId);
+        await db.createRoomParticipants([newEntityId], newRoomId);
+        if (p.userState === "FOLLOWED" || p.userState === "MUTED") {
+            await db.updateParticipantUserStates([
+                { roomId: newRoomId, entityId: newEntityId, state: p.userState },
+            ]);
+        }
+        participantsImported++;
+    }
+    logger.info(`[agent-import] Imported ${participantsImported} participants`);
+    // 6. Create components
+    let componentsImported = 0;
+    for (const comp of payload.components) {
+        const newComp = {
+            ...comp,
+            id: remap(comp.id),
+            ...(comp.entityId ? { entityId: remap(comp.entityId) } : {}),
+            ...(comp.agentId ? { agentId: newAgentId } : {}),
+            ...(comp.roomId ? { roomId: remap(comp.roomId) } : {}),
+            ...(comp.worldId ? { worldId: remap(comp.worldId) } : {}),
+            ...(comp.sourceEntityId
+                ? { sourceEntityId: remap(comp.sourceEntityId) }
+                : {}),
+        };
+        await db.createComponents([newComp]);
+        componentsImported++;
+    }
+    logger.info(`[agent-import] Imported ${componentsImported} components`);
+    // 7. Create memories
+    let memoriesImported = 0;
+    for (const mem of payload.memories) {
+        const tableName = resolveMemoryTableName(mem);
+        const newMem = {
+            ...mem,
+            id: remap(mem.id ?? ""),
+            agentId: newAgentId,
+            ...(mem.entityId ? { entityId: remap(mem.entityId) } : {}),
+            ...(mem.roomId ? { roomId: remap(mem.roomId) } : {}),
+            ...(mem.worldId ? { worldId: remap(mem.worldId) } : {}),
+            // Embeddings are excluded — they will be regenerated
+            embedding: undefined,
+        };
+        await db.createMemories([{ memory: newMem, tableName }]);
+        memoriesImported++;
+    }
+    logger.info(`[agent-import] Imported ${memoriesImported} memories`);
+    // 8. Create relationships
+    let relationshipsImported = 0;
+    for (const rel of payload.relationships) {
+        await db.createRelationships([
+            {
+                sourceEntityId: remap(rel.sourceEntityId),
+                targetEntityId: remap(rel.targetEntityId),
+                tags: rel.tags,
+                metadata: rel.metadata,
+            },
+        ]);
+        relationshipsImported++;
+    }
+    logger.info(`[agent-import] Imported ${relationshipsImported} relationships`);
+    // 9. Create tasks
+    // The Task type doesn't declare agentId but the DB schema stores it.
+    // We spread the original task and add agentId as a dynamic property
+    // that the database adapter will persist.
+    let tasksImported = 0;
+    for (const task of payload.tasks) {
+        const newTask = {
+            ...task,
+            id: remap(task.id ?? ""),
+            agentId: newAgentId,
+            roomId: task.roomId ? remap(task.roomId) : undefined,
+            worldId: task.worldId ? remap(task.worldId) : undefined,
+            entityId: task.entityId ? remap(task.entityId) : undefined,
+        };
+        await db.createTasks([newTask]);
+        tasksImported++;
+    }
+    logger.info(`[agent-import] Imported ${tasksImported} tasks`);
+    // 10. Create logs
+    let logsImported = 0;
+    for (const logEntry of payload.logs) {
+        await db.createLogs([
+            {
+                body: logEntry.body,
+                entityId: (logEntry.entityId
+                    ? remap(logEntry.entityId)
+                    : logEntry.entityId),
+                roomId: logEntry.roomId
+                    ? remap(logEntry.roomId)
+                    : newAgentId,
+                type: logEntry.type,
+            },
+        ]);
+        logsImported++;
+    }
+    logger.info(`[agent-import] Imported ${logsImported} logs`);
+    return {
+        success: true,
+        agentId: newAgentId,
+        agentName: payload.agent.name ?? "Unknown",
+        counts: {
+            memories: memoriesImported,
+            entities: entitiesImported,
+            components: componentsImported,
+            rooms: roomsImported,
+            participants: participantsImported,
+            relationships: relationshipsImported,
+            worlds: worldsImported,
+            tasks: tasksImported,
+            logs: logsImported,
+        },
+    };
+}
+/**
+ * Resolve the memory table name from a memory record's metadata.
+ * The elizaOS adapter requires a tableName for createMemory.
+ */
+function resolveMemoryTableName(mem) {
+    const metaType = mem.metadata?.type;
+    if (metaType === "message")
+        return "messages";
+    if (metaType === "document")
+        return "documents";
+    if (metaType === "fragment")
+        return "fragments";
+    if (metaType === "description")
+        return "descriptions";
+    if (metaType === "custom")
+        return "custom";
+    // Fallback: use the "type" field on the memory itself (elizaOS stores it
+    // as a top-level field in the DB row, which the proto Memory type inherits).
+    const memType = mem.type;
+    if (typeof memType === "string" && memType.length > 0)
+        return memType;
+    return "messages";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Export the current agent's full state as a password-encrypted binary file.
+ *
+ * @param runtime - The running AgentRuntime with an active database adapter
+ * @param password - User-provided password for encryption
+ * @param options - Export options (e.g., whether to include logs)
+ * @returns A Buffer containing the encrypted .eliza-agent file
+ */
+export async function exportAgent(runtime, password, options = {}) {
+    if (!password || password.length < MIN_PASSWORD_LENGTH) {
+        throw new AgentExportError(`A password of at least ${MIN_PASSWORD_LENGTH} characters is required to encrypt the export.`);
+    }
+    if (!runtime.adapter) {
+        throw new AgentExportError("No database adapter available on the runtime.");
+    }
+    const payload = await extractAgentData(runtime, {
+        includeLogs: options.includeLogs ?? false,
+    });
+    const jsonString = JSON.stringify(payload);
+    const compressed = gzipSync(Buffer.from(jsonString, "utf-8"));
+    logger.info(`[agent-export] Payload: ${jsonString.length} bytes JSON → ${compressed.length} bytes compressed`);
+    const encrypted = await encrypt(compressed, password);
+    const fileBuffer = packFile(encrypted);
+    logger.info(`[agent-export] Final file size: ${fileBuffer.length} bytes`);
+    return fileBuffer;
+}
+/**
+ * Import an agent from a password-encrypted .eliza-agent file.
+ *
+ * @param runtime - An AgentRuntime with an active database adapter (the agent
+ *                  will be created in this database, not overwriting the current agent)
+ * @param fileBuffer - The raw bytes of the .eliza-agent file
+ * @param password - The password used when the file was exported
+ * @returns An ImportResult describing what was imported
+ */
+export async function importAgent(runtime, fileBuffer, password) {
+    if (!password || password.length < MIN_PASSWORD_LENGTH) {
+        throw new AgentExportError(`A password of at least ${MIN_PASSWORD_LENGTH} characters is required to decrypt the import.`);
+    }
+    if (!runtime.adapter) {
+        throw new AgentExportError("No database adapter available on the runtime.");
+    }
+    // 1. Unpack file structure
+    const { salt, iv, tag, ciphertext, iterations } = unpackFile(fileBuffer);
+    // 2. Decrypt
+    let compressed;
+    try {
+        compressed = await decrypt(ciphertext, password, salt, iv, tag, iterations);
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            (err.message.includes("Unsupported state") ||
+                err.message.includes("unable to authenticate") ||
+                err.message.includes("auth"))) {
+            throw new AgentExportError("Incorrect password — decryption failed. Please check your password and try again.");
+        }
+        throw new AgentExportError(`Decryption failed: ${String(err)}`);
+    }
+    // 3. Decompress
+    let jsonString;
+    try {
+        const decompressed = await gunzipWithSizeLimit(compressed);
+        jsonString = decompressed.toString("utf-8");
+    }
+    catch (err) {
+        if (err instanceof AgentExportError)
+            throw err;
+        throw new AgentExportError(`Decompression failed — the file may be corrupt: ${String(err)}`);
+    }
+    // 4. Parse JSON
+    let rawPayload;
+    try {
+        rawPayload = JSON.parse(jsonString);
+    }
+    catch (err) {
+        throw new AgentExportError(`JSON parse failed — the export data is malformed: ${String(err)}`);
+    }
+    // 5. Validate schema
+    const parseResult = PayloadSchema.safeParse(rawPayload);
+    if (!parseResult.success) {
+        const issues = parseResult.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        throw new AgentExportError(`Export file schema validation failed: ${issues}`);
+    }
+    const payload = toAgentExportPayload(parseResult.data);
+    if (payload.version > EXPORT_VERSION) {
+        throw new AgentExportError(`Unsupported export version ${payload.version}. This build supports up to version ${EXPORT_VERSION}. ` +
+            "Please update your software to import this file.");
+    }
+    logger.info(`[agent-import] Importing agent "${payload.agent.name}" exported at ${payload.exportedAt}`);
+    // 6. Restore data
+    return restoreAgentData(runtime, payload);
+}
+/**
+ * Estimate the size of an agent export without actually creating it.
+ * Useful for showing the user how large the export will be.
+ */
+export async function estimateExportSize(runtime) {
+    const db = runtime.adapter;
+    const agentId = runtime.agentId;
+    let memoriesCount = 0;
+    for (const tableName of MEMORY_TABLES) {
+        const mems = await db.getMemories({
+            agentId,
+            tableName,
+            limit: Number.MAX_SAFE_INTEGER,
+        });
+        memoriesCount += mems.length;
+    }
+    const allWorlds = await db.getAllWorlds();
+    const agentWorlds = allWorlds.filter((w) => w.agentId === agentId);
+    const roomIds = await db.getRoomsForParticipants([agentId]);
+    const entityIdSet = new Set();
+    if (roomIds.length > 0) {
+        const entitiesResult = await db.getEntitiesForRooms(roomIds, true);
+        for (const result of entitiesResult) {
+            for (const e of result.entities) {
+                if (e.id)
+                    entityIdSet.add(e.id);
+            }
+        }
+    }
+    const tasks = await db.getTasks({ agentIds: [agentId] });
+    const agentTasks = tasks.filter((t) => taskAgentId(t) === agentId);
+    // Rough estimate: ~500 bytes per memory, ~200 bytes per entity, ~300 per room
+    const estimatedBytes = memoriesCount * 500 +
+        entityIdSet.size * 200 +
+        roomIds.length * 300 +
+        agentWorlds.length * 200 +
+        agentTasks.length * 400 +
+        2000; // base overhead
+    return {
+        estimatedBytes,
+        memoriesCount,
+        entitiesCount: entityIdSet.size,
+        roomsCount: roomIds.length,
+        worldsCount: agentWorlds.length,
+        tasksCount: agentTasks.length,
+    };
+}