Web chat package
pi-roundtable-webchat is a chat network that comes as a plugin.
People an OpenID Connect provider signs in chat with the assistant from a web page or a browser extension, each in private conversations of their own.
A turn’s text and tools show as it runs, and a held tool call asks the person on an approval card.
It needs no Discord: a host whose configuration has no discord and lists webChat({ ... }) is a web-only assistant.
Start a web chat project
Section titled “Start a web chat project”npx pi-roundtable init my-desk --adapter webcd my-deskbun installdocker compose up -dcp .env.example .env # then fill it inbunx roundtable doctorbunx roundtable startThe project lists webChat({ ... }) in plugins with an OpenID Connect verifier, a top-level access whose members and admins come from the token’s roles, and one persona, assistant, whose prompt is persona/assistant.md.
The persona’s selection names its tools, so tools a later plugin adds stay out until you name them.
The host listens on 127.0.0.1:3000; serve it over HTTPS through a reverse proxy, and set CHAT_ORIGINS to the pages that open the chat.
See init --adapter web for every file it writes.
Add it to a host
Section titled “Add it to a host”bun add pi-roundtable-webchatimport { readFileSync } from "node:fs";import { oidcJwtVerifier, webChat } from "pi-roundtable-webchat";
export default { // ...your roundtable settings, with http: { port: 3000, hostname: "127.0.0.1" }... access: { admins: { roles: ["web:role:Helpdesk.Admin"] }, members: { roles: ["web:role:Helpdesk.User"] }, }, plugins: [ webChat({ verifier: oidcJwtVerifier({ jwksUrl: "https://login.example.com/keys", issuers: ["https://login.example.com/"], audiences: ["api://helpdesk"], }), origins: ["https://chat.example.com"], personas: [ { kind: "helpdesk", label: "Helpdesk", prompt: () => readFileSync("./persona/helpdesk.md", "utf8"), selection: { tools: [], groups: [] }, }, ], }), ],};It releases in lockstep with pi-roundtable and needs an HTTP listener (http in the configuration).
Every mistake in these options throws when the configuration loads, so roundtable doctor names it before the host starts.
How people connect
Section titled “How people connect”A browser asks for a one-time ticket with POST /chat/tickets and Authorization: Bearer <token>, then opens /chat/socket offering the subprotocols roundtable.webchat.v1 and ticket.<ticket>.
Another client sends the bearer token on the upgrade.
The token never travels in a URL.
Each WebSocket message is one JSON object with a type.
The client sends send, stop, approval, answer, and auth; the server answers with ready, accepted, typing, stoppable, progress, reply, failed, prompt, prompt_closed, reauth, and error.
progress shows the turn’s text and the tools it runs, never its thinking and never a tool’s full arguments; reply carries the answer in full markdown.
A REST API lists a person’s conversations, opens one, and reads its messages.
The package README documents every frame, error code, close code, and limit.
The web chat tells the model that full Markdown renders, tables included: a short guidance text is appended to the system prompt of every turn that replies in it, after the persona.
Set formatting: "…" to replace the text for a client that renders less, or formatting: false to tell the model nothing.
Security model
Section titled “Security model”- Private conversations. A conversation belongs to the person who opened it. The host’s conversation registry records that person at the first turn, and the claim checks it before every turn: only that person may list, read, write in, stop, or answer it in the web chat. The owner can still read it through the owner console, and the operator through the database and the data directory.
- Tokens. Tokens are checked on every REST call, every upgrade, and every
authframe. By default only a person’s access token passes; a token without a scope or app roles, or an app-only token, is refused. A socket closes when its token expires. - Origins.
originsis required and checked on every upgrade and every browser request. - Limits. Each person has bounded sockets, tickets, conversations opened per hour, and turns running or queued at once.
- Approvals. A held call’s card goes to the conversation’s person only, at the tier the call needs.
- Questions. The assistant can ask up to four related questions on one card, but only to a client that has declared it can show them; any other client is asked one question at a time. The package README lists the frames.
- Owner. No token claim makes anyone the owner: list owners by speaker id,
oidc:<base64url(issuer)>:<subject>.
The verifier is generic; what makes it safe is how you point it at your provider.
Read the README’s provider settings before anyone signs in: name people by a claim that stays the same across app registrations, pin your tenant, accept access tokens only, and merge issuers of one tenant only.
For Microsoft Entra ID v2 access tokens, entraV2Check({ tenant, scope, guests? }) is a ready-made check: it pins tid, requires ver "2.0" and the delegated scope in scp, and accepts only members (acct 0 or "0") unless guests: true.
For tests, pi-roundtable-webchat/testing exports testIssuer, an OpenID provider on a local port that signs tokens with sign({ claims }) and serves the JWKS at jwksUrl.
The security page covers what the rest of the host trusts.
What it does not do yet
Section titled “What it does not do yet”- Attachments: messages carry text only.
- Schedules and delegated reports: a web conversation takes no background turns, so leave
schedule_*anddelegate_taskout of a persona’sselection. - Web tools: leave
web_searchandfetch_contentout unless people may make the host fetch any address, internal ones included. - Error reports:
ops.conversationcannot name a web conversation, which only its signed-in person opens; the host does not start with one. Report to another surface’s conversation, or to an agent with Discord. - Agent teams have no web rooms.
- A person on two providers, or on Discord and the web, has two speaker ids and two memories.