Dashboard Architecture

Vision

Working with an agent today is a text stream. The dashboard makes it a workbench: the agent renders live, interactive widgets; the user pins them onto a persistent surface; chat docks to the side (or hides) and the main content is the board. You go from "talking to the agent" to "operating a control panel the agent built for you" without ever leaving the session.

Principles:

• A board is a face of a session, not a new object. Every session (thread) has two faces: the transcript and the board. A session with no pinned widgets is plain chat. Pin one widget and the board exists. Boards inherit the session's identity, agent ownership, naming, pinning, and lifecycle. There is no dashboard_create, no board registry, no separate ACL model.
• Agent parity. Everything the user can do on a board, the agent can do with tools: add/update/remove widgets, arrange them, manage tabs, switch the visible tab, dock or hide the chat.
• Native, not embedded. The board is Lit components in the Control UI shell (the same design system as the rest of the app). Only widget content is sandboxed in iframes. No URL bar, no browser chrome.
• Small agent surface. Widgets are addressed by stable name and updated in place. Layout is a fluid auto-compacting grid; the agent speaks sizes and anchors, never pixels or coordinates.
• Capabilities over trust. Widget code is arbitrary agent-authored HTML/JS in a hard sandbox. Reach (gateway data, actions, network) exists only through a declared, operator-granted capability manifest.

Concepts

UX flows

• Graduation: agent calls show_widget in any chat → widget renders inline in the transcript exactly as today → hover shows Pin to dashboard → widget appears on the session's board. The agent can pass pin: true to do the same.
• Board view: a session with a board gets a face toggle (Chat / Dashboard). Board view = tab strip (only when >1 tab) + fluid grid + docked chat pane. Chat dock is resizable, movable (left/right/bottom), and collapsible exactly like the sidebar. Per-tab dock state is remembered.
• Drag: user drags widgets; grid auto-compacts (widgets float up, neighbors reflow). Resize by handle snaps to size steps. No pixel placement — for anyone.
• Reset warning: /new / /reset on a board-bearing session asks for confirmation in the web UI ("context resets, the dashboard stays") and keeps the board.
• Sidebar: pinned sessions render their board face when they have one. The Home session's board is the default "agent dashboard".
• Interactions (three tiers, see below): silent state events, visible prompt sends, and automation triggers.

Interaction tiers

1. State events (default). Widget UI interactions the model should know about but not respond to. bridge.emitState({...}) appends a structured session notice (same mechanism as group-activity notices). No agent turn is started; the model sees accumulated notices on its next run.
2. Prompts (explicit talk). bridge.sendPrompt(text) — requires user activation; sends a visible user message into the session (the docked chat shows it). Rate-limited; each send is user-confirmed unless the widget holds the prompt capability grant.
3. Automation. bridge.runAction(name, args) — fires a manifest-declared action. Initial verb set: cron.trigger (run an existing cron job now) and binding.refresh. Cron jobs already run in visible, isolated run-sessions and can use a cheaper model: that is the "small model powers the widget" path. No hidden sessions anywhere.

Widget model and hosting

Widget HTML/JS is authored by the agent (typically via show_widget), wrapped in the standard document shell (CSP meta, size reporter, bridge bootstrap) and rendered in <iframe sandbox="allow-scripts"> (never allow-same-origin).

• Inline (transcript) widgets keep the current canvas-document pipeline: written under the state dir, served by the gateway, pruned per scope, no approval (they are capless by construction — prompt sends are user-confirmed).
• Board widgets are session state: bytes live in the owning agent's SQLite DB (board_widgets), served by a core gateway route (/__openclaw__/board/<agentId>/<sessionKey>/<name>/) that reads the DB. Pinning a transcript widget copies the bytes. Caps: 256 KB per widget, 48 widgets per board.
• Update in place: re-emitting a widget with the same name replaces the bytes, bumps revision, broadcasts board.changed, and live views reload that iframe only.
• Byte freezing: granted capabilities bind to the sha256 of the widget bytes. Changing bytes keeps data/net/actions grants only if the new revision declares a subset of the granted manifest; a widened manifest re-prompts the operator.

Widgets host content; MCP apps are one content kind

The widget is the OpenClaw primitive: the named, pinned, sized, session-owned board cell with a grant record. What renders inside it is a content kind:

