Design

Agents emit a spec. The server draws it.

The generative UI protocol is versioned, validated on the server, and closed by construction. An agent describes components — never HTML — and the server renders them with the same design system, the same translation catalogue and the same authorization as every other view.

The protocol

An envelope, and a closed set of widgets.

{
  "protocol": "gsdui/1",
  "canvas_id": "…",
  "base_version": 12,
  "layout_title": { "i18n": "ui.canvas.sales_breakdown" },
  "view_mode": "GEN_UI",
  "widgets": []
}

view_mode is one of GEN_UI, BROWSER, DIFF or LOGS. The enum matches the UI exactly — an earlier draft listed four modes in the UI and three in the schema.

Every widget has a stable id. When the agent does not supply one, the server derives it from the canvas and the state key. A re-emitted widget for the same logical slot keeps the same id, so the client patches in place instead of remounting.
Table sort order, scroll position and Alpine state survive updates. That is the whole point of stable identity, and it is what a positional array cannot give you.
UI chrome is a translation key. Content is verbatim. Labels carry i18n keys; the message text and the data values are stored exactly as they arrived.
RuleConsequence
Rows are records keyed by columnColumn reorder cannot corrupt data. Positional arrays are not allowed.
Actions resolve server-sideThe client never supplies code, and the server never trusts the client's copy of a widget.
The component whitelist is closedUnknown types and unknown props are rejected at validation.
Patches are RFC 7386 merge patchesOne widget's props change without touching the rest of the canvas.
Text deltas are ephemeralThe final assembled message is appended once as a TEXT event; deltas are never persisted.
Data binding

A report that is still a report tomorrow.

A widget carrying inline rows is a screenshot with more steps. Instead, a widget may carry a binding to a dataset, and the server resolves it as the viewer.

{
  "id": "w_sales_table",
  "type": "DataTable",
  "state_key": "sales.by_region",
  "props": {
    "columns": [
      { "key": "region", "label": { "i18n": "ui.table.region" }, "type": "text" },
      { "key": "volume", "label": { "i18n": "ui.table.volume" }, "type": "currency" }
    ],
    "data": {
      "dataset": "…",
      "parameters": { "period": "$param.period", "team": "$param.team" }
    }
  }
}
  • The client never calls the dataset and never receives a query. The server executes it and renders materialised rows.
  • Parameters resolve in order — the artifact version's declared parameters, then the viewer's widget state, then the default.
  • Rows are paged server-side with a cursor action, so a large report renders like a small one.
  • A failed query renders that widget's error state and leaves the rest of the artifact intact. One slow dataset must not blank a pinned report.
  • A missing permission renders a permission state, never a partial result — a viewer cannot infer rows from an aggregate.
  • A binding must be declared by the published version, so a payload cannot widen its own access at render time.
Tier 1 · default

JSON records

Rows live in JSONB with a GIN index. Relationships are a relation table. Required and unique constraints are validated before insert. No DDL, no migration risk — and it already delivers permanent storage.

Tier 2 · opt-in

Physical tables

High-volume models get a real table. The DDL is generated from validated field metadata only, identifiers are slug-derived and pattern-checked, and the change is gated by human approval.

Governance

Idempotent sync

An idempotent command applies controlled DDL on every deploy. Destructive operations are never automatic, and a drift check fails CI when the registry, generated models and live columns disagree.

Why not generate a real table for every user-created model by default. It adds a second schema system outside migrations, patches the app registry, multiplies tables per tenant, and lets a manipulated agent alter shared schema. Flip the default only if the platform's purpose becomes a no-code database rather than a CMS with agent-native app building.
Hydration

Server-rendered fragments, swapped by widget id.

There is one Django template per widget type. A UI mutation carries the rendered fragment plus props and a sequence number, and the client swaps it in place.

  • Reuses the existing design system instead of duplicating it in JavaScript.
  • Keeps {% trans %} authoritative — the translation catalogue stays the source of truth.
  • Avoids introducing React into a codebase that has none, on a stack of Tailwind, HTMX and Alpine.
Mutation → fragment → swap
AGENT UI_MUTATION spec, not HTML VALIDATE closed whitelist props + binding grants TEMPLATE one per widget gettext keys HTML FRAGMENT + PROPS + seq CLIENT swap by widget id keep local state SAME AUTHZ AS THE SIDEBAR RESOLVER rendering a pinned artifact needs no topic — artifact, current version, declared bindings
No second widget renderer No React
Reference scenario

One missing report, twelve steps, and the model has to survive all of them.

This is the acceptance criterion. The rule for reviewing the design is simple: if a step needs a concept the domain model does not have, the model is wrong — not the scenario.

Cast

Northwind is the organization. Sales is a team. APAC Pipeline is a room.

Humans

Dana is the organization owner. Sam leads Sales. Priya belongs to a guest organization with a room share.

Agent

analyst has an OpenAI-compatible default runtime and a CLI fallback, is rostered into the room as its default agent, and is owned by Dana.

