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), lives until its TTL elapses, 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 (app_…) 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 (coming soon), 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 route the tool surfaces on. /mcp serves the union of agent + runtime handlers (what the model and its runtime see); /protocol serves protocol (design-time spec/discovery); /ops serves ops (operator surface). 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, coming soon). 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, code -32020; 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 routes (/mcp, /protocol, /ops); 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 per command from --registry / ggui.json#registry / GGUI_REGISTRY; installs 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 /ops route (e.g. http://127.0.0.1:6781/ops). 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. Wire-name prefix is ggui_ops_*, distinguishing them from agent-facing ggui_* tools at the route level.

→ See Ops 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 renders in ~100 ms versus ~3 s for fresh generation. 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 (coming soon), keys are minted via ggui keys create after ggui login (Preview — managed cloud, coming soon). 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.