@holon-run/agentinbox 1.5.2 → 1.6.0

package/README.md

@@ -299,6 +299,22 @@ that database next to the DB path (for example,
 `~/.agentinbox/agentinbox.sqlite.pre-v1.<timestamp>.bak`) and starts with a
 fresh v1 database; pre-v1 local data is not imported.
 
+## Database Backups
+
+Startup backups are event-driven, not unconditional:
+
+- before pending schema migrations run, a full backup is written to
+  `<db>.pre-migrate-v<N>.bak` (bounded by `AGENTINBOX_MIGRATION_BACKUP_KEEP`,
+  default 5; `0` keeps all)
+- `agentinbox backup [--home DIR] [--state PATH]` writes a manual snapshot to
+  `<db>.bak` on demand, for scheduled or pre-upgrade snapshots
+- regular opens verify the database with `PRAGMA quick_check` and escalate to
+  a full `integrity_check` only when the quick pass fails; recovery considers
+  manual and pre-migration backups, most recent first
+
+Setting `AGENTINBOX_STARTUP_BACKUP=1` restores the legacy behavior of backing
+up (and fully checking) the database on every open.
+
 ## License
 
 Apache-2.0

package/dist/src/cli.js

@@ -60,6 +60,14 @@ async function main() {
         await runDaemon(normalized.slice(1));
         return;
     }
