Building a UI

The baseline ships no HTML. The admin-api plugin exposes JSON routes and your application owns the frontend — React, HTMX, a Slack bot, a CLI — whatever your product already is. This keeps the agent’s reach and the human’s approval surface identical no matter how you render them.

Routes (@sms/plugin-admin-api, prefix /api by default)

The ORM routes take their OpContext from createOrmPlugin({ contextOf }) (an auth plugin’s session, for example); with the default {} every request is anonymous and only the guard decides.

One round-trip: /api/rpc (createBaseline({ rpc: true, meta: true }))

Token: authorization: Bearer <adminToken> or x-admin-token. Configure it in createBaseline({ adminToken }). When your app has its own users, a system plugin can admit its admin sessions instead of (or as well as) the token by contributing to the admin-authorizer point (system-only):

contributes: { 'admin-authorizer': [{ name: 'session', authorize: (req) => isAdminSession(cookieValue(req, 'sid')) }] }

With neither a token nor an authorizer, mutating routes are open (local development only). The baseline deliberately knows only “may mutate / may not” — per-user permissions live in your plugins.

Users and sessions (@sms/plugin-auth)

Install createAuthPlugin({ bootstrapAdmin: { login, password } }) and the baseline has users: PBKDF2 passwords (WebCrypto — works in a Worker), cookie sessions, and an admin-authorizer so an admin’s session drives every /api/* route above without the bearer token.

Your own routes ask identity.whoami(req) (key identity, injectable by agent plugins too — it never returns secrets). User management (identity-admin: create, setPassword, setAdmin, deactivate, activate) is a system-only key. Groups and permissions are @sms/plugin-rbac’s job.

Groups and permissions (@sms/plugin-rbac)

“Admin” here means the identity provider (your auth plugin) says isAdmin for the session — not the admin token. In your own routes: await rbac.assertCan({ userId, model, op }) (403 on failure) and AND await rbac.ruleDomain({ userId, model, op }) into the query.

Errors

Every baseline route answers errors as { error: { message, kind } } with a matching status (validation 400, auth 401, forbidden 403, not_found 404, conflict 409, internal 500 — the last one also carries plugin, the owner of the failing route). Use the same shape in your own routes: throw new HttpError(404, 'no such invoice') or return errorJson('bad id', 400) from @sms/plugin-http.

A minimal chat + approvals screen

const api = (path, init = {}) => fetch(path, { ...init, headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', ...init.headers } })
async function send(text) {
  const r = await (await api('/api/chat', { method: 'POST', body: JSON.stringify({ session: userId, text }) })).json()
  render(r.reply, r.steps)               // show tool calls: plugin_define → verdict, etc.
  refresh()
}
async function refresh() {
  const s = await (await fetch('/api/state')).json()
  renderPending(s.pending)               // approve/reject buttons → POST /api/approvals/:id/approve
  renderPlugins(s.plugins)               // enable/disable toggles for trust === 'agent'
  renderCollections(s.collections)       // tables from schema; rows from /api/collections/:name
}

Showing agent-made UI safely

Agent plugins cannot contribute HTML to the baseline (there is no such point). If your product wants agent-authored panels, define your own extension point in a system plugin (ui-panel: { title, html }), mark it sensitivePoints so a human approves each one, and render the HTML in a sandboxed iframe or through a strict sanitizer. The kernel will validate, record and undo those contributions like any other.

Streaming, long chats

POST /api/chat returns when the turn is done (tool loops included; maxSteps in the agent-loop options). POST /api/chat/stream is the same turn as text/event-stream: one data: <json> frame per AgentEvent (@sms/plugin-agent-loop):

Read it with fetch + ReadableStream (cookies and the bearer token work; EventSource cannot POST): split on blank lines, JSON.parse after data: . The turn keeps running server-side if the client disconnects, and turns on one session run one after another. Your own routes get the same stream from agent.chatStream(session, text) and can return sse(events) from @sms/plugin-http; the agent key is system-only, so such a route lives in one of your system plugins. For durable transcripts implement AgentSessionStore (load on a cache miss, append per message) and pass a factory as createBaseline({ sessionStore: (kernel) => store }) — it runs before your plugins install, so load() may read any key from the kernel it is given.