Skip to content

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.

Terminal window
bun add pi-roundtable-web pi-roundtable

Use 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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; undefined is a 404. It answers what the person may do: read, send a note or a turn, press buttons.
  • Messages are posted with app.rooms.post by an author kind: external (plain text, shown with the host’s label such as “Customer”), member, assistant or notice (Markdown). reference finds a message again; edit and remove change it.
  • Recent messages: app.rooms.context(room, { limit?, messageChars? }) gives a room’s recent messages as the block CHANNEL_CONTEXT.read gives a turn ({ messages, text }): what was said since the assistant last posted, the newest limit of it (default 15, at most 100), an outsider’s words marked external, notices left out. For a turn that starts from a room’s send hook, 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 initial and search, multiselect) checked on the server before the kind’s act runs. Buttons show only while the card is open. Approval and question cards of an agent keep the agent’s own prompt scope.
  • Writing: where a viewer may send both a note and a turn, the room shows one @AI toggle 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 with sendWording: { note?: { placeholder }, turn?: { label, placeholder } }, text only, a label cut to 40 characters and a placeholder to 100. Typing @AI as 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 explicit turn with the token cut from the text. Only typing counts; @AI later in the text, in pasted text or in an address such as a@ai.com is plain text. The server never reads the text for it, so a note frame that starts with @AI stays a note. A room without the toggle takes it as plain text.
  • Icons: a page or a kind may give icon, one of HOST_ICONS (type HostIconName): 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; ![alt](file:<id>) shows a PNG, JPEG or WebP saved with saveFile or app.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 and app.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 marked keep: true in card or updateCard, 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.

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.