+    if (command === "backup") {
+        if (hasHelpFlag(normalized.slice(1))) {
+            printHelp(["backup"]);
+            return;
+        }
+        await runBackup(normalized.slice(1));
+        return;
+    }
     if (hasHelpFlag(normalized.slice(1))) {
         printHelp([command]);
         return;
@@ -971,6 +979,7 @@ const COMMAND_SHELL_SPECS = [
     { name: "subscription", group: true, summary: "Manage source subscriptions." },
     { name: "inbox", group: true, summary: "Read and manage agent inboxes." },
     { name: "gc", group: false, summary: "Run garbage collection." },
+    { name: "backup", group: false, summary: "Write a local database backup snapshot." },
     { name: "deliver", group: true, summary: "Send outbound delivery actions." },
     { name: "status", group: false, summary: "Show daemon status." },
     { name: "version", group: false, summary: "Show CLI version." },
@@ -1006,6 +1015,25 @@ function parseCommanderShell(args) {
         isBareGroup: Boolean(COMMAND_SHELL_SPECS.find((item) => item.name === spec?.name())?.group && args.length === 1),
     };
 }
+async function runBackup(args) {
+    const serveConfig = (0, paths_1.resolveServeConfig)({
+        env: process.env,
+        homeDirOverride: takeFlagValue(args, "--home"),
+        statePathOverride: takeFlagValue(args, "--state"),
+    });
+    const store = await store_1.AgentInboxStore.open(serveConfig.dbPath);
+    try {
+        const backupPath = await store.backupDatabase();
+        console.log((0, util_1.jsonResponse)({
+            ok: true,
+            dbPath: serveConfig.dbPath,
+            backupPath,
+        }));
+    }
+    finally {
+        store.close();
+    }
+}
 async function runServe(args) {
     const port = parseOptionalNumber(takeFlagValue(args, "--port"));
     const homeOverride = takeFlagValue(args, "--home");
@@ -1677,6 +1705,14 @@ Usage:
   agentinbox daemon start [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock] [--log-level error|warn|info|debug|trace]
   agentinbox daemon stop [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
   agentinbox daemon status [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
+`,
+        backup: `agentinbox backup
+
+Usage:
+  agentinbox backup [--home ~/.agentinbox] [--state ~/.agentinbox/agentinbox.sqlite]
+
+Writes a verified snapshot to <db>.bak (replaces the previous manual backup).
+Pre-migration backups (<db>.pre-migrate-v<N>.bak) are created automatically.
 `,
         host: `agentinbox host
 

package/dist/src/store.js

@@ -40,24 +40,29 @@ class AgentInboxStore {
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
         removeOrphanBackupTmps(dbPath);
         const existedBeforeOpen = node_fs_1.default.existsSync(dbPath);
-        let db = await this.openDatabaseWithRecovery(dbPath);
+        // Legacy AGENTINBOX_STARTUP_BACKUP=1 mode pays for a full check and an
+        // unconditional backup on every open, matching v1.5.2 behavior.
+        const legacyStartupBackup = legacyStartupBackupEnabled(env);
+        let db = await this.openDatabaseWithRecovery(dbPath, legacyStartupBackup);
         let store = new AgentInboxStore(dbPath, db);
+        let archivedPreV1 = false;
         if (existedBeforeOpen && store.shouldArchivePreV1Database()) {
             const archivedPath = store.archivePreV1Database();
             console.warn(`[agentinbox] archived pre-v1 local database to ${archivedPath}; starting with a fresh v1 database (no data imported).`);
             db = this.openDatabase(dbPath);
             store = new AgentInboxStore(dbPath, db);
+            archivedPreV1 = true;
         }
-        else if (existedBeforeOpen && startupBackupEnabled(env)) {
-            await store.backupHealthyDatabase();
+        else if (existedBeforeOpen && legacyStartupBackup) {
+            await store.backupDatabase();
         }
-        store.migrate();
+        await store.migrate({ existedBeforeOpen: existedBeforeOpen && !archivedPreV1, env });
         store.persist();
         return store;
     }
-    static async openDatabaseWithRecovery(dbPath) {
+    static async openDatabaseWithRecovery(dbPath, fullCheck) {
         try {
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
         catch (error) {
             if (!node_fs_1.default.existsSync(dbPath)) {
@@ -71,19 +76,29 @@ class AgentInboxStore {
             node_fs_1.default.renameSync(dbPath, corruptPath);
             node_fs_1.default.copyFileSync(backupPath, dbPath);
             console.warn(`[agentinbox] recovered local database from ${backupPath}; archived corrupt database to ${corruptPath}.`);
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
     }
-    static openDatabase(dbPath) {
+    static openDatabase(dbPath, fullCheck = false) {
         const db = new better_sqlite3_1.default(dbPath);
         db.pragma("busy_timeout = 5000");
         db.pragma("journal_mode = WAL");
         db.pragma("synchronous = NORMAL");
         db.pragma("foreign_keys = ON");
-        this.assertHealthy(db, dbPath);
+        this.assertHealthy(db, dbPath, fullCheck);
         return db;
     }
-    static assertHealthy(db, dbPath) {
+    /**
+     * Verifies database integrity. Regular opens run `quick_check` and only
+     * escalate to a full `integrity_check` when the quick pass fails, so large
+     * databases do not pay a full scan on every startup. Conservative callers
+     * (legacy `AGENTINBOX_STARTUP_BACKUP=1` mode, recovery-candidate
+     * validation) pass `fullCheck`.
+     */
+    static assertHealthy(db, dbPath, fullCheck) {
+        if (!fullCheck && db.pragma("quick_check", { simple: true }) === "ok") {
+            return;
+        }
         const result = db.pragma("integrity_check", { simple: true });
         if (result !== "ok") {
             db.close();
@@ -95,7 +110,7 @@ class AgentInboxStore {
         for (const candidate of candidates) {
             try {
                 const db = new better_sqlite3_1.default(candidate, { readonly: true, fileMustExist: true });
-                this.assertHealthy(db, candidate);
+                this.assertHealthy(db, candidate, true);
                 db.close();
                 return candidate;
             }
@@ -108,14 +123,32 @@ class AgentInboxStore {
     static listBackupCandidates(dbPath) {
         const dir = node_path_1.default.dirname(dbPath);
         const baseName = node_path_1.default.basename(dbPath);
-        const startupBackups = node_fs_1.default.existsSync(dir)
-            ? node_fs_1.default.readdirSync(dir)
-                .filter((name) => name.startsWith(`${baseName}.startup.`) && name.endsWith(".bak"))
-                .sort()
-                .reverse()
-                .map((name) => node_path_1.default.join(dir, name))
-            : [];
-        return [`${dbPath}.bak`, ...startupBackups].filter((candidate, index, all) => node_fs_1.default.existsSync(candidate) && all.indexOf(candidate) === index);
+        const preMigrationPattern = new RegExp(`^${escapeRegExp(baseName)}\\.pre-migrate-v(\\d+)\\.bak$`);
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        const candidates = [];
+        for (const name of entries) {
+            const candidatePath = node_path_1.default.join(dir, name);
+            if (name === `${baseName}.bak`) {
+                candidates.push({ path: candidatePath, version: 0, modifiedAtMs: backupMtimeMs(candidatePath) });
+                continue;
+            }
+            const preMigration = preMigrationPattern.exec(name);
+            if (preMigration) {
+                candidates.push({
+                    path: candidatePath,
+                    version: Number.parseInt(preMigration[1], 10),
+                    modifiedAtMs: backupMtimeMs(candidatePath),
+                });
+            }
+        }
+        candidates.sort((left, right) => right.modifiedAtMs - left.modifiedAtMs || right.version - left.version);
+        return candidates.map((candidate) => candidate.path);
     }
     static nextPath(base) {
         if (!node_fs_1.default.existsSync(base)) {
@@ -135,13 +168,22 @@ class AgentInboxStore {
     }
     getDatabaseHealth() {
         return {
-            integrityCheck: String(this.db.pragma("integrity_check", { simple: true })),
+            quickCheck: String(this.db.pragma("quick_check", { simple: true })),
             journalMode: String(this.db.pragma("journal_mode", { simple: true })),
             foreignKeys: Number(this.db.pragma("foreign_keys", { simple: true })) === 1,
         };
     }
-    async backupHealthyDatabase() {
+    /**
+     * Writes a snapshot to `<db>.bak`, used by `agentinbox backup` and by the
+     * opt-in legacy `AGENTINBOX_STARTUP_BACKUP=1` startup backup. The open-time
+     * health check has already run against this handle. Returns the backup path.
+     */
+    async backupDatabase() {
         const backupPath = `${this.dbPath}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    async writeBackupTo(backupPath) {
         const tmpPath = `${backupPath}.${process.pid}.tmp`;
         try {
             node_fs_1.default.rmSync(tmpPath, { force: true });
@@ -152,17 +194,57 @@ class AgentInboxStore {
             node_fs_1.default.rmSync(tmpPath, { force: true });
         }
     }
-    migrate() {
+    async migrate(options) {
         const migrations = this.loadSqlMigrations();
         this.ensureDrizzleMigrationsTable();
         const applied = this.listAppliedMigrationTags();
         const pending = migrations.filter((migration) => !applied.has(migration.tag));
+        if (options.existedBeforeOpen && pending.length > 0) {
+            const backupPath = await this.backupBeforeMigration(migrations.length);
+            console.warn(`[agentinbox] pending schema migrations detected; backed up the local database to ${backupPath} before migrating to schema v${migrations.length}.`);
+            this.pruneMigrationBackups(options.env);
+        }
         for (const migration of pending) {
             this.applyMigration(migration);
         }
         this.ensureInboxEntryBackfill();
         this.setUserVersion(migrations.length);
     }
+    async backupBeforeMigration(targetVersion) {
+        const backupPath = `${this.dbPath}.pre-migrate-v${targetVersion}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    /**
+     * Keeps only the newest `AGENTINBOX_MIGRATION_BACKUP_KEEP` pre-migration
+     * backups (default 5; values <= 0 keep everything). Migration backups are
+     * rare, so pruning only runs right after a new one is written.
+     */
+    pruneMigrationBackups(env) {
+        const keep = migrationBackupKeep(env);
+        if (keep <= 0) {
+            return;
+        }
+        const dir = node_path_1.default.dirname(this.dbPath);
+        const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(this.dbPath))}\\.pre-migrate-v(\\d+)\\.bak$`);
+        const entries = [];
+        for (const name of node_fs_1.default.readdirSync(dir)) {
+            const match = pattern.exec(name);
+            if (!match) {
+                continue;
+            }
+            entries.push({ path: node_path_1.default.join(dir, name), version: Number.parseInt(match[1], 10) });
+        }
+        entries.sort((left, right) => right.version - left.version);
+        for (const entry of entries.slice(keep)) {
+            try {
+                node_fs_1.default.rmSync(entry.path, { force: true });
+            }
+            catch {
+                // Best-effort pruning.
+            }
+        }
+    }
     loadSqlMigrations() {
         const migrationsDir = this.resolveMigrationsDir();
         const files = node_fs_1.default
@@ -2384,16 +2466,37 @@ function uniqueSorted(values) {
 function summarizeBackfilledItemEntry(item) {
     return `${item.eventVariant} from ${item.sourceId}`;
 }
-function startupBackupEnabled(env) {
-    return !(0, util_1.isEnvFlagDisabled)(env.AGENTINBOX_STARTUP_BACKUP);
+const DEFAULT_MIGRATION_BACKUP_KEEP = 5;
+/**
+ * Backups are event-driven: a full database backup is taken only before
+ * pending schema migrations run, plus explicit `agentinbox backup` snapshots.
+ * Setting `AGENTINBOX_STARTUP_BACKUP=1` opts back into the legacy v1.5.2
+ * behavior of an unconditional backup and a full `integrity_check` on every
+ * open.
+ */
+function legacyStartupBackupEnabled(env) {
+    return (0, util_1.isEnvFlagEnabled)(env.AGENTINBOX_STARTUP_BACKUP);
+}
+function migrationBackupKeep(env) {
+    const parsed = Number.parseInt(env.AGENTINBOX_MIGRATION_BACKUP_KEEP ?? "", 10);
+    return Number.isInteger(parsed) ? parsed : DEFAULT_MIGRATION_BACKUP_KEEP;
+}
+function backupMtimeMs(candidatePath) {
+    try {
+        return node_fs_1.default.statSync(candidatePath).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
 }
 /**
- * Removes leftover `<db>.bak.<pid>.tmp` files whose owning process is dead.
- * Tmp files owned by a live pid belong to a concurrent open and are preserved.
+ * Removes leftover `<db>.*.bak.<pid>.tmp` files (manual and pre-migration
+ * backup temporaries) whose owning process is dead. Tmp files owned by a live
+ * pid belong to a concurrent open and are preserved.
  */
 function removeOrphanBackupTmps(dbPath) {
     const dir = node_path_1.default.dirname(dbPath);
-    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.bak\\.(\\d+)\\.tmp$`);
+    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.(?:.+\\.)?bak\\.(\\d+)\\.tmp$`);
     let entries;
     try {
         entries = node_fs_1.default.readdirSync(dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {