@mono-agent/agent-app 0.19.0 → 0.20.0

package/dist/memory-command.js

@@ -67,6 +67,14 @@ export async function runMemoryCommand(input) {
             writeMemoryForgetFailure(input.json, input.positionals[1] ?? "unknown", "forget_usage");
             return 2;
         }
+        if (input.positionals[0] === "export") {
+            writeMemoryBundleFailure(input.json, "export", "export_usage");
+            return 2;
+        }
+        if (input.positionals[0] === "import") {
+            writeMemoryBundleFailure(input.json, memoryImportOperationLabel(input.positionals[1]), "import_usage");
+            return 2;
+        }
         process.stderr.write(ui.errorLine(usageError));
         return 2;
     }
@@ -90,6 +98,10 @@ export async function runMemoryCommand(input) {
             writeMemoryForgetFailure(input.json, rest[0] ?? "unknown", "forget_requires_bujo");
             return 1;
         }
+        if (subcommand === "export" || subcommand === "import") {
+            writeMemoryBundleFailure(input.json, subcommand === "export" ? "export" : memoryImportOperationLabel(rest[0]), subcommand === "export" ? "export_requires_bujo" : "import_requires_bujo");
+            return 1;
+        }
         writeNoMemory(context.configPath, input.json);
         return 0;
     }
@@ -134,9 +146,13 @@ export async function runMemoryCommand(input) {
             return await runReplayAdoption(context, input.json);
         case "forget":
             return await runMemoryForget(context, rest, input);
+        case "export":
+            return await runMemoryBundleExport(context, input);
+        case "import":
+            return await runMemoryBundleImport(context, rest, input);
         default:
             process.stderr.write(ui.errorLine(`Unknown memory subcommand \`${subcommand}\`.`));
-            process.stderr.write(ui.hint("Expected stats, today, show <date>, search <query>, top, audit, inspect [id], retry [id], resolve <id> <reason>, rebuild, rollback, adopt-replay, or forget prepare|apply|restore."));
+            process.stderr.write(ui.hint("Expected stats, today, show <date>, search <query>, top, audit, inspect [id], retry [id], resolve <id> <reason>, rebuild, rollback, adopt-replay, forget prepare|apply|restore, export, or import prepare|apply|restore."));
             return 2;
     }
 }
@@ -203,10 +219,503 @@ function memoryCommandUsageError(input) {
                 ? undefined
                 : "Usage: mono-agent memory forget restore --backup <dir>.";
         }
+        case "export":
+            if (rest.length !== 0 || input.bundlePath === undefined || input.planPath !== undefined
+                || input.backupPath !== undefined || input.onConflict !== undefined
+                || input.entityConflict !== undefined || input.acceptDerivedAssociationDrift === true) {
+                return "Usage: mono-agent memory export --bundle <dir> [--include-extras] [--allow-pending].";
+            }
+            return undefined;
+        case "import": {
+            const operation = rest[0];
+            if (rest.length !== 1 || (operation !== "prepare" && operation !== "apply" && operation !== "restore")) {
+                return "Usage: mono-agent memory import prepare|apply|restore with the required operation flags.";
+            }
+            if (input.includeExtras === true || input.allowPending === true) {
+                return "--include-extras and --allow-pending are only supported for `mono-agent memory export`.";
+            }
+            if (operation === "prepare") {
+                return input.bundlePath !== undefined && input.planPath !== undefined && input.backupPath === undefined
+                    ? undefined
+                    : "Usage: mono-agent memory import prepare --bundle <dir> --plan <file> "
+                        + "[--on-conflict fail|skip] [--entity-conflict target|source] [--accept-derived-association-drift].";
+            }
+            if (operation === "apply") {
+                return input.planPath !== undefined && input.bundlePath === undefined && input.backupPath === undefined
+                    && input.onConflict === undefined && input.entityConflict === undefined
+                    && input.acceptDerivedAssociationDrift !== true
+                    ? undefined
+                    : "Usage: mono-agent memory import apply --plan <file>.";
+            }
+            return input.backupPath !== undefined && input.bundlePath === undefined && input.planPath === undefined
+                && input.onConflict === undefined && input.entityConflict === undefined
+                && input.acceptDerivedAssociationDrift !== true
+                ? undefined
+                : "Usage: mono-agent memory import restore --backup <dir>.";
+        }
         default:
             return undefined;
     }
 }
