Skip to content
Kimenpre-v1documentation home
Color scheme

A2UI adapter

@kimen/adapter-a2ui is Kimen’s first protocol adapter. It translates declarative A2UI messages into the neutral UI spec and renders every surface through the guarded renderer alone. The catalog and the ki-* elements are the durable assets; the adapter is disposable by design — the exact supported A2UI version(s) live in the package’s COMPAT.md, protocol churn is absorbed there, and an unabsorbable break retires the package without touching core.

The adapter owns no rendering path of its own. It builds a neutral UiSpec and hands it to renderUiSpec from @kimen/catalog; the guardrail’s four invariants (only catalog components render, only declared actions dispatch, unknown props are rejected, no code path executes from message data) are enforced there, once. Two complementary checks prove the adapter never opens a side channel: a static module boundary (no other rendering library is importable) and a runtime guarantee that every render call arrives at the guarded renderer.

import { createA2uiAdapter } from '@kimen/adapter-a2ui';
const adapter = createA2uiAdapter({
surface: document.querySelector('#genui'),
onAction: (event) => channelToAgent.send(event), // A2UI `action` round-trip
onError: (error) => channelToAgent.send(error), // VALIDATION_FAILED reports
onDegradation: (report) => log(report), // fallback gaps, as data
});
// A2UI v0.9.1 messages render as catalog components:
adapter.apply({
version: 'v0.9.1',
createSurface: {
surfaceId: 'checkout',
catalogId: 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json',
},
});
const result = adapter.apply({
version: 'v0.9.1',
updateComponents: {
surfaceId: 'checkout',
components: [
{ id: 'root', component: 'Card', child: 'confirm' },
{
id: 'confirm',
component: 'Button',
child: 'confirm-label',
action: { event: { name: 'confirm-order' } },
},
{ id: 'confirm-label', component: 'Text', text: 'Confirm order' },
],
},
});
result.ok; // true — or false with inert diagnostics naming each offender

The adapter implements A2UI 1.0 (preferred) and v0.9.1 over the basic catalog of each. Every message is validated against the version its envelope declares ("1.0", or "v0.9.1"/"v0.9"), and a surface accepts only the version that created it. The surface’s data model (bindings, updateDataModel, list templates) is resolved inside the adapter; the catalog never learns about it.

Modal uses its trigger and content references to render a button and a dialog linked within the surface. Users can open and close it through the rendered controls in both protocol versions.

An A2UI message is data, never code:

  • Basic-catalog types without a catalog counterpart degrade per node (Slider, DateTimeInput and others) to a fixed fallback that never carries agent content.
  • Image maps to ki-image. Supply the alternative text in @accessibility.label on 1.0 or accessibility.label on 0.9.1. Set hidden: true in that object for decorative images. An informative image with an empty or missing label degrades per node (missing-image-alt).
  • Icon maps to ki-icon.
  • Forbidden types reject the whole message — a type the compatibility matrix declares forbidden (e.g. raw html) is never partially rendered; so do undeclared properties and client functions that reach a browser capability (openUrl).
  • Unsupported protocol versions are rejected naming the supported set (1.0, v0.9.1, v0.9), and so is a message that uses the other version’s vocabulary.
  • Agents cannot run renderer functions: every A2UI 1.0 callRendererFunction is refused with INVALID_FUNCTION_CALL.
  • The action set is fixed: incremental updateComponents / updateDataModel messages revise the surface without discarding it, but no later update can bind an undeclared action.

Transport is caller-owned: the adapter consumes already-delivered A2UI messages and emits action and error messages to the supplied callbacks. deleteSurface drops adapter state; the host owns teardown of its surface element.

The canonical package documentation, including the compatibility policy, lives in the repository: packages/adapter-a2ui.