Show a person a page from your data
afui show renders a template from the data you give it and puts the page in
front of one person. The page is A2UI 1.0. The person acts on it, the template
decides which action is the answer, and one result comes back.
afui show ask --data '{"questions":[{"id":"next","question":"What should happen next?","options":[{"id":"retry","label":"Retry","recommended":true},{"id":"stop","label":"Stop"}]}]}'
Two templates are built in. ask is the standard question page (below). a2ui
takes A2UI messages exactly as you wrote them and shows them. Anything else is
a template of your own.
What a template is
A template is a directory:
| File | What it is |
|---|---|
template.json | {"contract": "ask@1", "a2ui": "1.0"}. Required. |
request.json.j2 | Renders the data into the request: messages, optional assets and title. Required. |
input.schema.json | A JSON Schema the data must satisfy, checked before anything opens. Without it the data only has to be a JSON object. |
submit.schema.json.j2 | Renders a JSON Schema from the data; an action the page sends back must satisfy it, or it is refused and the page stays open. Without it every action is accepted. |
result.json.j2 | Renders the result the caller receives from the data and the action. Without it the result is the action’s context. |
snapshot.html.j2 | Renders the snapshot a host shows for the session. Without it the host’s generic snapshot is used. |
Templates are MiniJinja. In the JSON files every
{{ value }} is written as one complete JSON value, quoted and escaped as JSON
needs, so what the data says cannot add structure to the output: write
"text": {{ title }}, not "text": "{{ title }}". A name the data does not
define is an error. Test for one with is defined. The snapshot is HTML and
escapes what it prints.
What a template renders is checked like a request written by hand: it must be A2UI 1.0 messages that follow the schemas, with images and sizes inside the limits. A template can do exactly what a caller writing A2UI directly could.
The contract
contract is <name>@<number>: lowercase letters, digits and -, then a
positive integer. It describes what the template takes (input.schema.json) and
gives back (result.json.j2), not its directory name, so a copy that only
changes the layout can keep declaring ask@1. The result of afui show names the
contract it came from, and --expect-contract ask@1 refuses a template that
declares another, before anything opens.
a2ui is the A2UI version the messages are written for. This build renders 1.0
and says so in afui --version. A template declaring another version is refused
with a2ui_version_unsupported, which names both.
Where a name is found
afui show NAME looks in the workspace’s .afui/templates/NAME, then in the
global configuration’s templates/NAME, then among the presets. The first
place with a directory by that name supplies all of it: files are never mixed
between places, so a template that leaves out an optional file does not pick up
the preset’s.
A workspace template is another person’s checkout until someone trusts it. It is
used only after afui template enable NAME, and any change to any file in it
withdraws that; until then afui show fails with template_untrusted rather
than quietly showing something other than what was asked. A global template is the
user’s own configuration and needs no enabling. --safe-mode uses the
presets only. --template-dir PATH uses that directory as given, with no lookup
and no trust step, because it is exactly as trusted as the data you pass.
afui template list # what can be named
afui template init polite-ask --from ask # copy a template to start from
afui template check polite-ask # contract, A2UI version, trust
afui template enable polite-ask # trust the workspace copy as it is now
afui template diff polite-ask # workspace against global
afui template disable polite-ask
init copies a whole template into the workspace (--scope global for the global
configuration). The copy is yours: it does not follow the preset when AFUI
changes.
Data, delivery and results
--data takes the data as literal JSON, file:PATH (the whole file), stdin,
fd:N or env:NAME; file:PATH#DOT_PATH reads one addressed value. Sources are
capped at 16 MiB and a rendered request at 1 MiB. Relative image paths resolve
from the working directory.
--mode window|link|session uses the delivery resolver, including
AFUI_LAUNCH_FILE. A session page requires a writable session registry.
--render prints the rendered request and stops: nothing opens, no credential is
issued. What it prints is the input of the a2ui template, so
afui show ask --data ... --render | afui show a2ui --data stdin shows the same
page. --render cannot be combined with --mode or --detach.
The readiness progress event has phase: "show_ready", the contract, the session
ID and the resolved delivery facts. It never carries the data. Only link delivery
publishes its handoff URL, through the existing readiness helper.
The terminal result:
code | Meaning | Fields |
|---|---|---|
show_completed | an action the template accepted ended the page | contract, action (name, surface_id, source_component_id, context), result |
show_closed | a person closed the window, or the session was ended from outside | none |
show_expired | the attention policy lapsed | none |
All three are successful interactions (exit 0). Taking a cancel button is just
another action: the caller reads action.name. Setup, validation and transport
failures are structured errors with exit 1; CLI grammar errors keep exit 2.
The error codes say which part is at fault: template_* for the template itself
(template_not_found, template_untrusted, template_invalid,
template_render_failed, template_contract_mismatch), data_invalid for data
the input schema refuses, with a JSON Pointer path and never the value, and
a2ui_* for what the template rendered (a2ui_message_invalid with the path of
the fault, a2ui_asset_unreadable, a2ui_request_too_large, and so on).
submit_invalid is the refusal shown to the person on the page; it names the
place in the submitted action, never the text.
The session ends when the template accepts an action
The page sends actions and data to AFUI’s Provider; the Provider decides whether
that is enough. For afui show, the Provider is the template: the first action
that satisfies submit.schema.json.j2 (or any action, when there is none) ends
the session, and the page closes. A refused action leaves the page open with the
reason, so the person can correct it.
Waiting without holding a command open
afui show blocks until the page ends. A caller whose commands have a time limit
uses --detach: the page runs in a background process and the command returns as
soon as it is ready. The data goes to the worker over stdin, never argv, and the
worker reads every image before reporting readiness, so after show_started the
source files may be removed:
{"kind":"result","result":{"code":"show_started","mode":"session","session_id":"4181c256…"},"trace":{}}
afui session wait <session_id> returns the terminal result afui show would
have printed. With --timeout-s N it stops after N seconds and reports
show_pending with waiting_s, the page still open. Omit the flag or use 0 to
wait until it ends; negative values are CLI errors. A result is collected once:
a later wait returns show_not_found. The worker records its ending in an
owner-only directory beside the session registry, so --detach is refused with
show_detach_unavailable when that registry cannot be opened. The worker leaves the caller’s process group, so a caller that kills
its command on timeout does not take the page with it. AFUI does not remind the
person: it does not know where they are.
Window failures keep AFUI’s error kind with a show_ prefix: a nonzero or
signal exit is show_window_wait_failed, and a successful exit without a page
request carrying this launch’s query ID is show_window_unavailable. A
successful exit after the page arrived is show_closed, which supplies no result
and implies no consent.
The ask template
An agent often needs a person’s answer to a few questions, each with suggested
answers, while leaving room for something the list did not anticipate. ask
owns that interaction: background context, one to eight questions, one answer
per question. It displays evidence for a judgment and collects choices and text.
Domain operations, dynamic forms and sustained interaction belong in a template
of your own or a Provider page. Nothing the person answers is ever executed, and
the page renders no Markdown or HTML.
The data is context (optional) and questions:
{"context":[
{"type":"paragraph","text":"The review found two issues."},
{"type":"table","columns":["ID","Status"],"rows":[["A","Ready"]]}
],"questions":[
{"id":"scope","question":"Which should be fixed?","multiple":true,
"options":[{"id":"readme","label":"README"},{"id":"subject","label":"Subject","description":"The session subject"}]},
{"id":"when","question":"When to release?","allow_custom":false,
"options":[{"id":"now","label":"Now","recommended":true},{"id":"later","label":"Later"}]}
]}
An option has a stable id, a human label, an optional description and an
optional recommended flag. A question has an id, the question text, its
options, optional multiple (several choices) and optional allow_custom
(default true). Context blocks are paragraph {text}, list {items},
code {text}, image {path,title}, table {columns,rows} and diff {text}.
Images are local PNG, JPEG or WebP files with matching signatures, up to 16 of
8 MiB and 32 MiB in all; URLs and SVG are refused, and the page gets a
controlled reference, never a local path.
The input schema holds these bounds, and unknown fields and block types are refused:
| Item | Bound |
|---|---|
| questions | 1–8 |
| question text | non-blank, at most 8192 characters |
| options per question | 0–32; none requires allow_custom true; at most one recommended |
| IDs | 1–64 ASCII letters, digits, underscores or hyphens |
| option label / description | non-blank label up to 1024 characters; description up to 4096 |
| context | at most 32 blocks; paragraph and code up to 8192 characters; lists of 1–32 items up to 1024 |
| table | 1–32 columns, up to 128 rows; headings non-blank, cells up to 1024 |
| diff | non-blank, up to 65536 characters |
| written answer | at most 16384 characters |
A schema cannot say that IDs are unique or that every table row is as long as its columns, so those are left to whoever writes the request; a repeated ID makes the result ambiguous.
The page shows the context, then the questions. A single-choice question takes one option or the person’s own words, never both; a multiple-choice question may combine them. Recommended options are marked in their label and never preselected. Written text is kept exactly as typed, and blank text counts as no answer. A submission that does not satisfy that is refused with the place of the fault and the page stays open. Cancel needs no answers.
The result of a submitted ask page:
{"kind":"result","result":{"code":"show_completed","contract":"ask@1",
"action":{"name":"submit","surface_id":"ask","source_component_id":"submit","context":{"answers":[]}},
"result":{"cancelled":false,"answers":[
{"question_id":"scope","selected":[{"option_id":"readme","label":"README"}],"text":"Also check the skill"},
{"question_id":"when","selected":[],"text":null}
]}},"trace":{}}
selected lists the chosen options with their labels, in the order chosen, and
text is the person’s own words, null when they wrote none. A cancelled page has
{"cancelled":true,"answers":[]}. The registry subject of a page is the first
line of its first question, shortened to 80 characters.
The a2ui template
afui show a2ui --data takes messages (A2UI 1.0 messages), optional assets
(names to local image paths, referenced as asset:<name> in an Image’s url) and
optional title (what the host calls the page, 1–80 characters). With no submit
schema the first action ends the session and the result is its context.
{"messages":[
{"version":"1.0","createSurface":{"surfaceId":"main","catalogId":"https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json"}},
{"version":"1.0","updateComponents":{"surfaceId":"main","components":[
{"id":"root","component":"Column","children":["label","button"]},
{"id":"label","component":"Text","text":"Ready?"},
{"id":"button","component":"Button","child":"button-label","action":{"event":{"name":"done"}}},
{"id":"button-label","component":"Text","text":"Done"}
]}}
],"title":"Review"}
The page renders the Basic Catalog: Text (with # headings), Image, Icon, Video,
AudioPlayer, Row, Column, List, Card, Tabs, Divider, Modal, Button, TextField,
CheckBox, ChoicePicker, Slider and DateTimeInput, with the Basic Catalog’s
functions (required, regex, length, numeric, email, and, or, not,
formatString, formatNumber, formatCurrency, formatDate, pluralize,
openUrl). Schema errors name a JSON Pointer without echoing the rejected value.
External media is blocked. A reload starts a fresh draft. Presentation overrides
follow the afui / show frontend contract and cannot supply behavior.
A Rust program serving A2UI itself uses A2uiSession
rather than a template.