Skip to content
Registry

a2ui

v0.1.20

Compose, validate, persist, and render A2UI v0.9.1 surfaces for Harness sessions in chat and on an injectable Console page.

license: Apache-2.0a2uiagent-uiconsolegenerative-uiharness

Install

bash
iii trigger compose::add worker=a2ui

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions26

a2ui::action

Function

Console-only: persist an A2UI component action and forward it as a structured message to the originating Harness session.

Request
  • action_idstringrequired

    Stable client-generated id reused when Harness delivery is retried.

  • contextunknown
  • data_modelunknown

    Full client-side model when createSurface.sendDataModel requested it.

  • expected_revisioninteger· uint64requiredmin 0

    Reject a gesture rendered from stale surface state.

  • namestringrequired
  • source_component_idstringrequired
  • surface_idstringrequired
Response
  • acceptedbooleanrequired
  • forward_errorstring
  • forwardedbooleanrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • surface_idstringrequired
  • turn_idstring

a2ui::binding::apply

Function

Console-only: persist a value delivered by a declared A2UI live binding.

Request
  • binding_idstringrequired
  • surface_idstringrequired

    Surface receiving the event value.

  • valueunknownrequired
Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::binding::delete

Function

Remove a declarative live event binding from an A2UI surface.

Request
  • binding_idstringrequired
  • surface_idstringrequired

    Surface that owns the binding.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::binding::refresh

Function

Console-only: run a live binding's declared read-only provider query and persist the result into the surface data model.

Request
  • binding_idstringrequired

    Binding whose declared provider query should run.

  • surface_idstringrequired

    Surface that owns the binding.

Response
  • catalog_idstringrequired
  • changedbooleanrequired

    False when the stored value already matched and nothing was written.

  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired
  • valueunknownrequired

    Value now stored at the binding's target path.

a2ui::binding::set

Function

