feat(a2ui): v0.9 action envelope and sendDataModel transport

apps/website/content/docs/render/a2ui/catalog.mdx

@@ -159,10 +159,10 @@ Renders a button that dispatches an action when clicked.
 **Action types:**
 
 ```json
-// Emit a named event (sent back to the agent)
-{"action": {"event": {"name": "submit", "context": {"formId": "contact"}}}}
+// Emit a named event with resolved context (sent back to the agent as v0.9 action)
+{"action": {"event": {"name": "submit", "context": {"email": {"path": "/email"}, "formId": "contact"}}}}
 
-// Execute a local function (e.g., open a URL)
+// Execute a local function (e.g., open a URL) — agent never sees this
 {"action": {"functionCall": {"call": "openUrl", "args": {"url": "https://example.com"}}}}
 ```
 

apps/website/content/docs/render/a2ui/overview.mdx

@@ -289,6 +289,111 @@ Validation styling uses CSS custom properties:
 | `--a2ui-input-bg` | `rgba(255,255,255,0.05)` | Input background |
 | `--a2ui-label` | `rgba(255,255,255,0.6)` | Label text color |
 
+## Events & Data Model Transport
+
+When a user triggers an event action (e.g., clicking a button with `action.event`), the Angular renderer builds a v0.9-compliant action message and sends it back to the agent. Local actions (`action.functionCall`) execute client-side only — the agent never sees them.
+
+### Action Message Shape
+
+The outbound message follows the [v0.9 spec](https://a2ui.org):
+
+```json
+{
+  "version": "v0.9",
+  "action": {
+    "name": "formSubmit",
+    "surfaceId": "contact",
+    "sourceComponentId": "submit-btn",
+    "timestamp": "2026-04-10T14:30:00.000Z",
+    "context": {
+      "name": "Alice",
+      "email": "alice@example.com"
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `version` | Always `"v0.9"` |
+| `action.name` | The event name from the component's `action.event.name` |
+| `action.surfaceId` | The surface that owns this component |
+| `action.sourceComponentId` | The `id` of the component that triggered the event |
+| `action.timestamp` | ISO 8601 timestamp of when the action was dispatched |
+| `action.context` | Resolved values from `action.event.context` — path refs and function calls are evaluated against the current data model |
+
+### Context Resolution
+
+Context values in `action.event.context` are `DynamicValue`s — they can be literals, path references, or function calls. They are resolved at dispatch time against the current data model:
+
+```json
+{
+  "action": {
+    "event": {
+      "name": "formSubmit",
+      "context": {
+        "name": {"path": "/name"},
+        "email": {"path": "/email"},
+        "total": {"call": "formatCurrency", "args": {"value": {"path": "/amount"}}}
+      }
+    }
+  }
+}
+```
+
+When the user clicks the button, the renderer resolves `/name` and `/email` from the data model and calls `formatCurrency` on `/amount`, producing a flat `context` object with concrete values.
+
+### sendDataModel
+
+Set `sendDataModel: true` on `createSurface` to attach the full data model snapshot to every outbound action:
+
+```json
+{"type": "createSurface", "surfaceId": "contact", "catalogId": "basic", "sendDataModel": true}
+```
+
+When enabled, the action message includes a `metadata` field:
+
+```json
+{
+  "version": "v0.9",
+  "action": { "..." : "..." },
+  "metadata": {
+    "a2uiClientDataModel": {
+      "version": "v0.9",
+      "surfaces": {
+        "contact": {
+          "name": "Alice",
+          "email": "alice@example.com",
+          "department": "Engineering"
+        }
+      }
+    }
+  }
+}
+```
+
+The data model is only sent with event actions — there are no passive change notifications on input changes. This matches the v0.9 spec requirement that the data model piggybacks on outbound messages.
+
+### Angular Integration
+
+`A2uiSurfaceComponent` exposes two outputs:
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `(action)` | `A2uiActionMessage` | Agent-bound action messages — the complete v0.9 envelope |
+| `(events)` | `RenderEvent` | All render events (state changes, handler calls, lifecycle) for observation |
+
+`ChatComponent` auto-routes `(action)` events to the agent as human messages. For standalone usage, bind `(action)` directly:
+
+```html
+<a2ui-surface
+  [surface]="surface()"
+  [catalog]="catalog"
+  (action)="sendToAgent($event)"
+  (events)="logEvent($event)"
+/>
+```
+
 ## What's Next
 
 <CardGroup cols={2}>

cockpit/chat/a2ui/python/src/graph.py

@@ -12,7 +12,7 @@
 A2UI_PREFIX = "---a2ui_JSON---"
 
 CONTACT_FORM_JSONL = A2UI_PREFIX + "\n" + "\n".join([
-    json.dumps({"type": "createSurface", "surfaceId": "contact", "catalogId": "basic"}),
+    json.dumps({"type": "createSurface", "surfaceId": "contact", "catalogId": "basic", "sendDataModel": True}),
     json.dumps({"type": "updateDataModel", "surfaceId": "contact", "value": {
         "name": "", "email": "", "department": "Engineering", "consent": False,
     }}),
@@ -56,7 +56,11 @@
              ]}},
               "message": "Complete all required fields and agree to be contacted"},
          ],
-         "action": {"event": {"name": "formSubmit", "context": {"formId": "contact"}}}},
+         "action": {"event": {"name": "formSubmit", "context": {
+             "name": {"path": "/name"},
+             "email": {"path": "/email"},
+             "department": {"path": "/department"},
+         }}}},
     ]}),
 ])
 
@@ -71,10 +75,10 @@ def build_a2ui_graph():
     async def create_form(state: MessagesState) -> dict:
         last = state["messages"][-1]
 
-        # If this is an a2ui_event, route to event handling
+        # If this is a v0.9 action message, route to event handling
         try:
             payload = json.loads(last.content)
-            if isinstance(payload, dict) and payload.get("type") == "a2ui_event":
+            if isinstance(payload, dict) and payload.get("version") == "v0.9" and "action" in payload:
                 return await handle_event(state, payload)
         except (json.JSONDecodeError, AttributeError):
             pass
@@ -83,9 +87,28 @@ async def create_form(state: MessagesState) -> dict:
         return {"messages": [AIMessage(content=CONTACT_FORM_JSONL)]}
 
     async def handle_event(state: MessagesState, payload: dict) -> dict:
-        name = payload.get("context", {}).get("formId", "unknown")
+        action = payload["action"]
+        context = action.get("context", {})
+        name = context.get("name", "Unknown")
+        email = context.get("email", "not provided")
+        department = context.get("department", "not specified")
+
+        # Full data model is available via metadata when sendDataModel is true.
+        # Use it when you need values beyond what context provides.
+        data_model = (  # noqa: F841
+            payload.get("metadata", {})
+            .get("a2uiClientDataModel", {})
+            .get("surfaces", {})
+            .get(action["surfaceId"], {})
+        )
+
         return {"messages": [AIMessage(
-            content=f"Thanks for submitting the **{name}** form! We'll be in touch soon.",
+            content=(
+                f"Thanks **{name}**! We received your submission:\n\n"
+                f"- **Email:** {email}\n"
+                f"- **Department:** {department}\n\n"
+                f"We'll be in touch soon."
+            ),
         )]}
 
     graph = StateGraph(MessagesState)

libs/a2ui/src/index.ts

@@ -7,6 +7,7 @@ export type {
   A2uiComponent,
   A2uiCreateSurface, A2uiUpdateComponents, A2uiUpdateDataModel, A2uiDeleteSurface,
   A2uiMessage, A2uiSurface,
+  A2uiClientDataModel, A2uiActionMessage,
 } from './lib/types';
 export { getByPointer, setByPointer, deleteByPointer } from './lib/pointer';
 export { createA2uiMessageParser } from './lib/parser';

libs/a2ui/src/lib/functions.ts

@@ -57,8 +57,10 @@ const FUNCTIONS: Record<string, FnExecutor> = {
 
   // Navigation
   openUrl: (args) => {
-    if (typeof globalThis.window !== 'undefined') {
-      globalThis.window.open(String(args['url']), '_blank');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const win = globalThis as any;
+    if (typeof win['window'] !== 'undefined') {
+      win['window'].open(String(args['url']), '_blank');
     }
     return null;
   },

libs/a2ui/src/lib/types.ts

@@ -106,6 +106,30 @@ export interface A2uiSurface {
   surfaceId: string;
   catalogId: string;
   theme?: A2uiTheme;
+  sendDataModel?: boolean;
   components: Map<string, A2uiComponent>;
   dataModel: Record<string, unknown>;
 }
+
+// --- v0.9 Outbound Action ---
+
+/** v0.9 client data model envelope — attached when sendDataModel is true. */
+export interface A2uiClientDataModel {
+  version: 'v0.9';
+  surfaces: Record<string, Record<string, unknown>>;
+}
+
+/** v0.9 outbound action message — sent when a component's event action fires. */
+export interface A2uiActionMessage {
+  version: 'v0.9';
+  action: {
+    name: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+  };
+  metadata?: {
+    a2uiClientDataModel: A2uiClientDataModel;
+  };
+}

libs/chat/src/lib/a2ui/surface-store.spec.ts

@@ -96,4 +96,16 @@ describe('createA2uiSurfaceStore', () => {
     store.apply({ type: 'updateComponents', surfaceId: 'nope', components: [] });
     expect(store.surfaces().size).toBe(0);
   });
+
+  it('preserves sendDataModel flag from createSurface', () => {
+    const store = setup();
+    store.apply({ type: 'createSurface', surfaceId: 's1', catalogId: 'basic', sendDataModel: true });
+    expect(store.surfaces().get('s1')!.sendDataModel).toBe(true);
+  });
+
+  it('defaults sendDataModel to undefined when not set', () => {
+    const store = setup();
+    store.apply({ type: 'createSurface', surfaceId: 's1', catalogId: 'basic' });
+    expect(store.surfaces().get('s1')!.sendDataModel).toBeUndefined();
+  });
 });

libs/chat/src/lib/a2ui/surface-store.ts

@@ -22,6 +22,7 @@ export function createA2uiSurfaceStore(): A2uiSurfaceStore {
           surfaceId: message.surfaceId,
           catalogId: message.catalogId,
           theme: message.theme,
+          sendDataModel: message.sendDataModel,
           components: new Map(),
           dataModel: {},
         });