• html — agent-authored via show_widget, bytes in board storage.
• mcp-app — a third-party MCP app view (ui:// resource from a configured server) hosted inside the widget cell.

MCP apps do not define the widget model; widgets gained the ability to host them. Identity, placement, pinning, grants, and the author-facing API stay OpenClaw's — so show_widget code stays as short as it is today and never needs to know the MCP Apps spec exists.

Shared infrastructure underneath (this is where the simplification lands):

• One sandbox host. html widgets render through the same hardened pipeline MCP apps shipped with (double-iframe on the dedicated sandbox origin, per-widget CSP declared and fail-closed decoded) instead of a second bespoke iframe host. The proxy receives HTML by value, so local content is the natural case.
• One authorization model. A widget's reach is a granted allowlist, whatever its kind: for html widgets, host tools; for mcp-app widgets, the server's app-visible tools (via the existing allowedAppToolNames mechanism, made durable per widget instead of per-minting-run).
• Host tools for html widgets (exposed over the widget bridge, checked against the grant):
  • openclaw.prompt.send — tier 2; routed through the visible composer, user-confirmed unless granted
  • openclaw.state.emit — tier 1 session notices (coalesced, size-capped)
  • openclaw.data.read — parameterized read-only bindings (existing allowlisted read RPC set), resolved gateway-side
  • openclaw.cron.trigger — tier 3 automation
• net = CSP. Network reach uses the already-shipped per-widget CSP declaration (connect-src origins) — the self-updating weather widget fetches its API directly from the sandbox, no gateway involvement.
• Grants. A widget declaring nothing renders immediately (sandboxed, default-src 'none', prompt sends individually confirmed) — same trust as today's inline chat widgets. Declared tools/origins put the widget in pending on the board: a placeholder card lists them human-readably with one-tap Allow/Reject. Grants are per widget name; for html widgets they are byte-frozen (sha256), and changed bytes keep the grant only if the declaration shrank.
• Authoring shim. The document wrapper injects window.openclaw.sendPrompt/emitState/read/call as the stable author API; whether the transport underneath is our channel or the AppBridge is an internal detail the widget author never sees. Size reporting and theme tokens ride the same bridge.

Transcript display: one widget card

Inline display unifies on the widget primitive. When a tool result carries UI — show_widget output or an MCP tool result with an app resource — the system materializes an ephemeral, auto-named widget (session-scoped, pruned) and the transcript renders a single widget card that dispatches on content kind. MCP app auto-display stays exactly as the spec expects (zero extra model work); it just is a widget underneath. This deletes the parallel mcpApp special-cases in chat rendering (surface gating, separate dedup), gives every inline UI the same pin affordance, and makes the widget registry the primary re-open path (transcript-scan reconstruction stays as fallback for never-pinned history). The read-only ticketed standalone host overlaps with boards as a persistent re-open surface — consolidation candidate to evaluate in T6, not assumed.

Composition: v1 is grid adjacency (agent chrome widget next to an app widget on one tab). v2 adds host-managed app slots — agent widget HTML declares a slot region and the host composites the real app view as a sibling sandbox. The app never renders inside the agent's iframe: nesting would break bridge identity and enable overlay/clickjack of granted app UI, so the slot is a layout contract, not an embed.

Server-sourced widgets (pinned MCP apps)

With the unified host, pinning a third-party MCP app is just a widget whose content is fetched from the server instead of stored: board_widgets keeps the descriptor (serverName, toolName, uiResourceUri, originating toolCallId + sessionKey) instead of HTML bytes, and the board re-mints the view lease past the chat-turn 10-minute TTL (re-fetching the ui:// resource on staleness). Chat inline MCP app views get the same Pin to dashboard affordance as agent widgets. Re-opened views are read-only today by design; pinned apps that should stay interactive get a durable grant over the server's app-visible tools (explicit allowlist shown to the operator on pin), decoupled from the minting run. Ungranted pins stay read-only — still useful for display dashboards. v1 pins to the originating session's board; cross-session pinning needs a lease broker and waits. Coordinate with open PR #109807 (ui/message composer routing, theme/size propagation).

Layout: fluid grid

12 columns, fixed row height, auto-compacting (gravity-up, push-aside on drag — gridstack semantics, implemented natively; grid math stays pure and DOM-free). Widget layout state per tab: { name, w (1-12), h (rows) } plus order. Agent vocabulary:

• size: sm (3×3) · md (6×4) · lg (8×6) · xl (12×8) · full (single-widget tab)
• after: <widgetName> optional ordering anchor; omitted = append
• User drags/resizes freely; the same order+size model round-trips.

Data model (per-agent DB)

New tables in agents/<agentId>/agent/openclaw-agent.sqlite (requires an agent-DB schema-version bump — operator sign-off required before this lands):

CREATE TABLE board_tabs (  session_key TEXT NOT NULL,  tab_id      TEXT NOT NULL,           -- slug  title       TEXT NOT NULL,  position    INTEGER NOT NULL,  chat_dock   TEXT NOT NULL DEFAULT 'right',  -- left|right|bottom|hidden  created_by  TEXT NOT NULL,           -- 'user' | 'agent'  PRIMARY KEY (session_key, tab_id)) STRICT; CREATE TABLE board_widgets (  session_key  TEXT NOT NULL,  name         TEXT NOT NULL,          -- stable widget name  tab_id       TEXT NOT NULL,  title        TEXT,  html         BLOB NOT NULL,          -- wrapped document source  sha256       TEXT NOT NULL,  revision     INTEGER NOT NULL,  size_w       INTEGER NOT NULL,  size_h       INTEGER NOT NULL,  position     INTEGER NOT NULL,       -- order within tab (auto-compact input)  manifest     TEXT NOT NULL DEFAULT '{}',  -- capability manifest JSON  grant_state  TEXT NOT NULL DEFAULT 'none', -- none|pending|granted|rejected  granted_sha  TEXT,                   -- byte-frozen grant  created_by   TEXT NOT NULL,  created_at   INTEGER NOT NULL,  updated_at   INTEGER NOT NULL,  PRIMARY KEY (session_key, name)) STRICT;

Board existence = any rows for the sessionKey. Deleting a session deletes its board rows. /new//reset does not touch them.

Protocol surface

RPCs (core method table, typebox schemas in gateway-protocol):

• board.get { sessionKey } → tabs + widget metadata (no bytes) — operator.read
• board.update { sessionKey, ops[] } — tab CRUD/reorder, widget move/resize/ remove/unpin, dock state, focus-tab — operator.write
• board.widget.put { sessionKey, name, html, manifest, placement } — operator.write (agent tool path and pin path)
• board.widget.grant { sessionKey, name, decision } — operator.approvals
• board.event { sessionKey, widget, payload } — tier-1 state event ingest — operator.write

Events (in EVENT_SCOPE_GUARDS, read scope):

• board.changed { sessionKey, revision, widget? } — persisted state changed; UI refetches (and reloads one iframe when widget is present).
• board.command { sessionKey, command } — transient UI drive (agent switches the visible tab, toggles chat dock) — the ui.command pattern.

Widget bytes are served over the authenticated HTTP surface, not the socket.

Agent tools

Three tools total (core, always registered; rendering gated on the inline-widgets client cap as today):

• show_widget { title, widget_code, name?, pin?, size?, tab?, after?, capabilities? } — create/update by name; pin places it on the board. Without name/pin it behaves exactly like today (inline, ephemeral).
• dashboard { action, ... } — board management verbs: read, tab_create, tab_update, tab_delete, tabs_reorder, widget_move, widget_remove, unpin, focus_tab, set_chat_dock.
• Existing cron tools cover the automation tier; no new tool needed.

Tool descriptions teach the size/anchor vocabulary and the tier model. The agent is told about user tier-1 events via session notices, e.g. [dashboard] user clicked "Refresh" on widget weather (tab main).

What this replaces

• extensions/workspaces is deleted. Experimental, enabledByDefault: false, never in a stable release (first appeared in 2026.7.2 betas). No migration; a doctor rule removes stale <stateDir>/workspaces/ if present. Harvested ideas: pure grid math, bridge security model (port bootstrap, binding gating, rate limits), byte-frozen approval.
• Widget hosting moves from extensions/canvas to core. The canvas doc store, document wrapper, HTTP serving, and the show_widget tool become core (src/canvas/); the plugin keeps the node-canvas control tool (canvas) and A2UI. The pluginSurfaceUrls["canvas"] advertisement and /__openclaw__/canvas paths are shipped native-client contracts and stay stable. Discord sessions keep the Discord-owned show_widget variant.
• WorkBoard is untouched (integration is a follow-up program).

Non-goals (this program)

• Multi-user board sharing/ACLs (future; will arrive via session sharing).
• Native macOS/iOS board rendering (they get it wherever they embed the Control UI; the inline-widget path is unchanged).
• Builtin data widgets (sessions/usage/cron cards) — the capability bridge plus agent-authored widgets cover v1; a builtin kind registry can come later.
• WorkBoard-on-dashboard.

Implementation plan

Independent worktrees, Codex-built, review+land sequentially. Land-then-fix.

Validation per repo rules: focused vitest locally, full gates on Crabbox/Testbox, $autoreview before every land, live proof for T6.