The web chat UI

A complete browser chat client - sidebar, streaming, approvals, SQLite store.

The web chat UI

A gateways/*.bx entry with exposes: "webui" ships a complete browser chat client for the agent - a conversation sidebar, streaming with reasoning and tool calls, human-in-the-loop approvals, per-visitor theming, and a real SQLite store behind it.

It lives under gateways/ because that is where exposures are declared, but it is a subsystem in its own right, which is why it has its own page.

// gateways/chat.bx
class {
	function configure() {
		return {
			exposes     : "webui",
			path        : "/chat",
			apiKeyEnvVar: "CHAT_UI_API_KEY"   // optional - see Securing the API
		};
	}
}

That generates a static <path>/index.html (served directly - no route needed) plus a dedicated API under <path>/api, backed by a generated handlers/ChatUi.bx and models/ChatDb.bx.

The UI is dependency-free vanilla HTML/CSS/JS - no Bootstrap, AlpineJS or Vite build step - and is pre-built and vendored inside BX Agents itself: bxAgents build never runs npm install/npm run build, and a generated project never needs Node or npm installed at all. Everything the page needs is inlined into the single generated index.html.

That constraint is about the build, not about scope. The page is a full client: conversation sidebar, streaming with reasoning and tool calls, approvals, compaction, server-side theming. What is genuinely still missing is listed under What is not here yet.

The page talks to its own generated <path>/api route via POST <path>/api/stream (Accept: text/event-stream), using fetch() + a manual ReadableStream reader - not the browser's EventSource, which can't POST or set custom headers, both needed here.

event: chunk
data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"Ray","reasoning":"...","tool_calls":[...]}}]}

event: done
data: [DONE]

Because the whole envelope arrives, reasoning and tool calls are already on the wire with no extra endpoint needed: delta.reasoning (normalized across every provider by bx-ai) renders as a collapsed "Thinking" strip, and delta.tool_calls as collapsed per-call chips. Tool-call arguments stream as partial JSON fragments keyed by index, so the page accumulates per index rather than assuming any single chunk holds a complete call.

What a streaming turn actually looks like

sequenceDiagram
    autonumber
    participant B as browser (generated index.html)
    participant H as handlers/ChatUi.bx
    participant A as the agent
    participant D as models/ChatDb.bx (SQLite)

    B->>H: POST /chat/api/stream, Accept: text/event-stream
    H->>D: resolve the conversation for this session
    H->>A: agent.stream( ... )
    H-->>B: event: thread - the threadId, sent BEFORE the first chunk
    loop for every chunk bx-ai emits
        A-->>H: a full normalized bx-ai envelope
        H-->>B: event: chunk - choices[0].delta.content / .reasoning / .tool_calls
    end
    H->>D: persist the turn
    H-->>B: event: done - [DONE]

The thread event goes first because a response header cannot be read before the body starts arriving, and the page needs that threadId to be able to POST /cancel mid-turn.

The generated API

A webui entry mounts twenty actions under <path>/api, served by a generated handlers/ChatUi.bx:

Every one is scoped by ColdBox's getUserSessionIdentifier() as the userId. The first three keep toAi()'s exact shape and wire format.

threadId is server-authoritative: taken from the request when supplied, minted otherwise, and always echoed back - as an X-Thread-Id response header on /invoke and /batch, and as a thread SSE event sent before the first chunk on /stream (a header can't be read before the body starts arriving). That's the same contract ColdBox 8.1's own toAi() adopted, so a client written against one works against the other.

/clear and /compact are both careful about scope. /clear goes through each memory's own clear( userId, conversationId ) rather than AiAgent.clearMemory(), which takes no arguments and would wipe every visitor's history; /compact goes through summarize( config, userId, conversationId ) for the same reason. Compaction replaces this conversation's older messages with an AI-written summary and keeps the most recent few, touching nothing outside the caller's (userId, conversationId) pair.

// Agent.bx - what makes /compact functional
memory: {
	type            : "cache",
	summaryProvider : "openai",
	summaryModel    : "gpt-4o-mini",
	summaryThreshold: 10
}

Users and sign-in

By default the web UI has no accounts and no gate — it is open, and every visitor is anonymous. That is the zero-ceremony bxAgents serve experience, and it is not a deployment posture. Declaring users on a webui entry turns on a real sign-in gate backed by cbauth and the same SQLite store everything else uses.

Without accounts, the UI is one shared workspace

There is no per-visitor identity, on purpose. Every visitor to an accountless web UI reads and writes the same conversations, preferences and agent memory — whoever can reach the page sees everything in it.

That is the point of running without accounts rather than an oversight: an open UI is a single shared tool (a laptop, a trusted internal box), not a multi-tenant service. Handing each browser its own slice would only fragment one workspace into per-browser copies nobody asked for, and any client-side id doing the fragmenting would be forgeable anyway.

// gateways/chatUi.bx
users : [
    { username: "ada",   passwordEnvVar: "ACME_ADA_PASSWORD", displayName: "Ada Lovelace" },
    { username: "grace", passwordHash: "pbkdf2$210000$...",   displayName: "Grace Hopper" }
]

Passwords are never written in config

An account names the environment variable holding its password (passwordEnvVar), or carries an already-hashed value (passwordHash). A literal password key is a build error, not a warning — silently ignoring it would leave you believing you had set a password when you had only committed one.

A passwordHash is safe to commit precisely because it cannot be reversed. Generate one with the same hasher the app uses:

bxAgents hash-password --password="correct horse battery staple"

What sign-in changes

Everything user-scoped re-keys to the real account. The generated handlers/ChatUi.bx resolves identity from cbauth directly, in one method (resolveUserId()), and agent memory, the conversation index, preferences and pending-run ownership all key off its return value.

It reads cbauth rather than ColdBox's identifierProvider setting deliberately: a closure declared in the coldbox config struct never reaches configSettings — verified in a real boot, in both the documented literal shape and as a later assignment — so anything leaning on that setting was silently getting a session id instead.

The practical difference: conversations and preferences follow the person across browsers and devices, and clearing cookies no longer creates a brand-new "user".

Lifecycle

Accounts are reconciled from config on every boot, in this order: the schema interceptor migrates, the seeder writes accounts, then the login gate starts enforcing.

• Adding a user to config creates them.
• Changing their password updates it. The seeder re-hashes only when the configured password no longer matches what is stored, so an unchanged password costs one verification rather than a fresh hash.
• Removing them from config deactivates the account rather than deleting it. Their conversations reference their id, so deleting the row would orphan that history instead of revoking access. They can no longer sign in; their data stays intact and returns if the account is restored.
• A passwordEnvVar whose variable is unset skips that account entirely and logs a warning to webui-auth. This fails closed on purpose — creating the account with an empty password would be far worse than it not existing.

What this is not

This is a fixed roster of operator-provisioned accounts, not a user-management system. There is no self-registration, no password reset, no roles or permissions, and no per-user rate limiting or spend cap. If you need federated identity instead, edit resolveUserId() in the generated handler to return your own authenticated principal — the rest of the web UI neither knows nor cares where the id came from.

Human-in-the-loop

When the agent pauses for approval, the stream emits a middleware_stop chunk that carries no detail. The page therefore asks GET /pending?threadId= what is being requested, renders it with Approve / Reject, and answers via POST /resume - which streams the continuation of the same turn, so the outcome lands in the conversation rather than starting a new one.

decidedBy is filled from the session server-side, never from the request body: who approved something is exactly the kind of claim a caller should not get to make about itself.

History and reload

The transcript lives in the DOM; the conversation lives in the agent's memory. Without rehydration a reload shows an empty screen while the agent still remembers everything - so the page would look blank and then answer follow-ups about messages the user cannot see. On load the page therefore calls GET <path>/api/history and replays the stored messages (markdown and all), falling back to the welcome message when the conversation is empty or the fetch fails.

New starts a fresh conversationId. It does not delete anything - the previous conversation stays on the server under its own id and appears in the sidebar, which is what the conversations table exists for.

What the page does

The shipped page is a real chat client, not a demo shell. It reads GET /info first and shapes itself to what the server actually reports, so a control only appears where the capability exists.

Recovery matters more than it sounds. The last-opened conversation is remembered in localStorage, but the conversations themselves live on the server. If that id no longer exists — deleted in another tab, or a fresh store — the page falls back to the newest remaining conversation instead of rehydrating into an empty screen with no active row.

Narrow screens get a real layout rather than a squeezed one: under 40rem the sidebar overlays the transcript instead of stealing its width, and prefers-reduced-motion is honoured.

The SQLite store

Every webui project gets a SQLite database. It isn't optional and there's no flag to turn it off.

The reason is a real gap, not a preference: bx-ai's IAiMemory has no enumeration API. It's a per-(userId, conversationId) bucket — you can read, write and clear one, but nothing in it answers "which conversations does this user have." A conversation list, per-user preferences, and anything else relational needs real storage alongside the memory, not inside it.

The datasource is registered in Application.bx and the grammar is pinned in config/ColdBox.bx:

// Application.bx (generated)
this.datasources[ "bxagents" ] = {
	"driver"  : "sqlite",
	"database": expandPath( "./data/chat.db" )
}
this.datasource = "bxagents"   // NOT this.defaultDatasource - see below

// config/ColdBox.bx (generated)
qb : {
	defaultGrammar : "SQLiteGrammar@qb",
	defaultOptions : { datasource : "bxagents" }
}

Both are optional to override, per entry:

An absolute database.path fails the build: it's resolved with expandPath() inside the generated app, so an absolute path silently escapes the app directory and breaks a packaged .bxa deploy.

Schema is versioned and forward-only. ChatDb.migrate() records what it has applied in a bxagents_schema_version table and applies only what's newer, so booting against an existing store is a no-op. v1 creates conversations and preferences. Evolve it by adding a new applyV<n>() and bumping SCHEMA_VERSION — never by editing a migration that has shipped, because SQLite cannot modify or drop a column and qb's SQLiteGrammar throws UnsupportedOperation rather than pretending otherwise.

The grammar is the only SQLite-specific piece. Everything else goes through qb, so pointing this at Postgres or MySQL later is a grammar and datasource change rather than a rewrite.

Conversations and preferences

These are what the SQLite store exists for, and both are scoped by the same server-derived userId as everything else.

Conversations. Every turn through /invoke, /stream or /batch records itself against the index: the row is created on first use, updatedAt moves, and the first user message becomes the title (collapsed to one line, truncated to 60 characters) unless one is already set — so a rename is never silently undone by the next turn. messageCount is a display counter, bumped by two per turn; a turn that dies midway can leave it one high, and /clear resets it. The agent's own memory remains the authority on what was actually said.

/conversations/delete removes the index row and clears the agent's messages for that conversation. Dropping only the row would leave the conversation invisible while still sitting in the model's context the moment anyone reused the id.

Preferences. Server-side rather than localStorage, so they follow the identity instead of the browser. Point identifierProvider at a real authenticated principal and a visitor's preferences follow them across devices with no change to the generated code.

Branding and theming

Every key below is optional - the entry works with just exposes and path.

theme maps directly onto the page's CSS custom properties: accent, accentFg, bg, fg, muted, border, surface, inputBg, bubbleUser, bubbleUserFg, bubbleAssistant, bubbleAssistantFg, bubbleError, reasoningFg, reasoningBg, toolFg, toolBg, radius, radiusSm, font, fontMono, fontSize, maxWidth. A nested theme.dark block overrides any of the same tokens for dark mode. An unknown token fails the build rather than being silently ignored, so a typo surfaces immediately instead of leaving you wondering why your brand color never showed up.

// gateways/chat.bx
theme: {
	accent : "0f766e",
	radius : "10px",
	font   : "Inter, system-ui, sans-serif",
	dark   : { accent : "rgb(45, 212, 191)" }
}

For anything the tokens don't cover - custom fonts, layout, per-element rules - drop a resources/webui/theme.css into the project. It's inlined last into the page's <style>, so it beats both the shipped defaults and the theme tokens; and being a real .css file, ordinary #rrggbb hex works there normally. (A literal </style in that file fails the build, since it would terminate the page's style block early.)

Conversation identity: the session IS the user identifier

Every memory an agent holds is keyed by (userId, conversationId) - and an agent can hold several at once (AiAgent's memories is an array; loadMemoryMessages() iterates all of them with the same pair). AiAgent.run()/.stream() fall back to "" for both when nothing supplies them, so with no server-side identity every visitor lands in one shared bucket, regardless of which memory types are configured.

The fix is identity, not memory type. A project with a webui exposure therefore gets:

1. Session management on in the generated Application.bx - this.sessionManagement = true, this.setClientCookies = true, a 60-minute sessionTimeout. Cookies are load-bearing: no cookie, no session id.
2. Its own handlers/ChatUi.bx, which passes ColdBox's getUserSessionIdentifier() as the agent's userId on all three runner shapes - invoke, stream and batch.

// handlers/ChatUi.bx (generated)
private string function resolveUserId() {
	return controller.getUserSessionIdentifier()
}

Delegating to ColdBox rather than reading session.sessionId directly buys three things: the id is prefixed per application, it falls back through URLToken/CFID if a session is somehow unavailable, and - the one that matters most - it honours the identifierProvider config setting. Point that at your authenticated principal and every memory re-keys to the real user with no change to the generated handler.

Because the identity is server-issued, scoping holds no matter which memories the project configures - one or many, window, cache, jdbc, vector, any mix.

conversationId still comes from the client, and that's deliberate: it distinguishes several conversations belonging to the same visitor - it's what the New button rotates. It is not the isolation boundary; the session-derived userId is.

No memory type is forced. Choose one (or several) per agent with a memory key on Agent.bx, same shape as checkpointer:

// Agent.bx
memory: { type: "cache", maxMessages: 50 }

A project with no webui keeps sessions off and bx-ai's own memory default - an API/gateway-only app has no browser to track, and a session there is overhead plus a cookie nobody asked for.

Reply rendering

Assistant replies render through a deliberately small markdown subset - fenced and inline code, bold/italic, links, bullet and numbered lists, headings. It is applied escape-first: the model's text is HTML-escaped before a single tag is introduced, so no model output can become live markup, and link hrefs are allowlisted to http(s)/mailto so a javascript: URL is never turned into an anchor at all.

What is not here yet

The page is complete against its own API - every route it needs exists and is exercised. These are the gaps:

See Known Limitations for what was and was not verified against a real ColdBox boot, including the parts of this page that are covered only by generator-level assertions rather than by driving a browser.