a2ui

# a2ui Use `a2ui` when the result should be an interface the person can scan or act on. Describe the desired experience and supply the underlying data; the worker delegates composition through `llm-router`, validates A2UI v0.9.1, and returns a compact receipt while the Console renders the surface. Surfaces belong to the current Harness session. The Harness pre-trigger hook stamps that identity authoritatively, and Console actions return to the same conversation as structured user interactions. ## When to Use - Present a dashboard, status overview, comparison, form, approval, or decision surface. - Keep a result live while later function calls update its components or data model. - Let a person respond through buttons or bound inputs without asking them to author JSON. - Revise an existing interface through a plain-language patch while preserving unspecified content. - Export a finished surface as portable A2UI JSON for reuse outside the current conversation. - Reuse, undo, pin, duplicate, import, or export a surface as a runnable React app or a data-serving iii worker template. - Materialize the React app into the selected workspace when the person wants to inspect and edit its files in Shell, then preview it through Browser. - Bind surface data to a worker-owned trigger type (optionally with its provider's read-only query), exact state, or Shell change events when the UI should stay live. ## Boundaries - Do not use A2UI for plain answers that are clearer as a short message. - Generated surfaces use the fixed Console catalog; they cannot execute HTML, JavaScript, CSS, or arbitrary components. - Use `canvas` for diagrams and freeform drawing, and use a domain worker directly when no visual surface is needed. - `a2ui::action`, `a2ui::binding::apply`, `a2ui::binding::refresh`, `a2ui::stamp-session`, and `a2ui::on-config-change` are internal Console/Harness lifecycle functions, not agent tools. - Live bindings never bind `browser::*`, `harness::*`, `engine::*`, hook, `http`, `cron`, or queue trigger types. A binding `query` must be a function registered by the trigger type's own worker with metadata `{"read_only": true}`. - Do not create new `stream` bindings: `stream` is deprecated (iii-stream) and will be removed in an upcoming release. Existing ones keep working while iii-stream runs. Bind the producing worker's own trigger type instead. ## Functions - `a2ui::generate` — compose and persist a complete surface from compact intent and optional data. - `a2ui::surface::apply` — validate and atomically apply A2UI v0.9.1 messages to one surface. - `a2ui::surface::get` — read one surface with its component graph and data model. - `a2ui::surface::list` — list compact surface summaries for the current session. - `a2ui::surface::delete` — remove a surface from the current session. - `a2ui::surface::patch` — replace a surface from a natural-language change request with optional revision protection. - `a2ui::surface::export` — return a session-free, replayable A2UI JSON package. - `a2ui::surface::history`, `undo`, `duplicate`, and `pin` — manage the surface library and revisions. - `a2ui::surface::import` and `export-code` — move surfaces between sessions or into source code. - `a2ui::binding::set` and `delete` — manage safe declarative live-data bindings. Example: `{ "id": "clicks-count", "trigger_type": "demo::counter-changed", "config": { "counter": "clicks" }, "target_path": "/count", "query": { "function_id": "demo::counter::get", "payload": { "counter": "clicks" }, "result_path": "/value" } }`. - `a2ui::template::*` — save, list, read, apply, and delete reusable session templates. - `a2ui::action` — internal Console action ingress and optional Harness forwarding. - `a2ui::stamp-session` — internal Harness hook that stamps authoritative turn context. - `a2ui::on-config-change` — internal authoritative configuration reload handler.