Attach a declarative live binding to a surface: a worker-owned trigger type (optionally with its provider's read-only query), state, or shell::changed. Legacy stream bindings are deprecated.

Request
  • bindingobjectrequired

    Declarative live-data binding rendered by the Console: the page registers `trigger_type`/`config` for its own view and writes delivered values to `target_path`. Bindings cannot invoke arbitrary functions.

    • configunknownrequired

      Trigger configuration, validated against the trigger type's registered configuration schema when the provider declares one.

    • event_pathstring

      JSON Pointer inside the event payload to apply (event mode only).

    • idstringrequired

      Stable binding id within the surface.

    • queryany of

      Optional provider query for worker-owned trigger types: run for the initial read, after every notification, and on reconnect.

      any of (2)
      Variant 1
      • function_idstringrequired

        Provider function that returns the current value.

      • payloadunknown

        Fixed request payload, validated against the function's request schema.

      • result_pathstring

        JSON Pointer inside the query result to apply. Defaults to the whole result.

      Variant 2
      valuenull
    • target_pathstringrequired

      JSON Pointer in the surface data model that receives the value.

    • trigger_typestringrequired

      Trigger type to bind: a worker-owned trigger type (for example `orders::changed`), `state`, or `shell::changed`. `stream` is accepted only as deprecated legacy compatibility.

  • surface_idstringrequired

    Surface that should receive live values.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • deprecationstring

    Present when the binding uses a deprecated trigger type (`stream`); the binding is stored and keeps working while iii-stream runs.

  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::generate

Function

Generate a user interface from a short description and optional data. Renders a safe A2UI v0.9.1 surface in chat and on the A2UI page, returning a compact receipt.

Request
  • dataunknown

    Optional application data. The composer should bind components to this data instead of repeating it in the component graph.

  • descriptionstringrequired

    Plain-language description of the interface to compose.

  • replaceboolean

    Replace a surface with the same id. Defaults to true.

  • surface_idstring

    Stable id to use for the generated surface. Omit for a generated id.

  • titlestring

    Human-readable title shown in the Console sidebar.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::on-config-change

Function

Internal: reload the A2UI worker from authoritative configuration after an update.

Request
  • idstring

    Advisory id only. The handler always re-fetches authoritative state.

Response
  • okbooleanrequired

a2ui::stamp-session

Function

Internal: stamp the authoritative Harness session onto A2UI calls before dispatch.

Request
  • callany of
    any of (2)
    Variant 1
    • argumentsunknown
    Variant 2
    valuenull
  • session_idstring
Response
any of (2)
Variant 1
  • decisionstringrequired
  • mutationsobjectrequired
    • argumentsunknownrequired
Variant 2
valuenull

a2ui::surface::apply

Function

Apply a batch of A2UI v0.9.1 protocol messages to a surface, validated and applied atomically to the session's durable state.

Request
  • messagesany of[]required

    Ordered A2UI v0.9.1 envelopes. One batch targets one surface and is persisted atomically after the complete batch validates.

    any of (4)
    Variant 1
    • createSurfaceobjectrequired
      Show 4 nested
      • catalogIdstringrequired
      • sendDataModelboolean
      • surfaceIdstringrequired
      • themeunknown
    • versionstringrequired
    Variant 2
    • updateComponentsobjectrequired
      Show 2 nested
      • componentsobject[]required
        Show 2 nested
        • componentstringrequired

          Component name from the negotiated catalog.

        • idstringrequired

          Unique component id within the surface. `root` is the render root.

      • surfaceIdstringrequired
    • versionstringrequired
    Variant 3
    • updateDataModelobjectrequired
      Show 3 nested
      • pathstring
      • surfaceIdstringrequired
      • valueunknown

        Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics.

    • versionstringrequired
    Variant 4
    • deleteSurfaceobjectrequired
      Show 1 nested
      • surfaceIdstringrequired
    • versionstringrequired
  • titlestring

    Optional Console title used when this batch creates a surface.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::delete

Function

Delete one A2UI surface from the current Harness session and publish the change to subscribed Console pages.

Request
  • surface_idstringrequired

    Stable surface id returned by generate, apply, or list.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::duplicate

Function

Duplicate an A2UI surface inside the current Harness session under a new stable id.

Request
  • new_surface_idstringrequired
  • surface_idstringrequired

    Existing surface to copy.

  • titlestring
Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::export

Function

Export one A2UI surface as a portable, replayable JSON package without Harness session metadata.

Request
  • surface_idstringrequired

    Stable id of the surface to export.

Response
  • catalog_idstringrequired
  • formatstringrequired
  • format_versioninteger· uint32requiredmin 0
  • messagesany of[]required
    any of (4)
    Variant 1
    • createSurfaceobjectrequired
      Show 4 nested
      • catalogIdstringrequired
      • sendDataModelboolean
      • surfaceIdstringrequired
      • themeunknown
    • versionstringrequired
    Variant 2
    • updateComponentsobjectrequired
      Show 2 nested
      • componentsobject[]required
        Show 2 nested
        • componentstringrequired

          Component name from the negotiated catalog.

        • idstringrequired

          Unique component id within the surface. `root` is the render root.

      • surfaceIdstringrequired
    • versionstringrequired
    Variant 3
    • updateDataModelobjectrequired
      Show 3 nested
      • pathstring
      • surfaceIdstringrequired
      • valueunknown

        Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics.

    • versionstringrequired
    Variant 4
    • deleteSurfaceobjectrequired
      Show 1 nested
      • surfaceIdstringrequired
    • versionstringrequired
  • protocol_versionstringrequired
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::export-code

Function

Generate source code from an A2UI surface: a React app or a data-serving iii worker.

Request
  • surface_idstringrequired

    Surface to turn into source files.

  • targetstringrequiredenum react, worker
Response
  • filesobject[]required
    • contentstringrequired
    • pathstringrequired
  • formatstringrequired
  • surface_idstringrequired

a2ui::surface::get

Function

Read one durable A2UI surface, including its flat component graph and data model, from the current Harness session.

Request
  • surface_idstringrequired

    Stable surface id returned by generate, apply, or list.

Response
  • bindingsobject[]
    • configunknownrequired

      Trigger configuration, validated against the trigger type's registered configuration schema when the provider declares one.

    • event_pathstring

      JSON Pointer inside the event payload to apply (event mode only).

    • idstringrequired

      Stable binding id within the surface.

    • queryany of

      Optional provider query for worker-owned trigger types: run for the initial read, after every notification, and on reconnect.

      any of (2)
      Variant 1
      • function_idstringrequired

        Provider function that returns the current value.

      • payloadunknown

        Fixed request payload, validated against the function's request schema.

      • result_pathstring

        JSON Pointer inside the query result to apply. Defaults to the whole result.

      Variant 2
      valuenull
    • target_pathstringrequired

      JSON Pointer in the surface data model that receives the value.

    • trigger_typestringrequired

      Trigger type to bind: a worker-owned trigger type (for example `orders::changed`), `state`, or `shell::changed`. `stream` is accepted only as deprecated legacy compatibility.

  • catalog_idstringrequired
  • componentsobject[]required
    • componentstringrequired

      Component name from the negotiated catalog.

    • idstringrequired

      Unique component id within the surface. `root` is the render root.

  • created_at_msinteger· int64required
  • data_modelunknownrequired
  • historyobject[]
    • componentsobject[]required
      • componentstringrequired

        Component name from the negotiated catalog.

      • idstringrequired

        Unique component id within the surface. `root` is the render root.

    • data_modelunknownrequired
    • last_actionany of
      any of (2)
      Variant 1
      • action_idstring
      • contextunknownrequired
      • data_modelunknown
      • namestringrequired
      • source_component_idstringrequired
      • timestamp_msinteger· int64required
      Variant 2
      valuenull
    • reasonstringrequired
    • revisioninteger· uint64requiredmin 0
    • send_data_modelbooleanrequired
    • themeunknown
    • titlestringrequired
    • updated_at_msinteger· int64required
  • last_actionany of
    any of (2)
    Variant 1
    • action_idstring
    • contextunknownrequired
    • data_modelunknown
    • namestringrequired
    • source_component_idstringrequired
    • timestamp_msinteger· int64required
    Variant 2
    valuenull
  • pinnedboolean
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • send_data_modelbooleanrequired
  • session_idstringrequired

    Authoritative Harness session stamped by the pre-trigger hook.

  • surface_idstringrequired

    Globally unique inside the session.

  • themeunknown
  • titlestringrequired
  • updated_at_msinteger· int64required

a2ui::surface::history

Function

List the saved revisions of one A2UI surface, restorable by undo.

Request
  • surface_idstringrequired

    Surface whose restorable snapshots should be listed.

Response
itemsobject[]
  • componentsobject[]required
    • componentstringrequired

      Component name from the negotiated catalog.

    • idstringrequired

      Unique component id within the surface. `root` is the render root.

  • data_modelunknownrequired
  • last_actionany of
    any of (2)
    Variant 1
    • action_idstring
    • contextunknownrequired
    • data_modelunknown
    • namestringrequired
    • source_component_idstringrequired
    • timestamp_msinteger· int64required
    Variant 2
    valuenull
  • reasonstringrequired
  • revisioninteger· uint64requiredmin 0
  • send_data_modelbooleanrequired
  • themeunknown
  • titlestringrequired
  • updated_at_msinteger· int64required

a2ui::surface::import

Function

Import a portable A2UI surface package into the current Harness session.

Request
  • packageall ofrequired

    Portable A2UI JSON package created by surface export.

    all of (1)
    Variant 1
    • catalog_idstringrequired
    • formatstringrequired
    • format_versioninteger· uint32requiredmin 0
    • messagesany of[]required
      Show 4 nested
      any of (4)
      Variant 1
      • createSurfaceobjectrequired
        Show 4 nested
        • catalogIdstringrequired
        • sendDataModelboolean
        • surfaceIdstringrequired
        • themeunknown
      • versionstringrequired
      Variant 2
      • updateComponentsobjectrequired
        Show 2 nested
        • componentsobject[]required
          Show 2 nested
          • componentstringrequired

            Component name from the negotiated catalog.

          • idstringrequired

            Unique component id within the surface. `root` is the render root.

        • surfaceIdstringrequired
      • versionstringrequired
      Variant 3
      • updateDataModelobjectrequired
        Show 3 nested
        • pathstring
        • surfaceIdstringrequired
        • valueunknown

          Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics.

      • versionstringrequired
      Variant 4
      • deleteSurfaceobjectrequired
        Show 1 nested
        • surfaceIdstringrequired
      • versionstringrequired
    • protocol_versionstringrequired
    • surface_idstringrequired
    • titlestringrequired
  • surface_idstring
  • titlestring
Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::list

Function

List the A2UI surfaces owned by the current Harness session, newest first, as compact summaries.

Request
Empty object
Response
  • countinteger· uintrequiredmin 0
  • session_idstringrequired
  • surfacesobject[]required
    • binding_countinteger· uintrequiredmin 0
    • catalog_idstringrequired
    • component_countinteger· uintrequiredmin 0
    • pinnedbooleanrequired
    • protocol_versionstringrequired
    • revisioninteger· uint64requiredmin 0
    • surface_idstringrequired
    • titlestringrequired
    • updated_at_msinteger· int64required

a2ui::surface::patch

Function

Update an A2UI surface from a plain-language instruction. Unspecified content is preserved; stale revisions are rejected.

Request
  • dataunknown

    Optional data to merge or use while composing the replacement.

  • expected_revisioninteger· uint64min 0

    Reject the update unless the surface is still at this revision.

  • instructionstringrequired

    Plain-language change to make while preserving unspecified content.

  • surface_idstringrequired

    Stable id of the surface to update.

  • titlestring

    Optional replacement title.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::pin

Function

Pin or unpin an A2UI surface so important interfaces remain first in the library.

Request
  • pinnedbooleanrequired
  • surface_idstringrequired

    Surface whose library priority should change.

Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::surface::undo

Function

Undo edits to an A2UI surface by restoring a prior revision as a new monotonic revision.

Request
  • surface_idstringrequired

    Surface to restore.

  • to_revisioninteger· uint64min 0
Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::template::apply

Function

Create a new A2UI surface from a reusable template in the current Harness session.

Request
  • surface_idstringrequired
  • template_idstringrequired

    Template to instantiate.

  • titlestring
Response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • pagestringrequired
  • protocol_versionstringrequired
  • revisioninteger· uint64requiredmin 0
  • session_idstringrequired
  • statusstringrequiredenum active, deleted
  • surface_idstringrequired
  • titlestringrequired

a2ui::template::delete

Function

Delete one reusable A2UI template from the current Harness session.

Request
  • template_idstringrequired

    Reusable template identifier.

Response
valueboolean

a2ui::template::get

Function

Read one reusable A2UI template from the current Harness session.

Request
  • template_idstringrequired

    Reusable template identifier.

Response
  • catalog_idstringrequired
  • componentsobject[]required
    • componentstringrequired

      Component name from the negotiated catalog.

    • idstringrequired

      Unique component id within the surface. `root` is the render root.

  • created_at_msinteger· int64required
  • data_modelunknownrequired
  • descriptionstringrequired
  • protocol_versionstringrequired
  • send_data_modelbooleanrequired
  • template_idstringrequired
  • themeunknown
  • titlestringrequired
  • updated_at_msinteger· int64required

a2ui::template::list

Function

List reusable A2UI templates stored for the current Harness session.

Request
Empty object
Response
  • countinteger· uintrequiredmin 0
  • templatesobject[]required
    • catalog_idstringrequired
    • componentsobject[]required
      • componentstringrequired

        Component name from the negotiated catalog.

      • idstringrequired

        Unique component id within the surface. `root` is the render root.

    • created_at_msinteger· int64required
    • data_modelunknownrequired
    • descriptionstringrequired
    • protocol_versionstringrequired
    • send_data_modelbooleanrequired
    • template_idstringrequired
    • themeunknown
    • titlestringrequired
    • updated_at_msinteger· int64required

a2ui::template::save

Function

Save an A2UI surface as a reusable template in the current Harness session.

Request
  • descriptionstring
  • surface_idstringrequired

    Surface to capture as a reusable template.

  • template_idstringrequired
  • titlestring
Response
  • catalog_idstringrequired
  • componentsobject[]required
    • componentstringrequired

      Component name from the negotiated catalog.

    • idstringrequired

      Unique component id within the surface. `root` is the render root.

  • created_at_msinteger· int64required
  • data_modelunknownrequired
  • descriptionstringrequired
  • protocol_versionstringrequired
  • send_data_modelbooleanrequired
  • template_idstringrequired
  • themeunknown
  • titlestringrequired
  • updated_at_msinteger· int64required

a2ui::ui-content

Function

Serve the a2ui worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.