a2ui
v0.1.20Compose, validate, persist, and render A2UI v0.9.1 surfaces for Harness sessions in chat and on an injectable Console page.
Install
bash
iii trigger compose::add worker=a2uiRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Agent-ready brief for v0.1.20
Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.
Full markdown
The same content rendered as discrete blocks below is exposed as a single markdown document at
/registry/workers/a2ui.md. Paste it into an LLM prompt or pipe it through curl from a worker.Install
iii trigger compose::add worker=a2ui@0.1.20Dependencies
Dependency · 5Version
Readme
README.md
a2ui
The A2UI worker turns compact agent intent into validated A2UI v0.9.1 surfaces, stores them under the originating Harness conversation, renders them inline in chat and on an injectable Console page, and sends user actions back to the same conversation.
Install
iii trigger compose::add worker=a2uiQuickstart
Call a2ui::generate from a Harness turn. The Harness hook supplies the authoritative session, and the worker reads that turn's routed model, so the agent only sends intent and data:
{
"description": "A deployment approval card with service, version, risk, and approve or reject actions.",
"data": {
"service": "payments-api",
"version": "2026.08.20",
"risk": "medium"
},
"surface_id": "deployment-approval"
}The call returns a compact receipt such as { "surface_id": "deployment-approval", "revision": 3, "component_count": 11, "page": "a2ui" }. page is the console page id: an agent opens it with console::workspace::open { screen: "ext:a2ui" }. The Console keeps that receipt visible in the chat feed and expands it into the full surface on selection, while the A2UI page keeps every surface in the active conversation live through an exact-session state subscription.
Patch an existing surface with another natural-language request. Supplying expected_revision prevents an older composition from overwriting a newer edit:
{
"surface_id": "deployment-approval",
"instruction": "Add an owner field and make the risk more prominent.",
"expected_revision": 3
}Interactive surfaces automatically submit their complete bound data model with button actions, so form values are persisted and forwarded to the originating Harness turn. The page also supports bounded revision history and undo, pinning, duplication, JSON import/export, and a per-session template library.
Live bindings
a2ui::binding::set binds a JSON Pointer in the surface data model to live data. The Console page registers the binding for its own view and stores each delivered value, so a binding is active while the surface is open. Bindings are declarative and cannot invoke arbitrary functions. A surface holds at most 32 bindings.
- Worker-owned trigger types (recommended):
trigger_typeis any trigger type a worker registers, for exampleorders::changed. The type must be registered when the binding is set, andconfigis validated against the configuration schema the provider registered (withtrigger_request_format). In event mode, each event payload (orevent_pathinside it) is applied. With aquery, the event is only a notification. The page reads the provider's query when it opens the surface (after binding) and again after each notification, through the Console-onlya2ui::binding::refresh. That covers the initial read, recovery after a reconnect and latest-state semantics. The query function must be registered by the same worker that owns the trigger type, with metadata{"read_only": true}, and its payload is validated against the function's request schema. state(scope,key) andshell::changed(path) keep their exact configs.- Reserved types are rejected:
engine::*,harness::*,browser::*(Console-side registration would bypass Browser approval boundaries),a2ui::*,iii::*, anyhooktype,http,cron,queue,durable:subscriber,subscribe,stream:joinandstream:leave. stream(stream_name,group_id, optionalitem_id) is deprecated legacy compatibility. It is still accepted and keeps working on engines that run iii-stream. The receipt carries adeprecationnotice, the worker logs a warning, and the page marks the surface. Move these bindings to a worker-owned trigger type; see the guide "Migrate from iii-stream and pubsub".
Example binding to a worker-owned trigger type served by the runnable provider in examples/owned_trigger_provider.rs (cargo run --example owned_trigger_provider -- ws://127.0.0.1:49134):
{
"surface_id": "clicks",
"binding": {
"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"
}
}
}The A2UI page does not replace or embed itself in Shell or Browser. Its workspace action materializes a complete runnable React project under generated/a2ui/ in the active Harness working directory. Shell then shows the real source files and Git diffs for editing. Run the generated Vite app in Shell and open its local URL in the Browser worker for preview. The same runnable project is available as a React app ZIP through a2ui::surface::export-code; JSON exports remain portable through a2ui::surface::import.
Configuration
The configuration worker stores this worker's live settings. An optional --config YAML file seeds them on first boot:
composer_model: null # inherit the Harness turn's model
composer_provider: null # inherit its routed provider
max_output_tokens: 8192 # one composition or repair call
max_composer_input_bytes: 786432
repair_attempts: 1 # bounded validation correction
max_surfaces_per_session: 16
max_history_per_surface: 64
max_templates_per_session: 32
max_components_per_surface: 160
max_description_bytes: 32768
max_data_bytes: 524288
max_surface_bytes: 2097152 # current surface plus bounded history
max_session_bytes: 16777216 # surfaces, histories, and templates
forward_actions: true # send Console actions to harness::sendThe worker implements the stable A2UI v0.9.1 envelope with the safe urn:iii:a2ui:console:v0.1 catalog. The catalog maps declarative components onto the running Console's shared React components and design tokens; it never executes model-provided HTML, JavaScript, or CSS.
Skills
API reference (JSON)
agent-api-reference.json
{
"functions": [
{
"description": "Console-only: persist an A2UI component action and forward it as a structured message to the originating Harness session.",
"metadata": {},
"name": "a2ui::action",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"action_id": {
"description": "Stable client-generated id reused when Harness delivery is retried.",
"type": "string"
},
"context": {
"default": null
},
"data_model": {
"default": null,
"description": "Full client-side model when createSurface.sendDataModel requested it."
},
"expected_revision": {
"description": "Reject a gesture rendered from stale surface state.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"name": {
"type": "string"
},
"source_component_id": {
"type": "string"
},
"surface_id": {
"type": "string"
}
},
"required": [
"action_id",
"expected_revision",
"name",
"source_component_id",
"surface_id"
],
"title": "ActionRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"accepted": {
"type": "boolean"
},
"forward_error": {
"type": [
"string",
"null"
]
},
"forwarded": {
"type": "boolean"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"surface_id": {
"type": "string"
},
"turn_id": {
"type": [
"string",
"null"
]
}
},
"required": [
"accepted",
"forwarded",
"revision",
"session_id",
"surface_id"
],
"title": "ActionResponse",
"type": "object"
}
},
{
"description": "Console-only: persist a value delivered by a declared A2UI live binding.",
"metadata": {},
"name": "a2ui::binding::apply",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"binding_id": {
"type": "string"
},
"surface_id": {
"description": "Surface receiving the event value.",
"type": "string"
},
"value": true
},
"required": [
"binding_id",
"surface_id",
"value"
],
"title": "BindingApplyRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Remove a declarative live event binding from an A2UI surface.",
"metadata": {},
"name": "a2ui::binding::delete",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"binding_id": {
"type": "string"
},
"surface_id": {
"description": "Surface that owns the binding.",
"type": "string"
}
},
"required": [
"binding_id",
"surface_id"
],
"title": "BindingDeleteRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Console-only: run a live binding's declared read-only provider query and persist the result into the surface data model.",
"metadata": {},
"name": "a2ui::binding::refresh",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"binding_id": {
"description": "Binding whose declared provider query should run.",
"type": "string"
},
"surface_id": {
"description": "Surface that owns the binding.",
"type": "string"
}
},
"required": [
"binding_id",
"surface_id"
],
"title": "BindingRefreshRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"description": "Receipt of `a2ui::binding::refresh`.",
"properties": {
"catalog_id": {
"type": "string"
},
"changed": {
"description": "False when the stored value already matched and nothing was written.",
"type": "boolean"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
},
"value": {
"description": "Value now stored at the binding's target path."
}
},
"required": [
"catalog_id",
"changed",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title",
"value"
],
"title": "BindingRefreshReceipt",
"type": "object"
}
},
{
"description": "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.",
"metadata": {},
"name": "a2ui::binding::set",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"BindingQuery": {
"additionalProperties": false,
"description": "Read-only query a worker-owned trigger type's provider exposes for the current data. The function must be registered by the same worker as the trigger type with metadata `{\"read_only\": true}`.",
"properties": {
"function_id": {
"description": "Provider function that returns the current value.",
"type": "string"
},
"payload": {
"description": "Fixed request payload, validated against the function's request schema."
},
"result_path": {
"description": "JSON Pointer inside the query result to apply. Defaults to the whole result.",
"type": [
"string",
"null"
]
}
},
"required": [
"function_id"
],
"type": "object"
},
"LiveBinding": {
"additionalProperties": false,
"description": "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.",
"properties": {
"config": {
"description": "Trigger configuration, validated against the trigger type's registered configuration schema when the provider declares one."
},
"event_path": {
"description": "JSON Pointer inside the event payload to apply (event mode only).",
"type": [
"string",
"null"
]
},
"id": {
"description": "Stable binding id within the surface.",
"type": "string"
},
"query": {
"anyOf": [
{
"$ref": "#/definitions/BindingQuery"
},
{
"type": "null"
}
],
"description": "Optional provider query for worker-owned trigger types: run for the initial read, after every notification, and on reconnect."
},
"target_path": {
"description": "JSON Pointer in the surface data model that receives the value.",
"type": "string"
},
"trigger_type": {
"description": "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.",
"type": "string"
}
},
"required": [
"config",
"id",
"target_path",
"trigger_type"
],
"type": "object"
}
},
"properties": {
"binding": {
"$ref": "#/definitions/LiveBinding"
},
"surface_id": {
"description": "Surface that should receive live values.",
"type": "string"
}
},
"required": [
"binding",
"surface_id"
],
"title": "BindingSetRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"description": "Receipt of `a2ui::binding::set`.",
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"deprecation": {
"description": "Present when the binding uses a deprecated trigger type (`stream`); the binding is stored and keeps working while iii-stream runs.",
"type": [
"string",
"null"
]
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "BindingSetReceipt",
"type": "object"
}
},
{
"description": "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.",
"metadata": {},
"name": "a2ui::generate",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"data": {
"default": null,
"description": "Optional application data. The composer should bind components to this data instead of repeating it in the component graph."
},
"description": {
"description": "Plain-language description of the interface to compose.",
"type": "string"
},
"replace": {
"default": true,
"description": "Replace a surface with the same id. Defaults to true.",
"type": "boolean"
},
"surface_id": {
"default": null,
"description": "Stable id to use for the generated surface. Omit for a generated id.",
"type": [
"string",
"null"
]
},
"title": {
"default": null,
"description": "Human-readable title shown in the Console sidebar.",
"type": [
"string",
"null"
]
}
},
"required": [
"description"
],
"title": "GenerateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Internal: reload the A2UI worker from authoritative configuration after an update.",
"metadata": {
"internal": true
},
"name": "a2ui::on-config-change",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"default": null,
"description": "Advisory id only. The handler always re-fetches authoritative state.",
"type": [
"string",
"null"
]
}
},
"title": "OnConfigChangeEvent",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "OnConfigChangeResponse",
"type": "object"
}
},
{
"description": "Internal: stamp the authoritative Harness session onto A2UI calls before dispatch.",
"metadata": {},
"name": "a2ui::stamp-session",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"StampCall": {
"properties": {
"arguments": {
"default": null
}
},
"type": "object"
}
},
"description": "Trusted pre-trigger envelope supplied by the Harness hook runner.",
"properties": {
"call": {
"anyOf": [
{
"$ref": "#/definitions/StampCall"
},
{
"type": "null"
}
]
},
"session_id": {
"default": null,
"type": [
"string",
"null"
]
}
},
"title": "StampSessionEvent",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"anyOf": [
{
"$ref": "#/definitions/StampSessionResponse"
},
{
"type": "null"
}
],
"definitions": {
"HookMutations": {
"properties": {
"arguments": true
},
"required": [
"arguments"
],
"type": "object"
},
"StampSessionResponse": {
"properties": {
"decision": {
"type": "string"
},
"mutations": {
"$ref": "#/definitions/HookMutations"
}
},
"required": [
"decision",
"mutations"
],
"type": "object"
}
},
"title": "Nullable_StampSessionResponse"
}
},
{
"description": "Apply a batch of A2UI v0.9.1 protocol messages to a surface, validated and applied atomically to the session's durable state.",
"metadata": {},
"name": "a2ui::surface::apply",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"CreateSurface": {
"additionalProperties": false,
"properties": {
"catalogId": {
"type": "string"
},
"sendDataModel": {
"type": [
"boolean",
"null"
]
},
"surfaceId": {
"type": "string"
},
"theme": true
},
"required": [
"catalogId",
"surfaceId"
],
"type": "object"
},
"CreateSurfaceMessage": {
"additionalProperties": false,
"properties": {
"createSurface": {
"$ref": "#/definitions/CreateSurface"
},
"version": {
"type": "string"
}
},
"required": [
"createSurface",
"version"
],
"type": "object"
},
"DeleteSurface": {
"additionalProperties": false,
"properties": {
"surfaceId": {
"type": "string"
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"DeleteSurfaceMessage": {
"additionalProperties": false,
"properties": {
"deleteSurface": {
"$ref": "#/definitions/DeleteSurface"
},
"version": {
"type": "string"
}
},
"required": [
"deleteSurface",
"version"
],
"type": "object"
},
"ServerMessage": {
"anyOf": [
{
"$ref": "#/definitions/CreateSurfaceMessage"
},
{
"$ref": "#/definitions/UpdateComponentsMessage"
},
{
"$ref": "#/definitions/UpdateDataModelMessage"
},
{
"$ref": "#/definitions/DeleteSurfaceMessage"
}
],
"description": "Exactly one of the four A2UI v0.9.1 server-to-client envelope messages."
},
"UpdateComponents": {
"additionalProperties": false,
"properties": {
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"surfaceId": {
"type": "string"
}
},
"required": [
"components",
"surfaceId"
],
"type": "object"
},
"UpdateComponentsMessage": {
"additionalProperties": false,
"properties": {
"updateComponents": {
"$ref": "#/definitions/UpdateComponents"
},
"version": {
"type": "string"
}
},
"required": [
"updateComponents",
"version"
],
"type": "object"
},
"UpdateDataModel": {
"additionalProperties": false,
"properties": {
"path": {
"type": [
"string",
"null"
]
},
"surfaceId": {
"type": "string"
},
"value": {
"description": "Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics."
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"UpdateDataModelMessage": {
"additionalProperties": false,
"properties": {
"updateDataModel": {
"$ref": "#/definitions/UpdateDataModel"
},
"version": {
"type": "string"
}
},
"required": [
"updateDataModel",
"version"
],
"type": "object"
}
},
"properties": {
"messages": {
"description": "Ordered A2UI v0.9.1 envelopes. One batch targets one surface and is persisted atomically after the complete batch validates.",
"items": {
"$ref": "#/definitions/ServerMessage"
},
"type": "array"
},
"title": {
"default": null,
"description": "Optional Console title used when this batch creates a surface.",
"type": [
"string",
"null"
]
}
},
"required": [
"messages"
],
"title": "ApplyRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Delete one A2UI surface from the current Harness session and publish the change to subscribed Console pages.",
"metadata": {},
"name": "a2ui::surface::delete",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Remove one surface from the current Harness session.",
"properties": {
"surface_id": {
"description": "Stable surface id returned by generate, apply, or list.",
"type": "string"
}
},
"required": [
"surface_id"
],
"title": "DeleteRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Duplicate an A2UI surface inside the current Harness session under a new stable id.",
"metadata": {},
"name": "a2ui::surface::duplicate",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"new_surface_id": {
"type": "string"
},
"surface_id": {
"description": "Existing surface to copy.",
"type": "string"
},
"title": {
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"new_surface_id",
"surface_id"
],
"title": "DuplicateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Export one A2UI surface as a portable, replayable JSON package without Harness session metadata.",
"metadata": {},
"name": "a2ui::surface::export",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"surface_id": {
"description": "Stable id of the surface to export.",
"type": "string"
}
},
"required": [
"surface_id"
],
"title": "ExportRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"CreateSurface": {
"additionalProperties": false,
"properties": {
"catalogId": {
"type": "string"
},
"sendDataModel": {
"type": [
"boolean",
"null"
]
},
"surfaceId": {
"type": "string"
},
"theme": true
},
"required": [
"catalogId",
"surfaceId"
],
"type": "object"
},
"CreateSurfaceMessage": {
"additionalProperties": false,
"properties": {
"createSurface": {
"$ref": "#/definitions/CreateSurface"
},
"version": {
"type": "string"
}
},
"required": [
"createSurface",
"version"
],
"type": "object"
},
"DeleteSurface": {
"additionalProperties": false,
"properties": {
"surfaceId": {
"type": "string"
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"DeleteSurfaceMessage": {
"additionalProperties": false,
"properties": {
"deleteSurface": {
"$ref": "#/definitions/DeleteSurface"
},
"version": {
"type": "string"
}
},
"required": [
"deleteSurface",
"version"
],
"type": "object"
},
"ServerMessage": {
"anyOf": [
{
"$ref": "#/definitions/CreateSurfaceMessage"
},
{
"$ref": "#/definitions/UpdateComponentsMessage"
},
{
"$ref": "#/definitions/UpdateDataModelMessage"
},
{
"$ref": "#/definitions/DeleteSurfaceMessage"
}
],
"description": "Exactly one of the four A2UI v0.9.1 server-to-client envelope messages."
},
"UpdateComponents": {
"additionalProperties": false,
"properties": {
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"surfaceId": {
"type": "string"
}
},
"required": [
"components",
"surfaceId"
],
"type": "object"
},
"UpdateComponentsMessage": {
"additionalProperties": false,
"properties": {
"updateComponents": {
"$ref": "#/definitions/UpdateComponents"
},
"version": {
"type": "string"
}
},
"required": [
"updateComponents",
"version"
],
"type": "object"
},
"UpdateDataModel": {
"additionalProperties": false,
"properties": {
"path": {
"type": [
"string",
"null"
]
},
"surfaceId": {
"type": "string"
},
"value": {
"description": "Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics."
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"UpdateDataModelMessage": {
"additionalProperties": false,
"properties": {
"updateDataModel": {
"$ref": "#/definitions/UpdateDataModel"
},
"version": {
"type": "string"
}
},
"required": [
"updateDataModel",
"version"
],
"type": "object"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"format": {
"type": "string"
},
"format_version": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"messages": {
"items": {
"$ref": "#/definitions/ServerMessage"
},
"type": "array"
},
"protocol_version": {
"type": "string"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"format",
"format_version",
"messages",
"protocol_version",
"surface_id",
"title"
],
"title": "SurfaceExport",
"type": "object"
}
},
{
"description": "Generate source code from an A2UI surface: a React app or a data-serving iii worker.",
"metadata": {},
"name": "a2ui::surface::export-code",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"CodeTarget": {
"enum": [
"react",
"worker"
],
"type": "string"
}
},
"properties": {
"surface_id": {
"description": "Surface to turn into source files.",
"type": "string"
},
"target": {
"$ref": "#/definitions/CodeTarget"
}
},
"required": [
"surface_id",
"target"
],
"title": "ExportCodeRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"CodeFile": {
"properties": {
"content": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"content",
"path"
],
"type": "object"
}
},
"properties": {
"files": {
"items": {
"$ref": "#/definitions/CodeFile"
},
"type": "array"
},
"format": {
"type": "string"
},
"surface_id": {
"type": "string"
}
},
"required": [
"files",
"format",
"surface_id"
],
"title": "CodeExport",
"type": "object"
}
},
{
"description": "Read one durable A2UI surface, including its flat component graph and data model, from the current Harness session.",
"metadata": {},
"name": "a2ui::surface::get",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Select one surface in the current Harness session.",
"properties": {
"surface_id": {
"description": "Stable surface id returned by generate, apply, or list.",
"type": "string"
}
},
"required": [
"surface_id"
],
"title": "GetRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ActionRecord": {
"properties": {
"action_id": {
"default": "",
"type": "string"
},
"context": true,
"data_model": true,
"name": {
"type": "string"
},
"source_component_id": {
"type": "string"
},
"timestamp_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"context",
"name",
"source_component_id",
"timestamp_ms"
],
"type": "object"
},
"BindingQuery": {
"additionalProperties": false,
"description": "Read-only query a worker-owned trigger type's provider exposes for the current data. The function must be registered by the same worker as the trigger type with metadata `{\"read_only\": true}`.",
"properties": {
"function_id": {
"description": "Provider function that returns the current value.",
"type": "string"
},
"payload": {
"description": "Fixed request payload, validated against the function's request schema."
},
"result_path": {
"description": "JSON Pointer inside the query result to apply. Defaults to the whole result.",
"type": [
"string",
"null"
]
}
},
"required": [
"function_id"
],
"type": "object"
},
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"LiveBinding": {
"additionalProperties": false,
"description": "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.",
"properties": {
"config": {
"description": "Trigger configuration, validated against the trigger type's registered configuration schema when the provider declares one."
},
"event_path": {
"description": "JSON Pointer inside the event payload to apply (event mode only).",
"type": [
"string",
"null"
]
},
"id": {
"description": "Stable binding id within the surface.",
"type": "string"
},
"query": {
"anyOf": [
{
"$ref": "#/definitions/BindingQuery"
},
{
"type": "null"
}
],
"description": "Optional provider query for worker-owned trigger types: run for the initial read, after every notification, and on reconnect."
},
"target_path": {
"description": "JSON Pointer in the surface data model that receives the value.",
"type": "string"
},
"trigger_type": {
"description": "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.",
"type": "string"
}
},
"required": [
"config",
"id",
"target_path",
"trigger_type"
],
"type": "object"
},
"SurfaceRevision": {
"properties": {
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"data_model": true,
"last_action": {
"anyOf": [
{
"$ref": "#/definitions/ActionRecord"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"send_data_model": {
"type": "boolean"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"components",
"data_model",
"reason",
"revision",
"send_data_model",
"title",
"updated_at_ms"
],
"type": "object"
}
},
"properties": {
"bindings": {
"default": [],
"items": {
"$ref": "#/definitions/LiveBinding"
},
"type": "array"
},
"catalog_id": {
"type": "string"
},
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"created_at_ms": {
"format": "int64",
"type": "integer"
},
"data_model": true,
"history": {
"default": [],
"items": {
"$ref": "#/definitions/SurfaceRevision"
},
"type": "array"
},
"last_action": {
"anyOf": [
{
"$ref": "#/definitions/ActionRecord"
},
{
"type": "null"
}
]
},
"pinned": {
"default": false,
"type": "boolean"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"send_data_model": {
"type": "boolean"
},
"session_id": {
"description": "Authoritative Harness session stamped by the pre-trigger hook.",
"type": "string"
},
"surface_id": {
"description": "Globally unique inside the session.",
"type": "string"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"catalog_id",
"components",
"created_at_ms",
"data_model",
"protocol_version",
"revision",
"send_data_model",
"session_id",
"surface_id",
"title",
"updated_at_ms"
],
"title": "SurfaceRecord",
"type": "object"
}
},
{
"description": "List the saved revisions of one A2UI surface, restorable by undo.",
"metadata": {},
"name": "a2ui::surface::history",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"surface_id": {
"description": "Surface whose restorable snapshots should be listed.",
"type": "string"
}
},
"required": [
"surface_id"
],
"title": "HistoryRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ActionRecord": {
"properties": {
"action_id": {
"default": "",
"type": "string"
},
"context": true,
"data_model": true,
"name": {
"type": "string"
},
"source_component_id": {
"type": "string"
},
"timestamp_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"context",
"name",
"source_component_id",
"timestamp_ms"
],
"type": "object"
},
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"SurfaceRevision": {
"properties": {
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"data_model": true,
"last_action": {
"anyOf": [
{
"$ref": "#/definitions/ActionRecord"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"send_data_model": {
"type": "boolean"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"components",
"data_model",
"reason",
"revision",
"send_data_model",
"title",
"updated_at_ms"
],
"type": "object"
}
},
"items": {
"$ref": "#/definitions/SurfaceRevision"
},
"title": "Array_of_SurfaceRevision",
"type": "array"
}
},
{
"description": "Import a portable A2UI surface package into the current Harness session.",
"metadata": {},
"name": "a2ui::surface::import",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"CreateSurface": {
"additionalProperties": false,
"properties": {
"catalogId": {
"type": "string"
},
"sendDataModel": {
"type": [
"boolean",
"null"
]
},
"surfaceId": {
"type": "string"
},
"theme": true
},
"required": [
"catalogId",
"surfaceId"
],
"type": "object"
},
"CreateSurfaceMessage": {
"additionalProperties": false,
"properties": {
"createSurface": {
"$ref": "#/definitions/CreateSurface"
},
"version": {
"type": "string"
}
},
"required": [
"createSurface",
"version"
],
"type": "object"
},
"DeleteSurface": {
"additionalProperties": false,
"properties": {
"surfaceId": {
"type": "string"
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"DeleteSurfaceMessage": {
"additionalProperties": false,
"properties": {
"deleteSurface": {
"$ref": "#/definitions/DeleteSurface"
},
"version": {
"type": "string"
}
},
"required": [
"deleteSurface",
"version"
],
"type": "object"
},
"ServerMessage": {
"anyOf": [
{
"$ref": "#/definitions/CreateSurfaceMessage"
},
{
"$ref": "#/definitions/UpdateComponentsMessage"
},
{
"$ref": "#/definitions/UpdateDataModelMessage"
},
{
"$ref": "#/definitions/DeleteSurfaceMessage"
}
],
"description": "Exactly one of the four A2UI v0.9.1 server-to-client envelope messages."
},
"SurfaceExport": {
"properties": {
"catalog_id": {
"type": "string"
},
"format": {
"type": "string"
},
"format_version": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"messages": {
"items": {
"$ref": "#/definitions/ServerMessage"
},
"type": "array"
},
"protocol_version": {
"type": "string"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"format",
"format_version",
"messages",
"protocol_version",
"surface_id",
"title"
],
"type": "object"
},
"UpdateComponents": {
"additionalProperties": false,
"properties": {
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"surfaceId": {
"type": "string"
}
},
"required": [
"components",
"surfaceId"
],
"type": "object"
},
"UpdateComponentsMessage": {
"additionalProperties": false,
"properties": {
"updateComponents": {
"$ref": "#/definitions/UpdateComponents"
},
"version": {
"type": "string"
}
},
"required": [
"updateComponents",
"version"
],
"type": "object"
},
"UpdateDataModel": {
"additionalProperties": false,
"properties": {
"path": {
"type": [
"string",
"null"
]
},
"surfaceId": {
"type": "string"
},
"value": {
"description": "Omit or set null to remove the path. At `/` this replaces the whole data model, matching A2UI v0.9.1 root-update semantics."
}
},
"required": [
"surfaceId"
],
"type": "object"
},
"UpdateDataModelMessage": {
"additionalProperties": false,
"properties": {
"updateDataModel": {
"$ref": "#/definitions/UpdateDataModel"
},
"version": {
"type": "string"
}
},
"required": [
"updateDataModel",
"version"
],
"type": "object"
}
},
"properties": {
"package": {
"allOf": [
{
"$ref": "#/definitions/SurfaceExport"
}
],
"description": "Portable A2UI JSON package created by surface export."
},
"surface_id": {
"default": null,
"type": [
"string",
"null"
]
},
"title": {
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"package"
],
"title": "ImportRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "List the A2UI surfaces owned by the current Harness session, newest first, as compact summaries.",
"metadata": {},
"name": "a2ui::surface::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "List the surfaces belonging to the current Harness session. List generated surfaces in the authoritative Harness session.",
"title": "ListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceSummary": {
"properties": {
"binding_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"pinned": {
"type": "boolean"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"binding_count",
"catalog_id",
"component_count",
"pinned",
"protocol_version",
"revision",
"surface_id",
"title",
"updated_at_ms"
],
"type": "object"
}
},
"properties": {
"count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"surfaces": {
"items": {
"$ref": "#/definitions/SurfaceSummary"
},
"type": "array"
}
},
"required": [
"count",
"session_id",
"surfaces"
],
"title": "ListResponse",
"type": "object"
}
},
{
"description": "Update an A2UI surface from a plain-language instruction. Unspecified content is preserved; stale revisions are rejected.",
"metadata": {},
"name": "a2ui::surface::patch",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"data": {
"default": null,
"description": "Optional data to merge or use while composing the replacement."
},
"expected_revision": {
"default": null,
"description": "Reject the update unless the surface is still at this revision.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"instruction": {
"description": "Plain-language change to make while preserving unspecified content.",
"type": "string"
},
"surface_id": {
"description": "Stable id of the surface to update.",
"type": "string"
},
"title": {
"default": null,
"description": "Optional replacement title.",
"type": [
"string",
"null"
]
}
},
"required": [
"instruction",
"surface_id"
],
"title": "PatchRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Pin or unpin an A2UI surface so important interfaces remain first in the library.",
"metadata": {},
"name": "a2ui::surface::pin",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"pinned": {
"type": "boolean"
},
"surface_id": {
"description": "Surface whose library priority should change.",
"type": "string"
}
},
"required": [
"pinned",
"surface_id"
],
"title": "PinRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Undo edits to an A2UI surface by restoring a prior revision as a new monotonic revision.",
"metadata": {},
"name": "a2ui::surface::undo",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"surface_id": {
"description": "Surface to restore.",
"type": "string"
},
"to_revision": {
"default": null,
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"surface_id"
],
"title": "UndoRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Create a new A2UI surface from a reusable template in the current Harness session.",
"metadata": {},
"name": "a2ui::template::apply",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"surface_id": {
"type": "string"
},
"template_id": {
"description": "Template to instantiate.",
"type": "string"
},
"title": {
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"surface_id",
"template_id"
],
"title": "TemplateApplyRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SurfaceStatus": {
"enum": [
"active",
"deleted"
],
"type": "string"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"component_count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"page": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"revision": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/SurfaceStatus"
},
"surface_id": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"catalog_id",
"component_count",
"page",
"protocol_version",
"revision",
"session_id",
"status",
"surface_id",
"title"
],
"title": "SurfaceReceipt",
"type": "object"
}
},
{
"description": "Delete one reusable A2UI template from the current Harness session.",
"metadata": {},
"name": "a2ui::template::delete",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"template_id": {
"description": "Reusable template identifier.",
"type": "string"
}
},
"required": [
"template_id"
],
"title": "TemplateSelectRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Boolean",
"type": "boolean"
}
},
{
"description": "Read one reusable A2UI template from the current Harness session.",
"metadata": {},
"name": "a2ui::template::get",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"template_id": {
"description": "Reusable template identifier.",
"type": "string"
}
},
"required": [
"template_id"
],
"title": "TemplateSelectRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"created_at_ms": {
"format": "int64",
"type": "integer"
},
"data_model": true,
"description": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"send_data_model": {
"type": "boolean"
},
"template_id": {
"type": "string"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"catalog_id",
"components",
"created_at_ms",
"data_model",
"description",
"protocol_version",
"send_data_model",
"template_id",
"title",
"updated_at_ms"
],
"title": "SurfaceTemplate",
"type": "object"
}
},
{
"description": "List reusable A2UI templates stored for the current Harness session.",
"metadata": {},
"name": "a2ui::template::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "List reusable templates in the authoritative Harness session.",
"title": "TemplateListRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
},
"SurfaceTemplate": {
"properties": {
"catalog_id": {
"type": "string"
},
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"created_at_ms": {
"format": "int64",
"type": "integer"
},
"data_model": true,
"description": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"send_data_model": {
"type": "boolean"
},
"template_id": {
"type": "string"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"catalog_id",
"components",
"created_at_ms",
"data_model",
"description",
"protocol_version",
"send_data_model",
"template_id",
"title",
"updated_at_ms"
],
"type": "object"
}
},
"properties": {
"count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"templates": {
"items": {
"$ref": "#/definitions/SurfaceTemplate"
},
"type": "array"
}
},
"required": [
"count",
"templates"
],
"title": "TemplateListResponse",
"type": "object"
}
},
{
"description": "Save an A2UI surface as a reusable template in the current Harness session.",
"metadata": {},
"name": "a2ui::template::save",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"description": {
"default": "",
"type": "string"
},
"surface_id": {
"description": "Surface to capture as a reusable template.",
"type": "string"
},
"template_id": {
"type": "string"
},
"title": {
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"surface_id",
"template_id"
],
"title": "TemplateSaveRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Component": {
"additionalProperties": true,
"properties": {
"component": {
"description": "Component name from the negotiated catalog.",
"type": "string"
},
"id": {
"description": "Unique component id within the surface. `root` is the render root.",
"type": "string"
}
},
"required": [
"component",
"id"
],
"type": "object"
}
},
"properties": {
"catalog_id": {
"type": "string"
},
"components": {
"items": {
"$ref": "#/definitions/Component"
},
"type": "array"
},
"created_at_ms": {
"format": "int64",
"type": "integer"
},
"data_model": true,
"description": {
"type": "string"
},
"protocol_version": {
"type": "string"
},
"send_data_model": {
"type": "boolean"
},
"template_id": {
"type": "string"
},
"theme": true,
"title": {
"type": "string"
},
"updated_at_ms": {
"format": "int64",
"type": "integer"
}
},
"required": [
"catalog_id",
"components",
"created_at_ms",
"data_model",
"description",
"protocol_version",
"send_data_model",
"template_id",
"title",
"updated_at_ms"
],
"title": "SurfaceTemplate",
"type": "object"
}
},
{
"description": "Serve the a2ui worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).",
"metadata": {
"internal": true
},
"name": "a2ui::ui-content",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Input of the content function: the console asks for one asset by path.",
"properties": {
"path": {
"description": "The asset path from the trigger config (e.g. `state/page.js`).",
"type": "string"
}
},
"required": [
"path"
],
"title": "UiContentInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of the content function.",
"properties": {
"content": {
"description": "The asset source, verbatim.",
"type": "string"
},
"content_type": {
"description": "MIME type the console should serve the asset with.",
"type": "string"
}
},
"required": [
"content",
"content_type"
],
"title": "UiContentResult",
"type": "object"
}
}
],
"triggers": []
}