@takebox-ai/checkpoint-sqlite

A SQLite (WAL) Checkpointer backend for @takebox-ai/sandbox-core — event-sourced session persistence for single-host, multi-process setups.

The default checkpointer in @takebox-ai/sandbox-sdk is file-based (one JSONL per session). This adapter stores the same event log in a SQLite database instead, using WAL journaling and a BEGIN IMMEDIATE write path so several processes on one host can append concurrently — a conflicting append throws CheckpointConflictError cleanly rather than corrupting the log.

Install

pnpm add @takebox-ai/checkpoint-sqlite

Depends on better-sqlite3 (a native module — it compiles on install).

Usage

Pass the checkpointer to createLiteAgent / query; it overrides the default file store:

import { createLiteAgent } from "@takebox-ai/sandbox-sdk";
import { juglow } from "@takebox-ai/sandbox-provider";
import { sqliteCheckpointer } from "@takebox-ai/checkpoint-sqlite";

const checkpointer = sqliteCheckpointer({ file: "./sessions.db" }); // or ":memory:"

const agent = createLiteAgent({
  model: juglow(),
  modelName: "haijun-minix",
  workdir: process.cwd(),
  checkpointer,
});

await agent.send("Hello!");
// Sessions persist to sessions.db and are shared across processes on this host.

checkpointer.close(); // when you're done

API

sqliteCheckpointer({ file }) → SqliteCheckpointer (a core Checkpointer plus checkIntegrity() / close()):

• file — path to the SQLite database, or ":memory:" for an ephemeral DB.
• synchronous — "normal" (default) or "full" for stricter durability.
• busyTimeoutMs — writer wait timeout (default 5000 ms).
• integrityCheckOnOpen — run PRAGMA quick_check and fail startup if corrupt.

It implements the full Checkpointer contract — append (optimistic, expectedHead-guarded), read, head, list, delete, and truncate (so session time-travel / restore works) — and is validated against core's checkpointerConformance test suite.

See the monorepo root for architecture.