Agent Checkpoint

Agent Checkpoint is dependency-free SQLite state management for long-running AI agents, coding agents, and local workflow automation. It combines agent leases, fencing tokens, durable checkpoints, and audit events in one local control plane. Independent processes get a shared way to answer four questions:

1. Who currently owns this operation?
2. Is that owner still alive?
3. Is a resumed worker stale?
4. Where should the workflow continue after a restart?

It is intentionally small: one Python package, one SQLite file, JSON output, and no hosted service.

Why it exists

Agent runs fail, machines restart, and multiple workers sometimes try to finish the same external action. A plain lock file cannot safely distinguish a current worker from a stale worker that wakes up later. Agent Checkpoint pairs expiring leases with monotonically increasing fencing tokens. A protected checkpoint write succeeds only when the owner and token still match the live lease.

This is useful for release automation, content pipelines, migrations, browser agents, scheduled jobs, and any workflow where duplicate final actions are costly.

Quick start

Python 3.10 or newer is required.

python -m pip install .
agent-checkpoint --db .state/agents.db init

Acquire a 60-second lease:

agent-checkpoint --db .state/agents.db lease acquire release \
  --owner worker-a --ttl 60

The JSON result contains a fencing token:

{
  "owner": "worker-a",
  "scope": "release",
  "token": 1
}

Save a checkpoint only if that lease is still live:

agent-checkpoint --db .state/agents.db checkpoint put deploy-v2 \
  --data '{"stage":"tests-passed","commit":"abc123"}' \
  --lease-scope release --owner worker-a --token 1

Resume after a restart:

agent-checkpoint --db .state/agents.db checkpoint get deploy-v2

Extend and release the lease:

agent-checkpoint --db .state/agents.db lease heartbeat release \
  --owner worker-a --token 1 --ttl 60
agent-checkpoint --db .state/agents.db lease release release \
  --owner worker-a --token 1

Python API

from agent_checkpoint import StateStore

store = StateStore(".state/agents.db")
store.initialize()

lease = store.acquire("release", "worker-a", ttl_seconds=60)
store.put_checkpoint(
    "deploy-v2",
    {"stage": "tests-passed"},
    lease_scope=lease.scope,
    owner=lease.owner,
    token=lease.token,
)
store.release(lease.scope, lease.owner, lease.token)

Command reference

agent-checkpoint init
agent-checkpoint lease acquire SCOPE --owner OWNER [--ttl SECONDS]
agent-checkpoint lease heartbeat SCOPE --owner OWNER --token TOKEN [--ttl SECONDS]
agent-checkpoint lease release SCOPE --owner OWNER --token TOKEN
agent-checkpoint lease show SCOPE [--include-expired]
agent-checkpoint checkpoint put WORKFLOW --data JSON
    [--lease-scope SCOPE --owner OWNER --token TOKEN]
agent-checkpoint checkpoint get WORKFLOW
agent-checkpoint checkpoint list
agent-checkpoint events [--limit NUMBER]
agent-checkpoint doctor

Set AGENT_CHECKPOINT_DB to avoid passing --db each time.

Coordination model

• SQLite BEGIN IMMEDIATE transactions serialize writers.
• A lease has an owner, TTL, heartbeat, and fencing token.
• Reacquiring an expired lease increments its token.
• A stale owner cannot heartbeat, release, or make a protected checkpoint write.
• Checkpoints use per-workflow sequence numbers and arbitrary JSON payloads.
• Every mutation produces an append-only audit event.
• WAL mode and a configurable busy timeout support multiple local processes.

Agent Checkpoint coordinates processes that can access the same filesystem. It is not a distributed consensus system and does not replace etcd, Consul, or a database-backed queue across multiple machines.

Safety notes

• Keep the SQLite database out of version control; .agent-checkpoint/ is ignored by default.
• Do not store secrets in checkpoint payloads or lease metadata.
• Choose a TTL longer than the longest expected gap between heartbeats.
• Pass the fencing token to the final state-changing operation when the target system supports conditional writes.
• An unprotected checkpoint write is available for simple resume-only uses. Use lease-protected writes when duplicate or stale actions matter.

Development

python -m pip install -e .
python -m unittest discover -s tests -v
python -m compileall -q src tests

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for private vulnerability reporting guidance.

Status

Version 0.1.0 is an alpha release. The database schema is versioned, but backward compatibility is not guaranteed before 1.0.