Data

Deals live in a dynamic model. Sam defines the dataset deals.by_region with period and team.

1
The built-in app is not enough
A seeded "Deals by owner" report exists and does not break down by region. Nothing is broken — it is simply not the report Sam needs. This is the moment the product exists for.
2
Sam asks
A task is created in the room, assigned to the analyst agent and linked to the objective. The assignee is a User, and an agent is a User, so this is the same assignment path a colleague would receive.
3
A topic appears
The task creates a topic with a required subject and queues an agent run. Sam's first message mentions the agent explicitly.
4
The agent queries data without SQL
The worker claims the run and executes the resolved runtime. The adapter asks for dataset.query with the dataset id and parameters. The worker checks the capability, intersects the agent's data scope with Sam's, executes the validated spec, and returns rows.
5
Preview in the canvas
The agent emits a UI mutation whose table widget binds to the dataset. The run appends it, it becomes a canvas version, and column three renders the fragment server-side.
6
Sam refines
"Add margin, sort by volume." Each turn is an action event plus a new version or a patch. Widget ids are stable, so the table's sort and scroll survive. Optimistic concurrency stops a second run clobbering the canvas.
7
Sam publishes to the team
Publishing appends ARTIFACT_PUBLISHED, creating the artifact with team visibility, version 1, and a source topic — then ARTIFACT_PINNED at team scope. Nothing was copied, and the canvas remains the working state.
8
Dana pins it for the organization
A second pin on the same artifact and the same version. A person in an unrelated team now sees it in their sidebar. There is still one artifact and one current version.
9
The guest does not see it
Priya sees artifacts pinned to that room whose visibility is room-level. Team and organization pins are invisible to her, and the room share never widens artifact visibility.
10
The report refreshes itself
A scheduled trigger re-runs the task each week and publishes version 2. Both pins show v2, because a pin points at the artifact. If v2 fails validation, the current version stays at 1 and the failure is a run-status event.
11
Two viewers, two row sets
A colleague opens the pinned report from the organization sidebar with no topic in view. The render endpoint executes the bindings as that colleague. Sam sees APAC and NA; the colleague sees only rows their scope allows, or a permission state.
12
The report is now part of the system
Addressable by id, linked to an objective, produced by an auditable run, refreshable on a schedule, pinnable at any scope, with row access that follows the viewer. A second agent, a third adapter or a new team changes none of that.
Dynamic apps

User-defined apps are a first-class feature, not a footnote.

Definitions are data. The registry is the durable source of truth for schemas, and it is what lets an organization model its own domain without a deploy.

App
DynamicApp

A named bundle an organization owns.

Model
DynamicModel

A schema versioned against a storage tier: JSON by default, physical as an approval-gated opt-in.

Field
DynamicField

A typed field — text, integer, decimal, boolean, date, datetime, JSON, or a relation to another model.

  • Events referencing user-defined records carry a stable entity id and record id — never a Django content type — so the log survives a generated-app rebuild or a rename.
  • Access is organization-scoped and narrowed by data scope, so a team's records are not readable by every member of the organization.
  • Agents reach dynamic data only through grants, the same row scope, and the approval policy.
  • Tier 2 DDL comes from validated metadata only, never from user SQL, and destructive changes never happen automatically.
Text shown in the UI is always wrapped for translation. A kind names the shape, not the business: a sales team, a club and a charity all use the same "report" entity with their own label.
The workspace, in practice

What the shipped slice already does.

The first four roadmap steps are built: ASGI, the actor flag, the organization event log and the topic WebSocket consumer — plus a working workspace and a CLI agent over the Agent Client Protocol.

Live

A stream that recovers itself

The socket reconnects with backoff and re-subscribes from the last sequence. Visibility and online events re-subscribe to catch up. A stale page cannot hide behind a dead socket.

Live

Streamed replies, honest records

Token chunks arrive as transient deltas into a streaming bubble. The persisted final message replaces it. A mid-stream reload loses partial text by design — the final message is the record.

Live

Per-topic model selection

The composer hides model choice unless the message mentions a rostered agent, so a plain room note never changes the topic model. A switch appends an event and renders in the timeline.

Live

Two CLIs, one client

The ACP client negotiates session options: one CLI accepts a set_model call, the other implements only the standard config option. One client serves both, with a fallback on method-not-found.

Live

Invocation as a seam

An agent process receives only PATH, HOME, USER, SHELL, locale, terminal and the XDG directories. The server's database URL, Redis URL and secret key are deliberately withheld, and a test pins it.

Live

Failures you can read

A missing binary, a crash before the handshake and a hang each record an error event that names the cause and the evidence. Before this, a failed run looked like the agent ignoring you.

Still ahead: approvals, secrets and per-capability grants; the canvas and the full protocol; the JSON API; the worker and the executor placements; and the product layer of objectives, tasks, artifacts and datasets.

Next: the principles that decide the trade-offs, and where this goes.