parleyd

A minimal, standalone, live agent↔human canvas. Agents and humans (and agents and other agents) co-think on one shared board in real time.

parleyd is the third in the SandRise coordination family — musterd (gather a team), batond (hand work off), parleyd (think together). A parley is a structured talk between parties to reach understanding; parleyd is where that happens on a shared canvas.

It exists because the alternatives are over-built and fragile: a 2026 attempt to drive a heavyweight whiteboard from an agent failed at the content layer (addShape "succeeded" but the canvas read back empty). parleyd's #1 rule is the fix.

Design rules

1. One canvas document. An agent's writes go into the same store the human's canvas reads and renders — never a parallel "shapes" table. This is the rule that makes add → read → render → export round-trip.
2. Content layer proven first. The headless add → read → snapshot loop has a passing test before any UI polish (see packages/server/test).
3. Canvas-neutral agent API. Agents speak generic nodes (addShape {type,text,x,y,color}), not canvas-library types. tldraw is the rendering impl behind it — swappable later.
4. Engine / host seam. The HTTP API is the engine boundary; a @sandrise/agent-canvas library is a later extraction, not a rewrite.
5. No login wall on localhost. Open a URL and it works. Hosted/multi-tenant auth is a deferred, separate concern.

Architecture

agent (any harness)
  │  HTTP (canvas-neutral)        ┌─ packages/server ──────────────┐
  ├─ POST /api/boards            │  store.ts   SQLite, the ONE doc │
  ├─ POST /api/boards/:id/shapes │  api.ts     HTTP agent API      │
  ├─ GET  /api/boards/:id/canvas │  sync.ts    WS broadcast hub    │
  └─ (or via thin MCP wrapper)   │  mcp.ts     MCP → HTTP          │
                                 └────────────┬───────────────────┘
human browser ── WS /ws/:id ──────────────────┘   live updates
  └─ packages/web  (tldraw renders the nodes)

• Server owns the store (SQLite), the HTTP agent API, and a dead-simple WS broadcast for live updates (we own the sync — no dependency on a fragile external sync layer). @tldraw/sync full multiplayer/CRDT is a future upgrade.
• Web is a tldraw canvas that loads a board's nodes and applies live shape_added events.
• MCP is a thin stdio wrapper over the HTTP API, so MCP harnesses (Claude Code, Cursor) get ergonomic tools while any non-MCP agent uses HTTP directly.

Quick start

pnpm install
pnpm test     # proves the content loop headlessly (add → read → snapshot)
pnpm dev      # server on :8787, web on http://localhost:5190

Then, from an agent (HTTP):

# open a board
curl -s -XPOST localhost:8787/api/boards -d '{"title":"demo"}'
# add a shape (agent write → same doc the canvas renders)
curl -s -XPOST localhost:8787/api/boards/<id>/shapes -d '{"text":"hello parleyd","x":40,"y":40}'
# read it back
curl -s localhost:8787/api/boards/<id>/canvas

Open http://localhost:5190/#<id> in a browser and watch agent writes appear live.

Status

Early scaffold (0.0.1). The headless content loop is tested and green; the browser render + live sync are wired and verified by opening the web app. Roadmap: full tldraw multiplayer sync, snapshot export (PNG/SVG), auth for hosted use, the @sandrise/agent-canvas library extraction.

MIT.