{"_id":"@backblaze-labs/agent-backup-core","_rev":"4-3e1aa7c02a60f5dccd5981f702734622","name":"@backblaze-labs/agent-backup-core","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@backblaze-labs/agent-backup-core","version":"0.1.0","keywords":["backblaze","b2","backup","ai-agent","sqlite","encryption"],"license":"MIT","_id":"@backblaze-labs/agent-backup-core@0.1.0","maintainers":[{"name":"goanpeca","email":"goanpeca@gmail.com"},{"name":"jdnyc","email":"jdeleon@jdeleon.com"}],"homepage":"https://github.com/backblaze-b2-samples/agent-backup-core#readme","bugs":{"url":"https://github.com/backblaze-b2-samples/agent-backup-core/issues"},"dist":{"shasum":"5c2c9a9253b591fd71dcc9deb68a09c02e97f6fa","tarball":"https://registry.npmjs.org/@backblaze-labs/agent-backup-core/-/agent-backup-core-0.1.0.tgz","fileCount":4,"integrity":"sha512-aC6LaDsA7oGeiH5AJQ2O/3VpR2bLWv7lEgLwRZmtlGidLrRo6zVw1oFz2IhKc4nPyWpOhMOVCoTpM4RdUp2uEQ==","signatures":[{"sig":"MEUCIQD9NVg6e6cqWtlCvUkrIcPIvMEkUxESLcm8Y3bQsoi+aAIgP2UTt8SiyF5cIbLGau5MONK/c5UQBdav4uKmm3gHHl0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44817},"main":"dist/index.mjs","type":"module","types":"dist/index.d.mts","engines":{"node":">=22.5.0"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"gitHead":"25c55366776f151afa0d5d3879f2cd3327925672","scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --out-dir dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"jdnyc","email":"jdeleon@jdeleon.com"},"repository":{"url":"git+https://github.com/backblaze-b2-samples/agent-backup-core.git","type":"git"},"_npmVersion":"11.6.0","description":"Reusable engine for backing up an AI agent's local state to Backblaze B2: incremental SHA-256 diffing, AES-256-GCM encryption, WAL-safe SQLite snapshots, and a standalone backup runner.","directories":{},"_nodeVersion":"24.9.0","dependencies":{"croner":"^10.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.20.0","vitest":"^4.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-backup-core_0.1.0_1782265715775_0.2111225325509305","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@backblaze-labs/agent-backup-core","version":"0.1.1","keywords":["backblaze","b2","backup","ai-agent","sqlite","encryption"],"license":"MIT","_id":"@backblaze-labs/agent-backup-core@0.1.1","maintainers":[{"name":"goanpeca","email":"goanpeca@gmail.com"},{"name":"jdnyc","email":"jdeleon@jdeleon.com"}],"homepage":"https://github.com/backblaze-b2-samples/agent-backup-core#readme","bugs":{"url":"https://github.com/backblaze-b2-samples/agent-backup-core/issues"},"dist":{"shasum":"e080f58b3ebcbc812690404aac37717bc384e10d","tarball":"https://registry.npmjs.org/@backblaze-labs/agent-backup-core/-/agent-backup-core-0.1.1.tgz","fileCount":4,"integrity":"sha512-Gr017TeSnXaY9kqnwrJEIOCrT3RfKeLjGj2AFxbDt6TwcEKU7wFoUjdG/4+6p08YId21YMAoRm+s5fO32LIoIg==","signatures":[{"sig":"MEYCIQCRibdvLRKjaEHDWSQwDp+7FvjYO9B5EN+B0kRP08UytAIhALBgBtPi0+sU6mTfsAOPh/u0QoH9nQp1QRfptUVnilEK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45274},"main":"dist/index.mjs","type":"module","types":"dist/index.d.mts","engines":{"node":">=22.5.0"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"gitHead":"ccc310ee8ab934a6287aeaaba223cd0d6485d507","scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --out-dir dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"jdnyc","email":"jdeleon@jdeleon.com"},"repository":{"url":"git+https://github.com/backblaze-b2-samples/agent-backup-core.git","type":"git"},"_npmVersion":"11.6.0","description":"Reusable engine for backing up an AI agent's local state to Backblaze B2: incremental SHA-256 diffing, AES-256-GCM encryption, WAL-safe SQLite snapshots, and a standalone backup runner.","directories":{},"_nodeVersion":"24.9.0","dependencies":{"croner":"^10.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.20.0","vitest":"^4.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-backup-core_0.1.1_1782266957040_0.6128178223848375","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@backblaze-labs/agent-backup-core","version":"0.2.0","keywords":["backblaze","b2","backup","ai-agent","sqlite","encryption"],"license":"MIT","_id":"@backblaze-labs/agent-backup-core@0.2.0","maintainers":[{"name":"goanpeca","email":"goanpeca@gmail.com"},{"name":"jdnyc","email":"jdeleon@jdeleon.com"}],"homepage":"https://github.com/backblaze-b2-samples/agent-backup-core#readme","bugs":{"url":"https://github.com/backblaze-b2-samples/agent-backup-core/issues"},"dist":{"shasum":"9fee06ae978d87a91fda773be2e456d0afcb9eaf","tarball":"https://registry.npmjs.org/@backblaze-labs/agent-backup-core/-/agent-backup-core-0.2.0.tgz","fileCount":4,"integrity":"sha512-epueu+FWuePMYdOnWozNW9ZQK1Xp7o+WnvRMQy+mQKhBt0YNmi4A18U4npb1I602wG1gEt7tS4I7r4m3xbCXMQ==","signatures":[{"sig":"MEQCIG2I7bvGEMMLrfGyt6sc5lE2zqbxR9dohihLvftdyYmLAiBX8RCzZrkkKcCs3VuaTjALyny5lm+mQ3djY0AA32Kwdg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55815},"main":"dist/index.mjs","type":"module","types":"dist/index.d.mts","engines":{"node":">=22.5.0"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"gitHead":"47fc11f64642a6e9b611537807261ab9fc6b12d5","scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --out-dir dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"jdnyc","email":"jdeleon@jdeleon.com"},"repository":{"url":"git+https://github.com/backblaze-b2-samples/agent-backup-core.git","type":"git"},"_npmVersion":"11.6.0","description":"Reusable engine for backing up an AI agent's local state to Backblaze B2: incremental SHA-256 diffing, AES-256-GCM encryption, WAL-safe SQLite snapshots, and a standalone backup runner.","directories":{},"_nodeVersion":"24.9.0","dependencies":{"croner":"^10.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.20.0","vitest":"^4.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-backup-core_0.2.0_1782269804552_0.6815635268896181","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@backblaze-labs/agent-backup-core","version":"0.3.0","description":"Reusable engine for backing up an AI agent's local state to Backblaze B2: incremental SHA-256 diffing, AES-256-GCM encryption, WAL-safe SQLite snapshots, and a standalone backup runner.","type":"module","main":"dist/index.mjs","types":"dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"build":"tsdown src/index.ts --format esm --dts --out-dir dist","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"dependencies":{"croner":"^10.0.0"},"devDependencies":{"@types/node":"^22.0.0","tsdown":"^0.20.0","typescript":"^5.9.0","vitest":"^4.0.0"},"engines":{"node":">=22.5.0"},"publishConfig":{"access":"public"},"keywords":["backblaze","b2","backup","ai-agent","sqlite","encryption"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/backblaze-labs/agent-backup-core.git"},"_id":"@backblaze-labs/agent-backup-core@0.3.0","gitHead":"47fc11f64642a6e9b611537807261ab9fc6b12d5","bugs":{"url":"https://github.com/backblaze-labs/agent-backup-core/issues"},"homepage":"https://github.com/backblaze-labs/agent-backup-core#readme","_nodeVersion":"24.9.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-5rQDPVBuJAfrZTTNLvqL93kLBpcUs300f94Qj07/n+y79iR2thyw5PWpKh2oMtFBEHywJAcNgY+57M0hk2/BPg==","shasum":"fe996b36919009c85744b382dbd95ece96592d0a","tarball":"https://registry.npmjs.org/@backblaze-labs/agent-backup-core/-/agent-backup-core-0.3.0.tgz","fileCount":5,"unpackedSize":59066,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICqqnrcCOsIZ54N4IzsaoQfPyCGh5doz7T4yz2Llk6/pAiEA1U+epylm5td1tQwvoPgcC8UTKUypgFQlFM9UksI4B6k="}]},"_npmUser":{"name":"jdnyc","email":"jdeleon@jdeleon.com"},"directories":{},"maintainers":[{"name":"goanpeca","email":"goanpeca@gmail.com"},{"name":"jdnyc","email":"jdeleon@jdeleon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-backup-core_0.3.0_1782273531119_0.06133041120138372"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-24T01:48:35.573Z","modified":"2026-06-24T03:58:51.382Z","0.1.0":"2026-06-24T01:48:35.912Z","0.1.1":"2026-06-24T02:09:17.205Z","0.2.0":"2026-06-24T02:56:44.684Z","0.3.0":"2026-06-24T03:58:51.261Z"},"bugs":{"url":"https://github.com/backblaze-labs/agent-backup-core/issues"},"license":"MIT","homepage":"https://github.com/backblaze-labs/agent-backup-core#readme","keywords":["backblaze","b2","backup","ai-agent","sqlite","encryption"],"repository":{"type":"git","url":"git+https://github.com/backblaze-labs/agent-backup-core.git"},"description":"Reusable engine for backing up an AI agent's local state to Backblaze B2: incremental SHA-256 diffing, AES-256-GCM encryption, WAL-safe SQLite snapshots, and a standalone backup runner.","maintainers":[{"name":"goanpeca","email":"goanpeca@gmail.com"},{"name":"jdnyc","email":"jdeleon@jdeleon.com"}],"readme":"# @backblaze-labs/agent-backup-core\n\nReusable engine for backing up an AI agent's local state to [Backblaze B2](https://www.backblaze.com/cloud-storage). It powers a family of small, independent per-agent backup tools (e.g. [`@backblaze-labs/goose-b2-backup`](https://github.com/backblaze-labs/goose-b2-backup)).\n\nYou normally don't install this directly — you install a per-agent package that depends on it. Install this only to build a backup tool for a **new** agent.\n\n## What it does\n\n- **Incremental sync** — SHA-256 manifest diffing; only changed files are uploaded.\n- **Encryption at rest** — AES-256-GCM, per-file random salt/IV, scrypt-derived key.\n- **WAL-safe SQLite snapshots** — uses SQLite's `.backup()` API (Node `node:sqlite`), with a copy + WAL/SHM fallback, so live databases snapshot consistently.\n- **Multi-root** — mirrors agents whose state is split across several directories (e.g. separate config / data / state dirs) into one namespace, and restores it correctly.\n- **Snapshot retention** — keeps the N most recent snapshots; safety snapshots before a restore are never auto-pruned.\n- **Standalone runner** — a daemon (`runCli`/`runDaemon`/`runOnce`) with single-instance locking, scheduling, auto-restore, and OS-service install. No agent runtime or plugin host required.\n- **Zero heavy deps** — hand-rolled S3 SigV4 client; only `croner` at runtime.\n\n## Building an adapter for a new agent\n\nAn adapter is pure data — where the agent's state lives and what to include:\n\n```ts\nimport { runCli, type BackupAdapter } from \"@backblaze-labs/agent-backup-core\";\n\nconst myAdapter: BackupAdapter = {\n  id: \"myagent\",\n  resolveRoots: (env) => [{ label: \"data\", dir: `${env.HOME}/.myagent` }], // existing dirs only\n  include: [/^data\\/.*\\.db$/, /^data\\/config\\.json$/],\n  exclude: [/-wal$/, /-shm$/],\n  sqlite: [/\\.db$/],          // files needing a WAL-safe snapshot\n  secretExclude: [/secrets/], // never uploaded\n};\n\nrunCli(myAdapter, () => loadYourConfig());\n```\n\nThat's the whole per-agent package: an adapter + a config loader + a one-line bin.\n\n## Security model\n\nRead this before deploying — it differs deliberately from the original OpenClaw plugin.\n\n- **The encryption key is separate from your B2 credentials.** Set `encryptionKey` in config. A leaked B2 application key then cannot decrypt your backups, and vice-versa. If `encryptionKey` is omitted, the engine falls back to deriving the key from the B2 application key (legacy behavior) and logs a **warning** — usable, but it couples backup confidentiality to your bucket credential, so set a real `encryptionKey`.\n- **The manifest is encrypted** when encryption is on. The file inventory itself can leak repo names and conversation topics, so it is not uploaded in the clear.\n- **`secretExclude` keeps designated secret files out of the backup entirely.** This is path-level only: secrets embedded as fields *inside* an otherwise-backed-up file are **not** redacted. Agents that store credentials inside larger state files need a redaction step before they're safe to mirror.\n- **The local manifest cache lives in a tool-owned directory** (`~/.agent-backup/<id>/` by default), never inside the agent's own directories.\n\n## API surface\n\n`createB2Client`, `push`, `pullLatest`, `pullSnapshot`, `listSnapshots`/`getLatestSnapshot`/`pruneSnapshots`, `gatherFiles`/`resolveRelativePath`/`shouldInclude`, `encrypt`/`decrypt`/`isEncrypted`, `snapshotSqlite`, `computeManifest`/`diffManifests`, `runCli`/`runDaemon`/`runOnce`/`buildContext`/`resolvePassphrase`/`acquireLock`/`generateServiceUnit`/`installService`. Types: `BackupAdapter`, `StandaloneConfig`, `BackupContext`, `BackupRoot`, `BackupManifest`, `Logger`.\n\n## Requirements\n\nNode ≥ 22.5.0 (for the built-in `node:sqlite` backup API).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}