+const MEMORY_BUNDLE_CLI_SCHEMA_VERSION = 1;
+const MAX_IMPORT_PLAN_BYTES = 64 * 1024;
+const MAX_MEMORY_BUNDLE_CAUSE_DEPTH = 8;
+/**
+ * Frozen operator-facing messages. Package errors are never interpolated:
+ * they can carry memory text, memory ids, entity names, and absolute paths.
+ */
+const MEMORY_BUNDLE_FAILURE_MESSAGES = Object.freeze({
+    export_requires_bujo: "Memory export requires a configured built-in BuJo store with embeddings.",
+    export_usage: "Memory export arguments are invalid.",
+    export_config_invalid: "Memory export requires a valid private configuration.",
+    export_destination_invalid: "The bundle destination must be a new directory outside the memory root.",
+    export_pending_work: "The memory store has unreplayed durable work; let it drain or re-run with --allow-pending.",
+    export_source_changed: "The memory store kept changing during export; retry with the agent idle.",
+    export_source_invalid: "The canonical memory source is invalid; repair it before exporting.",
+    export_failed: "Memory export failed; no bundle was published.",
+    import_requires_bujo: "Memory import requires a configured built-in BuJo store with embeddings.",
+    import_usage: "Memory import arguments are invalid.",
+    import_config_invalid: "Memory import requires a valid private configuration.",
+    import_bundle_invalid: "The bundle failed verification; the memory store was not changed.",
+    import_derived_drift: "Importing these entities would remove derived associations from existing memories; re-run with --accept-derived-association-drift to proceed.",
+    import_conflict: "Incoming memory ids already exist with different content; re-run with --on-conflict skip to keep this store's versions.",
+    import_prepare_failed: "Import-plan preparation failed without changing the memory store.",
+    import_pending_work: "The memory store has unreplayed durable work; let it drain, stop the agent, and prepare a fresh plan.",
+    import_stale_plan: "The import plan no longer matches this memory store or bundle; prepare a fresh plan.",
+    import_apply_failed: "Import application failed before a recoverable backup was available.",
+    import_apply_failed_recovered: "Import application failed and the complete pre-import backup was restored.",
+    import_apply_recovery_failed: "Import application failed and automatic recovery could not be verified; keep the agent stopped and restore the reported backup manually.",
+    import_restore_failed: "Backup restore was refused or failed; the current memory store was not intentionally overwritten.",
+});
+class MemoryBundleOperationError extends Error {
+    code;
+    recovered;
+    backupPath;
+    constructor(code, recovered = false, backupPath) {
+        super(code);
+        this.code = code;
+        this.recovered = recovered;
+        this.backupPath = backupPath;
+        this.name = "MemoryBundleOperationError";
+    }
+}
+/** Shared precondition: the built-in BuJo backend with a usable embedding provider. */
+function bundleMemorySettings(context) {
+    const memory = context.config.memory;
+    if (memory === undefined || (memory.backend ?? "bujo") === "supermemory"
+        || memory.mode !== "bujo" || memory.embeddings === undefined) {
+        return undefined;
+    }
+    return memory;
+}
+async function runMemoryBundleExport(context, input) {
+    const memory = bundleMemorySettings(context);
+    if (memory === undefined) {
+        writeMemoryBundleFailure(input.json, "export", "export_requires_bujo");
+        return 1;
+    }
+    let bujo;
+    try {
+        bujo = await loadBujoModule();
+    }
+    catch {
+        writeMemoryBundleFailure(input.json, "export", "export_failed");
+        return 1;
+    }
+    const { MemoryBundleExportError } = bujo;
+    try {
+        const root = resolve(context.cwd, memory.path);
+        const bundlePath = await canonicalProspectivePath(resolve(context.cwd, input.bundlePath));
+        const result = await bujo.exportMemoryBundle({
+            root,
+            bundlePath,
+            scope: input.includeExtras === true ? "canonical+extras" : "canonical",
+            ...(input.allowPending === true ? { allowPending: true } : {}),
+            ...(memory.embeddings?.model === undefined
+                ? {}
+                : { embeddingModel: `${memory.embeddings.provider}:${memory.embeddings.model}` }),
+            dimension: memory.embeddings?.dim ?? 768,
+        });
+        const published = {
+            schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+            operation: "memory-export",
+            status: "exported",
+            bundlePath: result.bundlePath,
+            scope: result.scope,
+            sourceFingerprint: result.sourceFingerprint,
+            treeFingerprint: result.treeFingerprint,
+            counts: result.counts,
+            ...(result.pendingWork ? { pendingWork: true } : {}),
+        };
+        write(input.json, published, () => renderMemoryBundleExport(published));
+        return 0;
+    }
+    catch (error) {
+        writeMemoryBundleFailure(input.json, "export", classifyMemoryBundleExportFailure(MemoryBundleExportError, error));
+        return 1;
+    }
+}
+async function runMemoryBundleImport(context, rest, input) {
+    const operation = rest[0];
+    const label = memoryImportOperationLabel(operation);
+    const memory = bundleMemorySettings(context);
+    if (memory === undefined) {
+        writeMemoryBundleFailure(input.json, label, "import_requires_bujo");
+        return 1;
+    }
+    try {
+        const bujo = await loadBujoModule();
+        // Canonicalize once through the import operation's recovery-aware resolver.
+        // Every containment check, fingerprint, and package call below must bind to
+        // this same root identity (not a lexical Darwin system alias).
+        const root = bujo.resolveMemoryBundleImportRoot(resolve(context.cwd, memory.path));
+        if (operation === "prepare") {
+            const result = await prepareMemoryImportPlan(context, root, input, bujo);
+            write(input.json, result, () => renderMemoryBundleImport(result));
+            return 0;
+        }
+        if (operation === "apply") {
+            const result = await applyMemoryImportPlan(context, root, input.planPath, bujo);
+            write(input.json, result, () => renderMemoryBundleImport(result));
+            return 0;
+        }
+        const result = await restoreMemoryImportBackup(context, root, input.backupPath, bujo);
+        write(input.json, result, () => renderMemoryBundleImport(result));
+        return 0;
+    }
+    catch (error) {
+        const failure = error instanceof MemoryBundleOperationError
+            ? error
+            : new MemoryBundleOperationError(operation === "prepare"
+                ? "import_prepare_failed"
+                : operation === "restore"
+                    ? "import_restore_failed"
+                    : "import_apply_failed");
+        writeMemoryBundleFailure(input.json, label, failure.code, failure.recovered, failure.backupPath);
+        return 1;
+    }
+}
+async function prepareMemoryImportPlan(context, root, input, bujo) {
+    const planPath = await canonicalProspectivePath(resolve(context.cwd, input.planPath));
+    if (isSameOrUnderDirectory(root, planPath)) {
+        throw new MemoryBundleOperationError("import_prepare_failed");
+    }
+    const bundlePath = resolve(context.cwd, input.bundlePath);
+    let preview;
+    try {
+        preview = bujo.prepareMemoryBundleImport({
+            root,
+            bundlePath,
+            onConflict: input.onConflict ?? "fail",
+            entityConflict: input.entityConflict ?? "target",
+            acceptDerivedAssociationDrift: input.acceptDerivedAssociationDrift === true,
+        });
+    }
+    catch (error) {
+        throw new MemoryBundleOperationError(classifyImportPrepareFailure(bujo.MemoryBundleImportError, error));
+    }
+    const payload = {
+        schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+        operation: "import",
+        rootFingerprint: preview.rootFingerprint,
+        destinationSourceFingerprint: preview.destinationSourceFingerprint,
+        bundlePath: preview.bundlePath,
+        bundleDigest: preview.bundleDigest,
+        mergeDigest: preview.mergeDigest,
+        mergedSourceFingerprint: preview.mergedSourceFingerprint,
+        onConflict: preview.onConflict,
+        entityConflict: preview.entityConflict,
+        acceptDerivedAssociationDrift: input.acceptDerivedAssociationDrift === true,
+        createdAt: new Date().toISOString(),
+    };
+    const plan = {
+        ...payload,
+        planDigest: createHash("sha256").update(JSON.stringify(payload)).digest("hex"),
+    };
+    await writePrivateJsonExclusive(planPath, plan);
+    return {
+        schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+        operation: "memory-import-prepare",
+        status: "prepared",
+        planPath,
+        planDigest: plan.planDigest,
+        counts: preview.counts,
+        // Counts only: entity ids and memory ids never enter the operator plan.
+        derivedAssociationsAdded: preview.derivedAssociationsAdded.length,
+        derivedAssociationsRemoved: preview.derivedAssociationsRemoved.length,
+        ...(preview.bundlePendingWork ? { bundlePendingWork: true } : {}),
+    };
+}
+async function applyMemoryImportPlan(context, root, rawPlanPath, bujo) {
+    const planPath = resolve(context.cwd, rawPlanPath);
+    if (isSameOrUnderDirectory(root, await canonicalProspectivePath(planPath))) {
+        throw new MemoryBundleOperationError("import_apply_failed");
+    }
+    const plan = await readMemoryImportPlan(planPath);
+    if (plan.rootFingerprint !== memoryRootFingerprint(root)) {
+        throw new MemoryBundleOperationError("import_stale_plan");
+    }
+    // Preserve the user-facing same-config diagnostic; the package transaction
+    // independently enforces the authoritative shared-root writer lease.
+    await assertNoLiveConfiguredAgent(context.configPath, await memoryRegistryDirs(context));
+    const settings = previewRecallSettings(context.config);
+    if (settings === undefined || "supermemory" in settings || settings.embeddings === undefined) {
+        throw new MemoryBundleOperationError("import_config_invalid");
+    }
+    const { createMemoryEmbeddingProvider } = await loadMemoryRecallModule();
+    const embeddings = await createMemoryEmbeddingProvider(settings.embeddings);
+    try {
+        const result = await bujo.applyMemoryBundleImport({
+            root,
+            bundlePath: plan.bundlePath,
+            expectedRootFingerprint: plan.rootFingerprint,
+            expectedSourceFingerprint: plan.destinationSourceFingerprint,
+            expectedBundleDigest: plan.bundleDigest,
+            expectedMergeDigest: plan.mergeDigest,
+            expectedMergedSourceFingerprint: plan.mergedSourceFingerprint,
+            planDigest: plan.planDigest,
+            onConflict: plan.onConflict,
+            entityConflict: plan.entityConflict,
+            acceptDerivedAssociationDrift: plan.acceptDerivedAssociationDrift,
+            embeddings,
+            dimension: settings.embeddings.dim ?? 768,
+        });
+        return {
+            schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+            operation: "memory-import-apply",
+            status: "applied",
+            imported: result.imported,
+            skipped: result.skipped,
+            identical: result.identical,
+            sourceFingerprint: result.sourceFingerprint,
+            backupPath: result.backupPath,
+            planDigest: plan.planDigest,
+            rollbackRetained: false,
+        };
+    }
+    catch (error) {
+        throw new MemoryBundleOperationError(...classifyImportApplyFailure(bujo, error));
+    }
+}
+async function restoreMemoryImportBackup(context, root, rawBackupPath, bujo) {
+    const backupPath = resolve(context.cwd, rawBackupPath);
+    await assertNoLiveConfiguredAgent(context.configPath, await memoryRegistryDirs(context));
+    try {
+        const result = await bujo.restoreMemoryBundleImport({
+            root,
+            backupPath,
+            expectedRootFingerprint: memoryRootFingerprint(root),
+        });
+        return {
+            schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+            operation: "memory-import-restore",
+            status: "restored",
+            sourceFingerprint: result.sourceFingerprint,
+            backupPath: result.backupPath,
+            planDigest: result.planDigest,
+        };
+    }
+    catch {
+        throw new MemoryBundleOperationError("import_restore_failed");
+    }
+}
+export function classifyMemoryBundleExportFailure(MemoryBundleExportError, error) {
+    if (!(error instanceof MemoryBundleExportError))
+        return "export_failed";
+    return classifyMemoryBundleExportCode(error.code);
+}
+function classifyMemoryBundleExportCode(code) {
+    switch (code) {
+        case "export_destination_invalid":
+        case "export_pending_work":
+        case "export_source_changed":
+        case "export_source_invalid":
+        case "export_failed":
+            return code;
+        default:
+            return unexpectedMemoryBundleExportCode(code);
+    }
+}
+function unexpectedMemoryBundleExportCode(_code) {
+    return "export_failed";
+}
+export function classifyImportPrepareFailure(MemoryBundleImportError, error) {
+    if (!(error instanceof MemoryBundleImportError))
+        return "import_prepare_failed";
+    const code = error.code;
+    switch (code) {
+        case "import_derived_drift":
+            return "import_derived_drift";
+        case "import_bundle_invalid":
+        case "import_bundle_incompatible":
+            return "import_bundle_invalid";
+        case "import_prepare_failed":
+            return hasExplicitCauseCode(error, "id_conflict") ? "import_conflict" : "import_prepare_failed";
+        case "import_pending_work":
+        case "import_stale_plan":
+        case "import_apply_failed":
+        case "import_apply_failed_recovered":
+        case "import_apply_recovery_failed":
+        case "import_restore_failed":
+            return "import_prepare_failed";
+        default:
+            return unexpectedImportPrepareCode(code);
+    }
+}
+function unexpectedImportPrepareCode(_code) {
+    return "import_prepare_failed";
+}
+export function classifyImportApplyFailure(bujo, error) {
+    if (error instanceof bujo.MemoryBundleImportError) {
+        const code = error.code;
+        switch (code) {
+            case "import_apply_failed_recovered":
+                return ["import_apply_failed_recovered", true, error.backupPath];
+            case "import_apply_recovery_failed":
+                return ["import_apply_recovery_failed", false, error.backupPath];
+            case "import_stale_plan":
+                return ["import_stale_plan", false, undefined];
+            case "import_derived_drift":
+                return ["import_derived_drift", false, undefined];
+            case "import_bundle_invalid":
+            case "import_bundle_incompatible":
+                return ["import_bundle_invalid", false, undefined];
+            case "import_pending_work":
+                return ["import_pending_work", false, undefined];
+            case "import_apply_failed":
+            case "import_prepare_failed":
+            case "import_restore_failed":
+                return ["import_apply_failed", false, undefined];
+            default:
+                return unexpectedImportApplyCode(code);
+        }
+    }
+    return ["import_apply_failed", false, undefined];
+}
+function unexpectedImportApplyCode(_code) {
+    return ["import_apply_failed", false, undefined];
+}
+function hasExplicitCauseCode(error, expectedCode) {
+    const seen = new Set();
+    let current = readErrorProperty(error, "cause");
+    for (let depth = 0; depth < MAX_MEMORY_BUNDLE_CAUSE_DEPTH; depth += 1) {
+        if (!current.ok || !isIntrinsicError(current.value) || seen.has(current.value))
+            return false;
+        const candidate = current.value;
+        seen.add(candidate);
+        const code = readOwnErrorCode(candidate);
+        if (code.ok && code.value === expectedCode)
+            return true;
+        current = readErrorProperty(candidate, "cause");
+    }
+    return false;
+}
+function readOwnErrorCode(error) {
+    try {
+        if (!Object.prototype.hasOwnProperty.call(error, "code"))
+            return { ok: true, value: undefined };
+    }
+    catch {
+        return { ok: false };
+    }
+    return readErrorProperty(error, "code");
+}
+async function readMemoryImportPlan(path) {
+    const value = await readPrivateJson(path, MAX_IMPORT_PLAN_BYTES);
+    if (!isObject(value)
+        || !hasExactKeys(value, [
+            "acceptDerivedAssociationDrift",
+            "bundleDigest",
+            "bundlePath",
+            "createdAt",
+            "destinationSourceFingerprint",
+            "entityConflict",
+            "mergeDigest",
+            "mergedSourceFingerprint",
+            "onConflict",
+            "operation",
+            "planDigest",
+            "rootFingerprint",
+            "schemaVersion",
+        ])
+        || value.schemaVersion !== MEMORY_BUNDLE_CLI_SCHEMA_VERSION
+        || value.operation !== "import"
+        || !isSha256(value.rootFingerprint)
+        || !isSha256(value.destinationSourceFingerprint)
+        || typeof value.bundlePath !== "string"
+        || !isSha256(value.bundleDigest)
+        || !isSha256(value.mergeDigest)
+        || !isSha256(value.mergedSourceFingerprint)
+        || (value.onConflict !== "fail" && value.onConflict !== "skip")
+        || (value.entityConflict !== "target" && value.entityConflict !== "source")
+        || typeof value.acceptDerivedAssociationDrift !== "boolean"
+        || typeof value.createdAt !== "string" || !isCanonicalIso(value.createdAt)
+        || !isSha256(value.planDigest)) {
+        throw new MemoryBundleOperationError("import_stale_plan");
+    }
+    const plan = value;
+    const { planDigest, ...payload } = plan;
+    if (createHash("sha256").update(JSON.stringify(payload)).digest("hex") !== planDigest) {
+        throw new MemoryBundleOperationError("import_stale_plan");
+    }
+    return plan;
+}
+function memoryImportOperationLabel(operation) {
+    return operation === "prepare" || operation === "apply" || operation === "restore"
+        ? `import-${operation}`
+        : "import-unknown";
+}
+export function writeMemoryBundleFailure(json, operation, code, recovered = false, backupPath) {
+    const safeOperation = operation === "export"
+        || operation === "import-prepare"
+        || operation === "import-apply"
+        || operation === "import-restore"
+        || operation === "import-unknown"
+        ? operation
+        : "import-unknown";
+    const result = {
+        schemaVersion: MEMORY_BUNDLE_CLI_SCHEMA_VERSION,
+        operation: `memory-${safeOperation}`,
+        status: "failed",
+        code,
+        message: MEMORY_BUNDLE_FAILURE_MESSAGES[code],
+        ...(recovered ? { recovered: true } : {}),
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+    if (json) {
+        write(true, result, () => "");
+        return;
+    }
+    process.stderr.write(ui.errorLine(`[${code}] ${result.message}`));
+}
+function renderMemoryBundleExport(result) {
+    return `${ui.banner("mono-agent memory", "export")}\n${ui.keyValue([
+        ["bundle", result.bundlePath],
+        ["scope", result.scope],
+        ["memories", String(result.counts.memories)],
+        ["daily files", String(result.counts.dailyFiles)],
+        ["entities", String(result.counts.graphEntities)],
+        ["source fingerprint", result.sourceFingerprint],
+        ...(result.pendingWork === true ? [["pending work", "yes"]] : []),
+    ])}\n`;
+}
+function renderMemoryBundleImport(result) {
+    return `${ui.banner("mono-agent memory", result.operation)}\n${ui.keyValue([
+        ["status", result.status],
+        ...(result.counts === undefined ? [] : [["new memories", String(result.counts.newMemories)]]),
+        ...(result.counts === undefined ? [] : [["conflicts", String(result.counts.conflictingMemories)]]),
+        ...(result.derivedAssociationsAdded === undefined
+            ? []
+            : [["derived associations +/-",
+                    `${result.derivedAssociationsAdded}/${result.derivedAssociationsRemoved ?? 0}`]]),
+        ...(result.imported === undefined ? [] : [["imported", String(result.imported)]]),
+        ...(result.skipped === undefined ? [] : [["skipped", String(result.skipped)]]),
+        ...(result.identical === undefined ? [] : [["identical", String(result.identical)]]),
+        ...(result.planPath === undefined ? [] : [["plan", result.planPath]]),
+        ...(result.backupPath === undefined ? [] : [["backup", result.backupPath]]),
+        ...(result.sourceFingerprint === undefined ? [] : [["source fingerprint", result.sourceFingerprint]]),
+    ])}\n`;
+}
 async function runReplayAdoption(context, json) {
     const memory = context.config.memory;
     if (memory === undefined || (memory.backend ?? "bujo") === "supermemory"