Genui

Addressable panels and silent updates

Give a spec an id when the user is expected to act on it more than once:

{"id": "sales", "title": "Sales", "items": [ … ]}

An id is 1–64 characters of letters, digits, _ and -, unique within the conversation. A panel without one is a one-shot — correct for a summary nobody will touch again.

An id changes what happens when the user acts on the panel. Their action arrives with a panel key:

[octo-ui-action] {"panel": "sales", "action": "refresh", "fields": {"range": "30d"}}

Neither that message nor your reply to it is drawn in the conversation. Your reply replaces the panel in place, wherever it already sits.

For that to work your reply must be exactly one ```octo-ui fence carrying the same id, and nothing else — no sentence before it, no sign-off after it. Any prose turns the reply into an ordinary visible message, which is a correct fallback when you really do need to say something, but means the panel does not update in place. Choose one:

• Updating the panel? Emit the fence alone.
• Need to explain, refuse, or ask something? Write normally — say it, and include a fresh fence if the panel should also change.

Re-sending a panel inside an ordinary reply is not an error: it re-presents the panel at that point in the conversation, which is right when you are bringing it back up after other discussion.

Interaction state (field values, selected tab, fold state) belongs to the panel id and survives a page reload. When you send a new version of a panel, values whose fields still exist are kept and the rest are dropped — so a refreshed dashboard stays under the filter the user set.

The [octo-ui-action] feedback convention

When a user acts on a GenUI component you rendered earlier (clicks a button, submits a field, picks an option), their action reaches you as a normal new user turn whose text begins with the literal prefix [octo-ui-action] , followed by a JSON object:

[octo-ui-action] {"action": "refresh", "fields": {"range": "7d"}, "payload": {}}

• action — the action name the interactive node declared.
• fields — the current value of every interactive field the user has set (text inputs, selections, checkboxes) at the time they triggered the action.
• payload — any fixed extra data you attached to that action when you rendered it.

Treat this exactly like any other user message: read the JSON and figure out what changed. Don't echo the raw JSON back to the user; respond to what it means.

How to answer depends on whether the envelope carries a panel key:

• With panel — the strict form above applies: reply with exactly one fence carrying that id and no other text, and the panel updates in place with nothing added to the conversation. Prose makes it an ordinary visible reply instead.
• Without panel — the panel was anonymous, so there is nothing to update in place. Reply however the change calls for: a fresh octo-ui fence, a render_ui call, or plain text.

Caps and what happens past them

Both the tool path and the inline-fence path enforce the same structural caps. Respect them yourself rather than relying on the renderer to catch an oversized spec — going over a cap doesn't fail your call, it silently trims:

• Max tree depth: 8
• Max total nodes per spec: 200
• Max string field length: 500 characters (labels, text, badge text, etc.)
• Max table cell length: 2000 characters
• Max table rows: 500
• Max table columns: 50
• Max list/keyvalue items: 200
• Max select/radio/quiz options: 50
• Max tabs entries: 8
• Max code / textarea default text: 5000 characters
• Max plot series: 8; max points per series: 100
• Max link href: 2000 characters — an over-long one drops the node rather than being truncated into a link pointing elsewhere
• textarea rows: clamped to 2–12
• A button's payload object: also depth- and width-capped (same depth limit as the node tree; up to 50 keys/entries per level), but that budget is separate from — not subtracted from — the 200-node total above.

An unrecognized type (including an interactive type sent through the render_ui tool, which only accepts the read-only table) causes just that node — and its subtree — to be dropped; its siblings still render. A spec with no valid items array is the one case that fails the render_ui tool call outright with an error you can see and retry.

Boundary with artifacts (write_file / edit_file / show_artifact)

GenUI and the Artifacts panel look similar from the outside — both let you produce something other than plain text — but they solve different problems, and routing the wrong content through the wrong one produces a bad result that won't error, it'll just look wrong:

• Use write_file/edit_file/show_artifact when the output is a deliverable that should survive this reply: a document, a standalone interactive page, an image — something the user might reopen, export, or refer back to later, independent of this conversation turn.
• Use render_ui/octo-ui for disposable structure inside this one reply that the user might act on right now — a quick comparison, a status summary, a small form — that has no reason to exist as a file.

The same line separates a plot node from a charting artifact. A chart the user is about to filter belongs in the panel. A visualization that is itself the deliverable — something needing a heatmap, a sankey, a map, brush-and-zoom, or a charting library's full expressiveness — belongs in an artifact, where you can write a real page with real code.

Never route a report-sized document or a large dataset through a GenUI table or list node just because the user asked for "a table." The guard caps above are enforced by silent truncation, not by a rejection you'd notice: a 900-row table becomes a 500-row table with no error, no warning in your tool result, and no indication to you that anything was cut. If the content genuinely doesn't fit inside a normal reply, that's the signal it belongs in a written artifact instead, not a signal to compress it into a GenUI node and hope the caps are generous enough.