---
title: Glossary
description: Lookup reference for ggui terminology — GguiSession, contract, blueprint, channel, connector, gadget, tool, and the wire envelopes that tie them together.
---

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**](/how-it-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](/api/mcp-protocol/) 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](/protocol/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](/protocol/overview/) names the **chat channel** (user ↔ wrapped agent, HTTP SSE) as the conversational-stack third; the [architecture overview](/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](/architecture/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](/protocol/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](/protocol/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](/protocol/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`](/api/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`](/api/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](#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](/architecture/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](#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](/api/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](/architecture/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`](/cli/login/#manage-keys) after [`ggui login`](/cli/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](/cli/serve/#production-hardening).

---

## See also

- [Protocol overview](/protocol/overview/) — the three-channel topology these terms hang off.
- [Envelopes](/protocol/envelopes/) — wire reference for `ActionEnvelope` and `StreamEnvelope`.
- [MCP Protocol](/api/mcp-protocol/) — MCP method reference (`ggui_handshake`, `ggui_render`, `ggui_update`, `ggui_consume`).
- [WebSocket Protocol](/api/websocket-protocol/) — live-channel message-type reference.