skip to content
iii / worker
$worker

a2ui

v0.1.12

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

iiiverified
1 installs0 in 7d0 today
install
$iii trigger compose::add worker=a2ui@0.1.12
binarylicense: Apache-2.0a2uiagent-uiconsolegenerative-uiharness
  • macOS: arm64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64
25functions0triggers0skills5depsv0.1.12version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

25

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::set

function

Attach an allowlisted live state, stream, or shell event binding to a surface.

request
  • bindingobjectrequired
    • configunknownrequired
    • event_pathstring
    • idstringrequired
    • target_pathstringrequired
    • trigger_typestringrequired
  • surface_idstringrequired

    Surface that should receive live values.

response
  • catalog_idstringrequired
  • component_countinteger· uintrequiredmin 0
  • 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
      … expand 4 nested
      • catalogIdstringrequired
      • sendDataModelboolean
      • surfaceIdstringrequired
      • themeunknown
    • versionstringrequired
    variant 2
    • updateComponentsobjectrequired
      … expand 2 nested
      • componentsobject[]required
        … expand 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
      … expand 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
      … expand 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
      … expand 4 nested
      • catalogIdstringrequired
      • sendDataModelboolean
      • surfaceIdstringrequired
      • themeunknown
    • versionstringrequired
    variant 2
    • updateComponentsobjectrequired
      … expand 2 nested
      • componentsobject[]required
        … expand 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
      … expand 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
      … expand 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
    • event_pathstring
    • idstringrequired
    • target_pathstringrequired
    • trigger_typestringrequired
  • 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
      … expand 4 nested
      any of (4)
      variant 1
      • createSurfaceobjectrequired
        … expand 4 nested
        • catalogIdstringrequired
        • sendDataModelboolean
        • surfaceIdstringrequired
        • themeunknown
      • versionstringrequired
      variant 2
      • updateComponentsobjectrequired
        … expand 2 nested
        • componentsobject[]required
          … expand 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
        … expand 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
        … expand 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 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.

triggers

0
no triggers registered