@b4run/sqlite-storage

SQLite persistence for B4.run checkpoints and Agent Protocol threads.

Use this when: You need to use B4.run's local checkpoint or thread persistence directly.

Install

pnpm add @b4run/sqlite-storage

Example

import { createThreadsStore, sqliteCheckpointer } from "@b4run/sqlite-storage"

export const checkpointer = sqliteCheckpointer({ path: ".b4/checkpoints.sqlite" })
export const threadsStore = createThreadsStore({ path: ".b4/threads.sqlite" })

Runtime and stability

@b4run/sqlite-storage is a node-only, supported application surface.

SQLite is a local process-oriented default. Use shared persistence when multiple application instances must observe the same checkpoints or threads.

Workspace source-bundle persistence and installation ownership support managed workspaces. The installation owner keeps a durable identity and source bundles in .b4/workspaces/state.sqlite, with a separate SQLite writer lock that admits one active owner on a local host. Separate state transactions remain available while that lock is held; it does not serialize every thread into one run.

An interrupted first initialization can resume. An established installation with missing or inconsistent state fails closed. Process death releases the ownership lock. This does not support network filesystems, multiple hosts, or recovery from loss or replacement of the entire state directory.

The Node runtime acquires ownership before admitting managed workspace work. openWorkspaceInstallation exposes guarded source and association stores; creation and deletion transitions remain durable across process restarts.

Related

• SQLite Storage API reference — exact checkpoint and thread-store contracts.
• Persistence and Tenancy — application configuration and storage boundaries.
• @b4run/postgres-storage — shared Postgres persistence.

Maturity and support

B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the @b4run/sqlite-storage changelog and upgrading guide before upgrading. For support, use GitHub Discussions; report defects in GitHub Issues.

License

MIT. See the repository license.