Web package
pi-roundtable-web is the owner app of a host: a page on the host’s HTTP listener where the owner talks to the agent team, answers its approval cards, stops a turn, sends files, switches yolo and long-running mode, and is notified on the phone when something waits.
It is also the console that came first, with conversation transcripts, memory notes and team status.
The plugin is a chat surface of its own, so a team of agents can live in the web alone: a host with no Discord works fully. Each active agent and group has a room, and Home is the coordinator’s. A room is its own conversation, apart from the same agent’s Discord channel.
Install and requirements
Section titled “Install and requirements”bun add pi-roundtable-web pi-roundtableUse Bun 1.4.4 or newer and pi-roundtable >=0.50.0 <0.51.0.
The app runs on the machine that owns the host data directory, and keeps its keys and files under <dataDir>/web/.
It needs an agent team (agents in the configuration), and authentication is mandatory: choose none, password, or a verifier such as Cloudflare Access.
Install the app and receive notifications over HTTPS.
import { cloudflareAccess, webConsole } from "pi-roundtable-web";
export default { // ...your roundtable settings, with `agents` and no `discord` if you like... plugins: [webConsole({ verifier: cloudflareAccess({ teamDomain: "example.cloudflareaccess.com", audience: process.env.CONSOLE_ACCESS_AUD ?? "", email: "owner@example.com", }), origin: "https://app.example.com", })],};Open https://app.example.com/console/; the page is the app.
The owner app
Section titled “The owner app”| Where | What it does |
|---|---|
| Rooms | Home first, then agents, groups, and dispatch threads, with badges for working, a card waiting, yolo, and long-running. A thread is a card; swipe a finished one to the right, hold it, right-click it, or press Delete on it to clear it from the list, with Undo for a few seconds. The room list’s menu, and each folder’s, can mark everything read and clear every finished thread at once, again with Undo. |
| A room | Messages with the author’s character, Markdown, files, a live progress strip, a composer with upload and Stop. |
| Cards | Approvals with details, questions, questionnaires, and the card at a turn’s time limit, answered in the room by any owner. |
| Agent profile | Name, prompt, model, thinking level, and the character creator. |
| Schedules | The team’s schedules, with a confirmed cancel. |
| Table | A round table that is a council: one agent group, at most eight members, at the podiums, with the group’s room in a dialogue box under it. A sheet with a tick list edits the group in place or saves the ticks as another council. Host rooms are not seated for owners; they are in the room list. A member or an admin gets it only where the host names it for their tier: it then seats the host rooms they may list, eight at most. |
| Files | The knights’ workspace: a tree, files highlighted by CodeMirror, and an editor whose saves check that a knight did not change the file meanwhile; new, rename and delete (to a restorable trash). |
| Settings | Color scheme and look, install, notifications for this device, and Log out. |
The Files pane shows the agents’ working directory and scratch directory (and the workspace.roots you add) to the owner only. Every save is checked against the hash the file was read with, .git is read-only, symlinks that leave a place are never opened, and the editor’s code loads only when a file is opened. The README has the full rules.
The table is a 3D scene where the browser has WebGL and an SVG table where it has not; add ?nogl to the page address to see the SVG one.
Seat names are drawn at 11 px or more; where a canvas is too small for that, the seats are listed as buttons under it.
A turn waits cardGraceSeconds (120 by default) for a card; then it goes on without the answer, and the card stays open for a day.
An answer given later starts a new turn in the room.
Files of any kind up to uploadMaxBytes (100 MiB by default) are streamed to disk and given to the agent; a Cloudflare free plan caps a request body at 100 MB.
Yolo and long-running mode
Section titled “Yolo and long-running mode”The room menu has two switches, kept per room and across restarts.
Yolo approves the held calls a rule allows, without a card, and writes a line in the room for each.
It never approves for a webhook or report turn, a call with named approvers, or a card that is the speaker’s alone, and the destructive classes (sudo, rm, disk, power, services, docker, firewall, packages, force push, hard reset, gh, crontab) still ask.
A plain git push and a write outside the workspace are approved, and a push to main may deploy; list shell.push in autonomy.yolo.card of the host configuration to make it ask.
Question cards and the timeout card still come in yolo, but they wait shorter (30 seconds and one minute by default) and an unanswered one does not stop the work: the agent goes on with its own best choice and says what it assumed, and the timeout card continues the turn by itself up to the long-running cap.
Long-running lets a turn go past its time limit, up to autonomy.longRunning.maxSeconds (four hours by default), then it asks on a card or aborts.
A banner shows while either is on.
A temp knight’s room follows the modes of the conversation that made it, live: its banner says where they come from, and they are switched there.
The core guide lists the classes and the guardrails.
Agents are drawn as composed characters.
The page has a Modern look and a Camelot look (parchment by day, a night castle by night, gold rules, shield frames, wax seals), each in light and dark, picked per device in Settings.
appearance.look sets the host’s default.
The chat home
Section titled “The chat home”appearance.home: "chats" opens the app on a chat list instead of the arranged room list; hosts that leave it out keep the room list.
The pinned rooms are big figures on top (Home first, with a star), the folders are chips that filter one list of the other rooms by latest activity, and one collapsed row leads to the hidden rooms and the archive.
A room can be hidden from its menu: it keeps answering, running schedules and pushing, and only leaves the home and the switcher; the owners share the hidden rooms like the pins (PUT api/rooms/<key>/hidden).
Everything else (arranging, schedules, files, settings) is behind the grid button, as a sheet on a phone and a popover on a wide screen; there is no tab bar or rail, and from 1024 px the home is a 380 px column beside the open room.
Dispatch threads and temp knights are reached from a control in their room’s header.
Incoming webhooks
Section titled “Incoming webhooks”A permanent knight’s room takes JSON posts from outside, as a Discord webhook’s post in its channel does: POST <mountPath>/hooks/<id>/<token> with { "content": "...", "username": "..." } (or any JSON, shown as a fenced block, at most 16 KB, 30 posts a minute) shows in the room marked Webhook and starts the knight’s report turn, as untrusted input.
The path needs no session, so a sign-in proxy must let <mountPath>/hooks/ through; webhookOrigin names a separate public hostname for the URL.
The owner makes and revokes webhooks in the knight’s sheet (More) or, for every knight at once, on the Webhooks page (#/webhooks, the pane webhooks; a host with an explicit panes list adds it), and the knight with webhook_create, webhook_list and webhook_revoke, for its own room only.
The URL is shown once and only the token’s hash is stored.
Install on a device and notifications
Section titled “Install on a device and notifications”The app is a PWA: a manifest scoped to the mount, a service worker that keeps the shell and never data, and icons (icons.dir replaces the shipped set). The tab icon is the round-table mark by default, and the manifest and icons answer without a session so the sign-in page and link previews show them.
Install it from the browser’s Install option or Settings; on iPhone and iPad use Share, then Add to Home Screen, and open it from there.
Web Push wakes a device while no page of that owner is in view: when a card opens (“Card waiting”, or “Long-running cap reached”), when an agent posts on its own, and for a notice the host sends.
Each owner turns it on per device in Settings, and can remove a device there.
Set push.subject (a mailto: address or an https: URL) unless origin is https; the VAPID keys are made at the first start in <dataDir>/web/vapid.json, and the file must outlive restarts.
Endpoints must be https on an allowed push service, and push.endpointHosts adds more.
With push.preview off a notification carries no message text.
From 23:00 to 08:00 on the console’s time zone an agent’s post and a notice are not pushed, while a card still is; push.quietHours ({ start, end } as HH:MM, or false) changes the window, and Settings shows it read-only.
Configuration
Section titled “Configuration”| Option | Default | Purpose |
|---|---|---|
auth |
required, or verifier |
{ mode: "none" }, { mode: "password" }, { mode: "verifier", verifier }, or { mode: "oidc", ... }. |
verifier |
none | Shorthand for the verifier mode: cloudflareAccess(...) or a custom function. Giving both throws. |
origin |
required | Browser-visible scheme and host. Writes must send this exact Origin. |
webhookOrigin |
origin |
Scheme and host an incoming webhook’s URL starts with, when the public hook hostname differs from the console’s. |
ownerId |
primary owner | Deprecated: the principal a verifier that reports no actor stands for. |
dataDir |
./data |
Host data directory: sessions/ and web/. |
mountPath |
/console |
Route prefix. |
listener |
public |
HTTP listener that serves the app. |
routing |
hash |
path preserves mount-relative page links and history navigation. |
admission |
owners |
owners lets in only owners; access lets in everyone IDENTITY admits on the surface (owners, admins, members). See Members and the gate. |
modes |
on | false leaves out the yolo and long-running switches; PUT api/rooms/<key>/mode answers 404. |
panes |
rooms, table, workspace, overview, schedules, conversations, notes, presets, webhooks |
Ordered subset of those panes plus skills and connectors; presets lists every knight’s temp-knight presets, webhooks every knight’s incoming webhooks; schedules, table, workspace, presets and webhooks need rooms, and workspace needs a place to show. An explicit list is kept as written. With admission: "access" the default adds profile, and { owner, admin?, member } chooses per tier; of the owners’ panes only table may be named for a member or an admin (with that tier’s rooms). |
workspace |
the agents’ directories | What the Files pane shows. workspace.roots adds places, each with workspace.roots.id, workspace.roots.label, workspace.roots.dir and workspace.roots.writable (false unless set); workspace.agents and workspace.scratch set to false leave the agents’ working or scratch directory out. A dir that is or contains dataDir stops the start. |
surface |
app |
Key prefix of the app’s rooms. Changing it starts every room over. |
cardGraceSeconds |
120 |
How long a turn waits on a card, above 0 and at most 3600. |
uploadMaxBytes |
100 MiB | Largest file one person uploads, 1 byte to 4 GiB. |
uploads |
{ keepDays: 30 } |
uploads.keepDays: days a stored file of the app’s agent rooms is kept, 1 to 3650. A host kind’s own retention.fileDays decides for its rooms. |
push |
on with an https origin | Web Push; keys below. |
icons |
shipped icons | { dir }: a directory of the five install icons. |
appearance |
{ look: "modern", home: "rooms" } |
{ look, home }: appearance.look is modern or camelot; appearance.home is rooms (the arranged room list) or chats (the chat list). |
title |
Roundtable |
Page heading, <title> (in the served HTML), og:title, and installed app name. |
description |
derived from title |
<meta name="description"> and og:description, for search results and link previews. |
presentation |
English | { locale, messages } controls language, date formatting, and wording; English source strings are dictionary keys. A zh-TW locale uses the built-in Traditional Chinese (Taiwan) wording, and messages words single keys over it. |
features |
none | Object or public setup-context factory for party status, schedule counts, cleanup, skills, and connectors. |
relayNotes |
remote MCP relay note | Prefixes removed from relayed messages before display. |
exclude |
none | Predicate (key, record?) for conversations the console must not list or read; record is what the registry holds of it. |
assetDir |
package dist/ |
Built page directory; set this only in tests. |
| Key | Default | Purpose |
|---|---|---|
auth.mode |
required | none, password, verifier, or oidc. |
auth.trustNetwork |
false |
none only: allow a TCP listener that reaches beyond this machine. |
auth.passwordEnv |
ROUNDTABLE_WEB_PASSWORD |
password only: the variable that holds the password, at least 12 characters. |
auth.sessionDays |
30 |
password only: how long a login lasts, 1 to 365. |
auth.principal |
primary owner | none and password: the principal the session speaks for. |
auth.verifier |
required for the mode | verifier only: the request verifier. |
auth.issuer |
required | oidc only: the provider’s exact iss, an https URL. |
auth.discoveryUrl |
<issuer>/.well-known/openid-configuration |
oidc only: where the endpoints are read at start. |
auth.clientId |
required | oidc only: the client id; the redirect URI is <origin><mountPath>/auth/callback. |
auth.clientSecretEnv |
none | oidc only: the variable holding the client secret; left out means a public client with PKCE. |
auth.scopes |
openid, profile |
oidc only; offline_access is refused. |
auth.subjectClaim |
sub |
oidc only: the claim that names the person. |
auth.nameClaim |
name |
oidc only: the claim for their name. |
auth.rolesClaim |
roles |
oidc only: the claim whose values become app:role:<name>; false reads none. |
auth.check |
none | oidc only: decides from the claims whether a token is acceptable. |
auth.endSession |
false |
oidc only: whether Log out also signs out at the provider. |
auth.reauthHours |
never | oidc only: ask the provider again after this many hours. |
auth.storeClaims |
none | oidc only: id_token claims kept with the session. |
auth.onSessionVerified |
none | oidc only: (principalId) => void, called when a request or socket proves a live session (once per session per five minutes). |
push.preview |
true |
Whether a notification shows the first 120 characters. |
push.quietHours |
{ start: "23:00", end: "08:00" } |
When an agent’s post and a notice are not pushed, as HH:MM times on the console’s time zone; cards always are. false turns it off. |
push.endpointHosts |
none | Extra push-service hosts; a leading *. allows subdomains. |
push.tiers |
["owner"] |
The tiers whose people may subscribe and receive push. |
push.subject |
origin if https |
The VAPID contact: a mailto: or https: URL. Push is off without one. |
push.sender |
"internal" |
Who signs and sends a push: this process, or { external: { publicKey, subscribePath? } }, a sender process you run that holds the VAPID key so the app never does. |
push.content |
"full" internal, "none" external |
What leaves the app for a push: a title and a preview ("full"), or only the kind, a tag and a count ("none"). |
push.transports |
none | Names of the transports besides web-push that the sender carries, such as slack; a notice’s via may name only these. |
onboarding.links |
none | Maps a provider to "required" (gates the app) or "nudge" (only asks); each needs a LinkProver registered through WEB_APP. |
onboarding.push |
"off" |
"required" or "nudge" asks the person to turn push on and receive a test notification. |
onboarding.pushWaiver |
false |
Lets a person skip a required push step. |
Notices and an external push sender
Section titled “Notices and an external push sender”A notice waits on one person. A host raises it with Notices.raise and an open target, { room, message? } or { page, query? }, and takes it back with Notices.resolve. Its tag is the dedupe key, the push tag and the acknowledgement key, and the people the notice is for can see it, so put no private id in it. It shows in the bell and on the app icon, and a normal one waits in the bell during the person’s quiet hours while an urgent one rings. Tapping a notice or a notification opens exactly that room or page, with the app open or closed.
What a person owes before the app opens is set with onboarding (links, push and pushWaiver, above).
The profile page lists the accounts a person linked, lets them link or unlink the ones the host’s LinkProvers allow, choose which account names them (Shown as), and set their quiet hours.
With push.sender: { external } the app holds no VAPID key. It queues each push in web_push_outbox, and a process you run with runPushSender from pi-roundtable-web/push-sender signs and sends it through its transports, and can serve the subscription routes at subscribePath. Those routes answer only with the app’s session cookie, and a request other than GET must carry exactly the console’s Origin.
Members and the gate
Section titled “Members and the gate”admission: "access" lets in everyone the host’s IDENTITY admits on the app’s surface, with auth set to oidc (or a verifier that reports who signed in).
A linked person is only read (IDENTITY.peek); an unlinked one is admitted as a new principal only where access.provisioning.app is admitted.
The facts are partial, so signing in here never lowers a tier recorded elsewhere. A disabled principal, or one the rules give no tier, gets 403.
One table in src/authz.ts decides every request before a handler sees it, and a route not in it answers 404 to everyone.
Owners get the agent rooms, the overview and the rest of the owners’ panes; a member gets their own conversations, notes and schedules, the host’s rooms and pages, and their profile.
A member’s socket receives nothing from an agent room, not as it happens and not when it connects, and a card is answered only by its own audience.
A member’s or admin’s round table, where the host names it, seats only the host rooms the kinds let them list: a seat is lit by its room’s own frames, which reach the socket only for a room they may read, and a tap opens the room’s page, where the kind’s access decides what they may write.
A required onboarding step closes the app on it: only the profile, settings and the pages that finish the step answer, until the last one is done.
A link may carry ?next= with profile, notices, settings, room:<key> or p:<page>; any other value is dropped.
OpenID Connect signs in with the authorization code flow and PKCE, checks the id_token once at the callback, and keeps its own server-side session in web_sessions: a random id in an HttpOnly cookie, of which only the SHA-256 is stored. The session ends after sessionDays without a visit; Log out deletes it. reauthHours makes the provider vouch again, silently when it can (an open socket is closed as signed out once its session is past it), and storeClaims keeps named claims with the session. onSessionVerified(principalId) hears a live session at most once per session every five minutes, so a host can count a person who only has the app open as present; an error it throws is logged, never failing the request.
Authentication and the threat model
Section titled “Authentication and the threat model”| Mode | Who is the owner | Use it when |
|---|---|---|
verifier |
The person the verifier reports, linked to an owner. | A proxy such as Cloudflare Access signs people in. The only mode an agent on the host cannot forge. |
password |
The primary owner, after the password. | The app is reachable from the internet with no signing proxy. |
none |
The primary owner, whoever reaches the listener. | Only the owner reaches the listener: a unix socket, or loopback TCP. |
oidc |
The person the provider reports, by an identity IDENTITY links to a principal; with admission: "access", members and admins too. |
People sign in with your own OpenID Connect provider. |
password serves a login page with no script, waits a second after each failure, locks every login for the rest of 15 minutes after ten failures (a global limit, because a client address behind a proxy is not trustworthy), and sets a signed HttpOnly, SameSite=Strict cookie that a new password invalidates.
none must be written out, warns at every start, and refuses a TCP listener that is not loopback unless trustNetwork is true.
An agent whose shell runs as the host’s user can reach whatever that user reaches.
With none it can call the app as the owner over the socket, approve its own held actions, and turn yolo on; with password it can read the password and the session key.
Both resist the network, and neither resists a compromised agent.
Only a verifier does, because the agent cannot forge a signed token.
On a host whose agents run commands, keep Cloudflare Access (or another signing proxy).
The built-in cloudflareAccess verifier checks the signed Access token, team, audience, and allowed email.
A custom verifier that trusts a proxy header is only safe if clients cannot reach the listener directly and the proxy strips client-supplied copies of that header.
Every API, SSE, WebSocket, page, and static asset is authenticated before data is read, writes need the exact Origin, and the page sends no CORS headers.
Agent output is Markdown without raw HTML, and stored files are served as downloads under a sandbox policy.
Transcripts contain tool arguments and results, so secrets handled by tools may appear there; use panes or exclude to narrow what is exposed.
Host rooms, pages and cards
Section titled “Host rooms, pages and cards”A host plugin that is not an agent can own rooms in the app, such as a support inbox with one room per email thread. It lists WEB_APP in requires and calls registerRoomKind, registerPage from setup. The host types (WEB_APP, WebApp, HostRoomKind, HostPage, HostCard, Viewer, OpenTarget, ActionResult, LinkProver, OnboardingStep, Notices) are exported from pi-roundtable-web. Keep the WebApp object and read rooms, notices, pages, onboarding and push lazily: they throw until the plugin has started, and notices.onAck works only after start. HostRoomKind.buttons may return a promise.
- Access is the kind’s
access(viewer, id), asked on every read, frame, send, card answer, upload and file;undefinedis a404. It answers what the person may do: read, send anoteor aturn, press buttons. - Messages are posted with
app.rooms.postby an author kind:external(plain text, shown with the host’s label such as “Customer”),member,assistantornotice(Markdown).referencefinds a message again;editandremovechange it. - Recent messages:
app.rooms.context(room, { limit?, messageChars? })gives a room’s recent messages as the blockCHANNEL_CONTEXT.readgives a turn ({ messages, text }): what was said since the assistant last posted, the newestlimitof it (default 15, at most 100), an outsider’s words markedexternal, notices left out. For a turn that starts from a room’ssendhook, where no message addressed the assistant. It marks nothing handed over, so a retry reads the same. - Cards carry a title, body, tone, state, links and buttons; a button may open a form (text, textarea, url, select with
initialandsearch, multiselect) checked on the server before the kind’sactruns. Buttons show only while the card isopen. Approval and question cards of an agent keep the agent’s own prompt scope. - Writing: where a viewer may send both a
noteand aturn, the room shows one@AItoggle over the composer’s bar (off = a note for the room’s people only, on = the agent answers) and the box’s hint follows it; a viewer who may send one way only has no toggle. A kind words it withsendWording: { note?: { placeholder }, turn?: { label, placeholder } }, text only, a label cut to 40 characters and a placeholder to 100. Typing@AIas the first word of the box does the same as turning the toggle on: the toggle shows on while it is there, and the page sends the message as an explicitturnwith the token cut from the text. Only typing counts;@AIlater in the text, in pasted text or in an address such asa@ai.comis plain text. The server never reads the text for it, so anoteframe that starts with@AIstays a note. A room without the toggle takes it as plain text. - Icons: a page or a kind may give
icon, one ofHOST_ICONS(typeHostIconName):chat,link,activity,users,megaphone,qr,settings,bell,file,list,shield,lock,sparkle. A page’s icon shows in the navigation, a kind’s beside its section in the room list; a name outside the list shows the default. - Links and images:
app.rooms.link(room, messageId?)gives the address that opens a room and highlights a message;shows a PNG, JPEG or WebP saved withsaveFileorapp.pages.saveAsset, to those who may see the room or page. - Pages at
<mount>/p/<id>are built from Markdown, list, form and card sections;visible(viewer)is asked every time andapp.pages.changed(id?)makes viewers fetch again. - Retention: a kind’s
retention: { textDays, fileDays }deletes its messages, author names, cards and files, counted from each message’s time (a card’s from when it was first posted). A card markedkeep: trueincardorupdateCard, such as a ticket’s pinned card while the ticket is open, is skipped by the sweep for as long as the host passes it. - Read marks: the app keeps how far each person has read in every room (host and agent rooms alike). The list and drawer show unread counts, a room opens with a “new messages” divider, and each message shows who has read up to it (“Seen by 2”, with pictures).
The room, list and page code loads when first opened; the app’s first load does not grow.
Host integrations
Section titled “Host integrations”Overview also lists stored owner workspaces and outside-agent conversations.
features.party supplies separately stored party channel status through contains(key) and list() returning PartyView[].
features.schedules.count(key) adds workspace schedule counts.
features.cleanup supplies startFresh(key) and deleteConversation(key); the latter returns deleted or busy.
The package validates key shape, ownership, exclusions and stored existence before invoking cleanup, shows confirmation dialogs, and returns 409 for a busy delete.
Without the cleanup hook, conversation data remains read-only.
features.skills.catalog() supplies source, description, groups, carriers and missing-file status.
read(name) returns the selected catalog entry’s { frontmatter, body }, never a request-selected path.
Set errorDetail: true to show the missing-file text or read error in the API response (cut at 300 characters) when the host’s reasons are safe to show.
features.connectors supplies gateways(), servers(), usedBy(server) and an optional safe adminUrl.
Skills and Connectors fail startup when enabled without their hooks.
A feature factory receives public plugin setup context so the host can bind existing stores without renaming tables, grants or session paths.
Declare any extra service dependencies on the host wrapper’s requires.
Application-specific wording belongs in presentation, not a cloned server or React page.
For the full threat model, the Cloudflare setup steps, the custom-verifier example, the WebSocket protocol, and option validation, see the pi-roundtable-web README.