ui-surfaces plugin
The bundledui-surfaces plugin (ADR 0106) gives the WednesdayAI web chat its assistant-composed
UI: the show_ui agent tool, the plugin-owned store behind the chat.surfaces.list|get|pin
gateway methods, and the UiSurfaceProvider seam core reads. It is off by default (ADR 0034);
enablement, the per-agent tools.deny opt-out and what end users see are covered from the
operator side in Web client hosting.
Everything the agent can put on screen is declarative JSON validated by the private
ui-contract package (validateSurface) before anything is stored. The schemas, the component
catalog and the budget constants are re-exported from wednesdayai/plugin-sdk (legacy alias
openclaw/plugin-sdk), so the plugin imports core only through the SDK:
The provider seam
The plugin registers exactly one provider:src/plugins/registry.ts: a
second registration is rejected with a PLUGIN_REGISTER_ERROR diagnostic and the first
registration stands. Core reads the provider from the global registry and never touches surface
storage itself - it owns the protocol, admission, turn binding and history projection, while the
plugin owns the tool and the storage (ADR 0106 D13).
The provider contract (UiSurfaceProvider from ui-contract, re-exported by the SDK) is keyed
by session id, never by session key: core resolves sessionKey -> sessionId the same way
chat.history does before every call, which keeps the canonical-key rules in AGENTS.md out of
the plugin:
bindAction is an atomic consume: it derives the submit schema for that revision
(deriveSubmitSchema), strips unknown keys, validates the values, and consumes the revision in
the same transaction. Two concurrent submits for one revision yield exactly one ok and one
"ui-action-consumed" refusal. The refusal reasons are the UiActionProviderRefusal union
(ui-action-unknown-surface, ui-action-stale, ui-action-undeclared,
ui-action-invalid-data, ui-action-consumed); core maps them onto chat.send refusals and
never lets one authorize anything - the accepted action only starts the next chat turn.
The show_ui tool
The tool factory receives theOpenClawPluginToolContext and returns null - offering nothing -
unless all of these hold:
- the plugin is enabled;
ctx.clientCaps(the advertised caps of the connection that started the run withchat.sendoragent) contains"ui-surfaces";ctx.sessionIdis present.
tools.deny: ["show_ui"] applies as usual on top.
A rejection is isError: true with text show_ui rejected: <rule>: <detail> and stores nothing;
every cap is a refusal, never a prune.
Render profiles
ctx.clientRenderProfile carries the originating connection’s renderProfile connect field.
With "hud" (a glasses display), the surface is still stored, so its actions bind through
chat.send uiAction as usual, but the tool result is degraded:
contentis the title and the visible text of each node in render order (text,label,value), whitespace-collapsed, each line cut to 48 characters, at most four lines; when more remain, the fourth line is…. Button labels are not lines. ATableadds a header line of its column labels and one line per row, cells in column order joined by|(a blank cell shows as-; an all-blank row is skipped).detailsis{ ui: {surfaceId, revision}, renderProfile: "hud", hud: { lines, actions } }, whereactionsholds the first two submit buttons as{ id, label }.openUrlbuttons are dropped.
result unless the session’s verboseLevel is full. A
tool-events connection that declared renderProfile: "hud" still receives this HUD slice
(content plus details.{ui, renderProfile, hud}, nothing else) at any verbose level; other
connections and channel output are unchanged.
"full", "compact" and an absent profile return the normal result; "compact" has no reduced
form yet. chat.surfaces.get and chat.surfaces.list are unchanged for every profile.
Storage
Placement follows the shared domain resolver (resolveDomainStorage, domain ui-surfaces), the
same rule as every other plugin-owned store: sqlite by default, or Postgres in the
plugin_ui_surfaces schema; overrides live under
plugins.entries["ui-surfaces"].config.storage. The store is append-only - no DELETE anywhere -
and keyed by sessionId, so a reset or /new starts an empty Canvas without touching old rows
(ADR 0098).
Transcript carriers
Surfaces and actions ride two transcript carriers, never free-form markdown:__openclaw.ui={surfaceId, revision}— projected from theshow_uitool result’sdetails.uiatchat.historyread time; the snapshot itself is fetched viachat.surfaces.get.__openclaw.uiAction={surfaceId, revision, actionId, label, title}— on the user turn (stored as theopenclaw:ui-actioncustom entry), rendered as the “You submitted” chip. The submitted data is not in it: it reaches the model only in the composed[ui-action]text.
show_ui parameters
The tool takes a flattened payload validated bypackages/ui-contract (validateSurface):
surfaceId(optional; mints one when omitted, adds a revision when present).title(1..80 chars).components— the node list from the 14-component catalog (Column,Row,Card,Divider,Text,Image,Progress,Table,Chart,TextField,CheckBox,ChoicePicker,DateTimeInput,Button).
show_ui rejected: <rule>: <detail> and stores nothing.