Sneak peek — you found hosted ggui early · official launch soon

Glossary

read as .md

Lookup reference for the terms that run through these docs. Each entry is short and links to where the term is documented in depth. For a narrative walkthrough, see How ggui works.

Identity and lifecycle

GguiSession (a “render”)

The atomic unit of a ggui exchange — the canonical protocol shape for a single rendered UI. A GguiSession is minted server-side inside ggui_render (one per UI emission), persists — reopenable via resources/read, or bounded by an optional per-render TTL — and is keyed by a stable sessionId (opaque string). It is a union of Component / System / McpApps variants and carries a single component mount plus a stream of live-channel deliveries. The server is the authority on its state, not the agent. render survives as the verb and in wire constants (ggui_render, ui://ggui/render, the ai.ggui/render slice).

Conversation-scoped grouping (sibling GguiSessions inside the same host chat) flows through the unchanged _meta["ai.ggui/host-session"] slice — captured ONCE at creation, never lifted onto every GguiSession. The agent does not thread a conversation id; instead each new ggui_handshake → ggui_render pair mints a fresh sessionId.

→ See MCP Protocol → ggui_handshake / ggui_render for the lifecycle methods.

GguiSession contents

A single GguiSession packages a compiled component plus its declared contract:

sessionId — the stable identifier
componentCode — the compiled JavaScript module returned by generation
props — the data payload the agent rendered
propsSpec / actionSpec / streamSpec / contextSpec — the four contract specs that pin the wire surface
clientCapabilities — the package-keyed gadget catalog projected from the contract at render time

In wire envelopes you’ll see sessionId consistently — there is no separate conversation-session id layer.

→ See Envelopes → ActionEnvelope for the wire shape.

App (`appId`)

The agent-builder’s tenant scope. An appId (an opaque 8-character base62 string, e.g. aB3kP9xY) groups GguiSessions, blueprints, connectors, and provider keys under one boundary. On self-hosted ggui serve, the default app is whatever your ggui.json declares; on the hosted ggui cloud, the appId is minted by the platform. Every ggui_handshake / ggui_render call is scoped to one appId.

`shortCode`

An internal 16-character token minted per render. Not on the agent wire — ggui_render returns sessionId + resourceUri (ui://ggui/render/<id>), and hosts mount the GguiSession from the resourceUri; the agent never receives a render URL — but ggui serve still uses shortCodes for its local render-viewer route (/r/<shortCode>).

Wire

ggui’s wire is split across orthogonal transports. Two share every framing: MCP (agent ↔ server request/response) and the live channel (server ↔ renderer WebSocket). A third depends on viewpoint — the protocol overview names the chat channel (user ↔ wrapped agent, HTTP SSE) as the conversational-stack third; the architecture overview names the bootstrap channel (server → renderer, one-shot bundle fetch) as the wire-pipeline third. The terms below all live on the live channel unless noted.

Audience

A tag on every MCP handler — one of agent, runtime, protocol, or ops — that determines which of the server’s two surfaces the tool appears on. The /mcp data plane serves the union of agent + runtime handlers (what the model and its runtime see during a session); the /control control plane serves protocol (design-time spec/discovery, anonymous) and ops (operator surface, authenticated and confirm-gated on mutations). The audience tag is set on every handler factory and encoded in the wire-name prefix (ggui_protocol_*, ggui_ops_*, ggui_runtime_*, or bare ggui_*).

→ See Audience routes.

Channel (live channel)

A named outbound stream on the live-channel WebSocket (ws://127.0.0.1:6781/ws on ggui serve; wss://mcp.ggui.ai/ws on the hosted cloud). Agents declare channels in their streamSpec; the server validates each StreamEnvelope against the declared channel’s schema before delivery. A channel has a name (e.g. message, tasks, progress), a payload schema, a state-folding mode ('append' or 'replace'), and an optional replay policy.

Channels prefixed with _ggui: are reserved for the server (e.g. _ggui:preview, _ggui:lifecycle). Agent-authored streamSpec cannot declare them.

→ See Envelopes → Reserved channels.

Contract

The typed agreement between agent and renderer for a given render: what the props look like, what actions the user can dispatch, what each action’s payload schema is, what live channels the renderer subscribes to. Contracts are authored with defineContract({…} as const) so the protocol derives TypeScript types from a single source.

A contract has four orthogonal specs:

propsSpec — initial render data (server → UI, one-time at render)
actionSpec — discrete events that drive the agent’s next turn (UI → agent, via ggui_consume)
contextSpec — observable state mirrored from UI to server, last-write-wins (UI → server)
streamSpec — outbound deliveries from agent to UI (agent → UI, via ggui_emit)

The placement test for the two inbound specs: does this thing need the agent’s next-turn reasoning? Yes → actionSpec. No → contextSpec. There is no third category — actionSpec carries events that drive turns; contextSpec carries state the agent observes when it next does work.

When a delivery violates the contract, the server rejects it with a typed, named failure (a CONTRACT_VIOLATION error frame on the live channel; a typed rejection on the agent’s own tool call) — that’s the contract’s failure-mode surface. Nothing lands on the consume buffer. (The earlier _ggui:contract-error channel and ContractErrorPayload shape were removed in draft-2026-06-11.)

`ActionEnvelope`

The flat, narrow inbound envelope on the live channel. Carries a single canonical user action — type is always 'data:submit' — plus a payload. The server validates ActionEventValue payloads against the render’s actionSpec.

→ See Envelopes → ActionEnvelope.

`StreamEnvelope`

The outbound delivery on the live channel — one envelope per delivery on a named stream. Carries channel, mode, payload, and (when populated) a server-assigned seq for replay correctness.

→ See Envelopes → StreamEnvelope.

`nextStep` tool hint

An author-declared hint on a contract action: actionSpec[name].nextStep names an MCP tool — “when the user dispatches this action, that tool is what should run next”. Every action is agent-routed: the server appends the action event to the GguiSession’s consume buffer and the agent reacts on its next turn via ggui_consume. The hint rides along on ActionEventValue.tool (derived server-side at event-build time) so the agent sees the contract author’s recommendation; the agent owns the call decision — the protocol never binds it.

In agent-less deployments (a bare ggui serve with no agent process attached), actions take the SAME path: each action event queues on the GguiSession’s consume buffer until an agent attaches and drains it via ggui_consume({sessionId}) — the server NEVER invokes a tool on the user’s behalf. There is no second routing model.

Actions without a nextStep are pure event signals — the agent receives {action, data} and decides what to do unconstrained.

(The retired dispatch.kind === 'tool' | 'agent' discriminated union from earlier drafts is gone; outside material still using that vocabulary is stale.)

`ggui_emit`

The MCP tool the agent calls to emit a delivery onto a declared streamSpec channel of an existing render. Input is {sessionId, channel, payload}; the server validates payload against streamSpec[channel].schema and fans it out as a StreamEnvelope on the live channel. The outbound counterpart to ggui_consume’s inbound drain.

→ See MCP Protocol → ggui_emit.

`ggui_consume`

The MCP tool the agent long-polls to drain buffered user events off one render. Consume-once semantics — events drain on read. Call this right after every ggui_render whose response carries nextStep.tool === 'ggui_consume' (i.e. the rendered contract has a non-empty actionSpec). Drained events surface with optional tool metadata mirrored from actionSpec[action].nextStep.

→ See MCP Protocol → ggui_consume.

`nextStep` (advisory recovery hint)

A small wire-shape object the server returns on ggui_handshake and ggui_render. The handshake form is {tool: 'ggui_render', example}; the render form is {tool: 'ggui_consume', description, example, args: {sessionId}} — args carries the literal value to pass to ggui_consume. The example is a literal worked call prefilled with current ids, so the agent can recover the next step without re-reading the docs. On ggui_render, nextStep is emitted ONLY when the rendered contract has a non-empty actionSpec and points at ggui_consume; pure-display renders get no nextStep.

Distinct from actionSpec[name].nextStep, which is an author-declared tool hint on a contract action (see nextStep tool hint).

MCP service

A self-contained MCP server mounted at its own HTTP path (e.g. /docs, /playground/todos) with its own tool catalog, auth adapter, and lifecycle. Distinct from an McpServerMount, which aggregates tools onto the audience-filtered shared surfaces (/mcp, /control); a service stands alone at its mount path. Used when a tool group needs route-level isolation — a different auth posture, a tighter tool catalog, or a public read-only surface.

→ See MCP services.

Capabilities

ggui has two symmetric capability surfaces — one for what the agent can do, one for what the renderer can render. Both are declared per-app and bounded by the operator, not the agent. They mirror each other across the wire: the agent uses its tools to drive a render; the renderer uses its gadgets to render the result.

	Renderer (renders UI)	Agent (drives render)
Unit	gadget	tool
Catalog	`clientCapabilities.gadgets`	`agentCapabilities.tools`
Lifecycle	Loaded at iframe boot, SRI-verified	Bound at render start
Authoring	`ggui.gadget.json` manifest	MCP tool code

Gadget (renderer-side capability)

A self-contained bundle the UI generator picks up when assembling a UI. Concrete examples: a Leaflet gadget exports a LeafletMap component the generated UI renders; a Stripe gadget exposes a checkout flow; a Calendar gadget exposes date-picker behaviour. Gadgets bridge third-party JS into the ggui iframe runtime via the createGguiGadget factory; a contract references them through the package-keyed clientCapabilities.gadgets map (outer key = npm package, inner key = export name), and they load SRI-verified at boot. Authored as ggui.gadget.json manifests and published to a marketplace registry (resolved via the shared chain --registry > GGUI_REGISTRY > ggui.json#registry; read verbs — install/search — fall back to registry.ggui.ai).

The term replaced the older clientLibraries / “Client Libraries” name; old external references may still use it.

Tool (agent-side capability)

An MCP tool the agent has access to when orchestrating renders — ggui_handshake, ggui_render, ggui_consume, plus any custom tools the operator wires in. Tools are the agent-side counterpart of gadgets: gadgets give the renderer something to render with; tools give the agent something to act with. Declared per-app in agentCapabilities.tools and surfaced to the model via the MCP server.

Blueprints sit in a different category — they’re not capabilities, they’re cached responses (pre-composed UIs) that short-circuit fresh generation. See Blueprint below.

Ops tool

An MCP tool tagged with audience: ['ops'], surfaced on the server’s /control plane (e.g. http://127.0.0.1:6781/control). Every action the console UI can perform is also available as an ops tool, so an LLM operator agent can drive the same workflows programmatically — list apps, rotate keys, inspect renders, yank blueprints. Ops tools require authentication (unlike the anonymous protocol tools sharing the route), and state-changing ones require a second call with confirm: true. Wire-name prefix is ggui_ops_*, distinguishing them from agent-facing ggui_* tools.

→ See Control MCP.

Theme

A per-app visual overlay. AppTheme = {mode: 'light' | 'dark', cssVariables, name?} — where cssVariables is a map of --ggui-* custom properties — is snapshotted onto each GguiSession at render-commit and applied at the iframe :root after the base design tokens, so operator values win the cascade. Presets ship in @ggui-ai/design (7 today); agents discover them via ggui_list_themes and override per render with ggui_render({themeId}). Resolution chain: GguiSession.themeId → App.defaultThemeId → server fallback.

Generation

Blueprint

A cached UI primitive — a stable, reusable card whose code, contract, and prompt are pre-computed. Blueprints are matched during ggui_handshake by intent + contract similarity (semantic search + LLM rerank); the paired ggui_render then serves the cached component — a hit serves the pre-built component with zero generation calls; a miss runs fresh generation — both render in seconds. Project-local blueprints are authored as ggui.ui.json manifests and declared via ggui.json#blueprints.include globs; for marketplace publishing, a blueprint repo carries a ggui.blueprint.json artifact manifest (ggui blueprint publish).

Where gadgets are ingredients the LLM composes with and tools are actions the LLM invokes, blueprints are recipes the LLM can return directly — a cache short-circuit for already-solved screens.

Primitive

A leaf-level UI component declared in a primitive catalog (e.g. Button, Input, SearchField). Primitives are catalog-declared, not protocol-declared — the agent doesn’t ship a fixed component set; the operator declares which primitives are available via ggui.json#primitives.

Component levels nest: primitive (Button) → component (SearchField) → composite (LoginForm, Modal) → template (ListDetail, Dashboard page).

`shellType`

The visual shell the renderer wraps a render in. Three values today: chat (conversation pane), fullscreen (whole-window app), spatial (XR / immersive surface). Carried on interfaceContext.shellType and read by the runtime when mounting a render.

Auth

Anonymous service

An McpService mounted with anonymous: true. Auth becomes OPTIONAL, not skipped: a presented valid bearer still resolves to the caller’s real identity; only a missing or invalid credential falls back to a synthesized {identity: {kind: 'builder'}, source: 'anonymous'} principal. Safe for read-only public surfaces (e.g. the docs MCP service that serves how-to lookups); tools that mutate or read tenant-scoped data must re-impose auth at the handler level.

→ See MCP services.

Connector / connector key

A ggui_user_* API key that authenticates an agent runtime against a ggui MCP server. Locally, ggui keys create --keys-file <path> mints bearers that ggui serve --keys-file accepts — no account needed. On the hosted cloud’s universal endpoint, keys are minted via ggui keys create after ggui login, or straight from the ggui console. Connector keys are scoped to one user; revoking via ggui keys revoke <id> is a soft-revoke (the audit row stays, but every subsequent request from the key returns 401 invalid_grant).

Distinct from the bearer minted by ggui serve’s pairing flow — that bearer is per-session and per-pairing, not user-keyed.

`wsToken`

A short-TTL opaque credential minted at ggui_render and delivered to the iframe on _meta["ai.ggui/render"], paired with wsUrl. The iframe presents it on the WebSocket upgrade (?wsToken=) and in SubscribePayload.wsToken; the server validates it against the subscribing sessionId + appId. Refreshed without a re-handshake via the runtime-audience tool ggui_runtime_refresh_ws_token.

`AuthAdapter`

The pluggable seam in @ggui-ai/mcp-server that decides who’s authenticated on /mcp and the live-channel /ws upgrade. The default for ggui serve is dev-mode pairing; production composes createGguiServer({ auth }) with a custom adapter (OIDC, Cognito, custom).

→ See ggui serve → Production hardening.