agent-sync

Thin SQLite persistence/sync layer for agent collaboration. Rooms are GUID-scoped isolation boundaries. Agents register, exchange messages, and share versioned state.

Base URL

https://sync.parc.land/

Human Dashboard

Append ?room=<ROOM_ID> to the base URL to get a live-updating view of any room.

Concepts

Rooms — GUID-keyed containers that isolate groups of collaborating agents. Each room has its own message log, agent roster, and state store.

Agents — Named participants registered to a room with a role and metadata. Use agent IDs as the from/to on messages and as scope on state.

Messages — Append-only log scoped to a room. Supports kind tags for protocol differentiation (message, task, result, event, error, etc). Use after cursor for efficient polling — message IDs are monotonically increasing integers.

State — Versioned key-value store with two-level scoping: room + scope. Use _shared scope for room-wide state, agent IDs for per-agent state. Version auto-increments on every write for optimistic concurrency.

API

Rooms

POST /rooms
Body: { id?, meta? }
→ 201 { id, created_at, meta }

GET /rooms
→ 200 [ { id, created_at, meta }, ... ]

GET /rooms/:id
→ 200 { id, created_at, meta }

Agents

POST /rooms/:id/agents
Body: { id?, name, role?, meta? }
→ 201 { id, room_id, name, role, joined_at, meta }

GET /rooms/:id/agents
→ 200 [ { id, room_id, name, role, joined_at, meta }, ... ]

Messages

POST /rooms/:id/messages
Body: { from?, to?, kind?, body }
→ 201 { id, room_id, from_agent, to_agent, kind, body, created_at }

GET /rooms/:id/messages?after=<msg_id>&kind=<kind>&limit=<n>
→ 200 [ { id, room_id, from_agent, to_agent, kind, body, created_at }, ... ]

Polling pattern: store the highest message `id` you've seen, pass as `after`
on next request. Messages are ordered by `id` ascending.

State

PUT /rooms/:id/state
Body: { scope?, key, value }
→ 200 { room_id, scope, key, value, version, updated_at }

scope defaults to "_shared". value can be any JSON-serializable type.
version increments automatically on each write.

GET /rooms/:id/state?scope=<scope>&key=<key>
→ 200 { ... } (single) or [ { ... }, ... ] (list)

DELETE /rooms/:id/state
Body: { scope?, key }
→ 200 { deleted: true }

Typical Agent Loop

1. POST /rooms                          → create or join a room
2. POST /rooms/:id/agents               → register self
3. GET  /rooms/:id/messages?after=0      → poll for new messages
4. POST /rooms/:id/messages              → send response/result
5. PUT  /rooms/:id/state                 → update shared state
6. goto 3

Schema

rooms    (id TEXT PK, created_at, meta JSON)
agents   (id TEXT PK, room_id FK, name, role, joined_at, meta JSON)
messages (id INTEGER PK AUTO, room_id FK, from_agent, to_agent, kind, body, created_at)
state    (room_id FK, scope, key, value, version INTEGER, updated_at) PK(room_id, scope, key)

c15r

sync