@agent-os/backend-node-postgres

Purpose

Node/Postgres production backend interpreter for agentOS backend-protocol semantics. It provides the second production backend proof for backend-neutral status alongside the Cloudflare Durable Object backend.

Invariant

The backend interprets the same backend-protocol algebra as the Cloudflare DO backend. Ledger facts live in Postgres, and due_work is a mechanical scheduling and claim buffer, not an audit source.

Concurrent drainers claim due work with Postgres row ownership: FOR UPDATE SKIP LOCKED, claim tokens, and claim deadlines ensure one due dispatch retry is acquired at most once across processes. Dispatch retry, schedule firing, resource reservation, quota grant, telemetry diagnostics, and replay gates must remain backend-neutral projections of the shared protocol.

The package does not own protocol vocabulary. Dispatch payloads, delivery receipt settlement, retry policy, resource/quota projection shapes, and replay snapshot vocabulary stay in @agent-os/backend-protocol.

The test harness may start a temporary Docker Postgres instance when AGENTOS_NODE_POSTGRES_DATABASE_URL is not set. That harness is not public API.

Minimal Usage

Create a backend with an explicit Postgres database URL and binding ref, then initialize its schema before use.

import { NodePostgresBackend } from "@agent-os/backend-node-postgres";
import { bindingMaterialRef } from "@agent-os/kernel/material-ref";

const backend = new NodePostgresBackend({
  databaseUrl: process.env.AGENTOS_NODE_POSTGRES_DATABASE_URL!,
  bindingRef: bindingMaterialRef({
    provider: "node",
    bindingKind: "postgres",
    ref: "agent",
  }),
});

await backend.initialize();

Verification

cd packages/backends/node-postgres
bun run test:runtime