# AG-UI gateway compatibility boundary

Observed 2026-10-24 UTC. `dsh-a2ui` and `dsh-ag-ui` both use the name `render_a2ui`, but their default tool, event and action contracts are different. Do not connect them by name alone. No AG-UI adapter is provided or certified by this comparison.

## Inspected versions

- `dsh-a2ui` alpha.13: [c3318227971decc51f743c1429bbc8a965b5b809](https://github.com/sunxiuguo/dsh-a2ui/tree/c3318227971decc51f743c1429bbc8a965b5b809), official renderer 0.14.0 and unmodified A2UI schemas from `020a9d6f694761ad16b35bc38945e4ccd0ac14e8`, specification `v0_9_1`.
- `dsh-ag-ui` current main at inspection: [86d7c5fc7bc524c01bacfa560e311d0868de58f8](https://github.com/CaiZongyuan/dsh-ag-ui/tree/86d7c5fc7bc524c01bacfa560e311d0868de58f8). Its tests pin `@ag-ui/a2ui-middleware` 0.0.10. The inspected middleware release source is [b9910b93be5464835ab77eba9c2a4fa3b341e7ca](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/package.json).

Both projects use MIT licenses. The official A2UI schemas/runtime have separate Apache-2.0 notices retained by this project. Source availability does not establish combined-host compatibility.

## What can cross the boundary

1. **Document data:** this plugin accepts `{messages: [...]}`, with complete, versioned `createSurface`, `updateComponents`, `updateDataModel` and `deleteSurface` operations. Both `v0.9` and `v0.9.1` are accepted without rewriting. The middleware's injected tool instead accepts `{surfaceId, components, data?}`. Its streamed output does contain genuine `v0.9` operations inside `ACTIVITY_SNAPSHOT.content.a2ui_operations`. Compatible extracted operations can pass our validator, but neither the compact tool input nor the activity envelope is a document input. See [our tool](https://github.com/sunxiuguo/dsh-a2ui/blob/c3318227971decc51f743c1429bbc8a965b5b809/src/dsh/tool.ts#L9-L21), [middleware tool](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/src/tools.ts#L13-L45) and [operation emission](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/src/index.ts#L678-L737).

2. **Catalog and snapshot semantics:** alpha.13 requires `https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json`. Middleware 0.0.10 can be explicitly configured with that catalog, but its final fallback is the different `.../v0_9/basic_catalog.json` URI. Its cumulative snapshots carry `replace: true` and repeat `createSurface`; blindly appending them fails our duplicate-surface check. A future adapter must handle identity, replacement and validation explicitly, without silently rewriting catalogs or weakening media/navigation policy. See [catalog selection](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/src/index.ts#L569-L594) and [our validation](https://github.com/sunxiuguo/dsh-a2ui/blob/c3318227971decc51f743c1429bbc8a965b5b809/src/protocol.ts#L46-L59).

3. **Events and results:** our client consumes native DSH events and settles only validated `dsh-a2ui/1` presentation metadata. A `{status:"rendered"}` receipt alone withdraws its preview; it does not prove display. Gateway projection preserves native result metadata, so carrying our recording over AG-UI is plausible, but this plugin has no consumer for that wire event. Our tool's text receipt also is not the middleware's autodetected `{a2ui_operations:[...]}` result wrapper. See [native node](https://github.com/sunxiuguo/dsh-a2ui/blob/c3318227971decc51f743c1429bbc8a965b5b809/src/dsh/node.ts#L10-L30), [gateway result projection](https://github.com/CaiZongyuan/dsh-ag-ui/blob/86d7c5fc7bc524c01bacfa560e311d0868de58f8/src/projection.ts#L265-L279) and [middleware result detection](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/src/index.ts#L759-L821).

4. **Tool ownership:** if our backend `render_a2ui` is inherited by the same gateway agent, requesting the middleware's frontend tool under that name hits the gateway's `FRONTEND_TOOL_NAME_COLLISION` guard. This is a conditional source finding, not a demonstrated package-installation conflict. Merely renaming the middleware tool does not convert its input, result or event contract. See [collision guard](https://github.com/CaiZongyuan/dsh-ag-ui/blob/86d7c5fc7bc524c01bacfa560e311d0868de58f8/src/thread.ts#L1162-L1180).

5. **Actions and identity:** our `{version,action}` envelope travels as an ordinary persisted, explicitly untrusted user message. The gateway's middleware path requires `forwardedProps.a2uiAction.userAction` plus a matching final synthetic `log_a2ui_event` assistant/tool pair. Forwarded properties alone are rejected. Gateway deduplication uses the preserved synthetic result ID and rejects changed content under that identity. Middleware 0.0.10 generates fresh pair IDs on each invocation, so rebuilding a pair is not the same retry. Native interrupt approval/resume is a separate protocol; an A2UI button is not approval authority. See [our send path](https://github.com/sunxiuguo/dsh-a2ui/blob/c3318227971decc51f743c1429bbc8a965b5b809/src/dsh/client.tsx#L24-L31), [pair validation](https://github.com/CaiZongyuan/dsh-ag-ui/blob/86d7c5fc7bc524c01bacfa560e311d0868de58f8/src/thread.ts#L1425-L1500), [durable identity](https://github.com/CaiZongyuan/dsh-ag-ui/blob/86d7c5fc7bc524c01bacfa560e311d0868de58f8/src/thread.ts#L975-L1005), [pair generation](https://github.com/ag-ui-protocol/ag-ui/blob/b9910b93be5464835ab77eba9c2a4fa3b341e7ca/middlewares/a2ui-middleware/src/index.ts#L252-L301) and [interrupt validation](https://github.com/CaiZongyuan/dsh-ag-ui/blob/86d7c5fc7bc524c01bacfa560e311d0868de58f8/src/interrupts.ts#L59-L99).

## Choose an existing path

- For this plugin's documented native DSH workflow, keep its server tool, native client, exact catalog and validated recordings together.
- For an AG-UI application, use the gateway's documented middleware/client contract and an appropriate AG-UI renderer. Do not substitute this native client by tool name.
- Treat a combined bridge as separate integration work requiring explicit event, snapshot, catalog, settlement and action-identity tests. Do not enable routes, rename tools, replay actions or expand permissions automatically. Gateway authentication and application authorization remain separate responsibilities.

## Verification boundary

The synthetic [contract fixture](../test/gateway-contract-boundary.test.tsx) passed 11/11 assertions on Node 24.19.0, Vitest 3.2.4 and jsdom 26.1.0. The copied source/schema/license inputs were byte-checked against alpha.13. It exercised standard-document acceptance, compact-input and envelope rejection, cumulative-snapshot/catalog rejection, native event matching, receipt-only withdrawal, validated settlement, retained media/navigation policy, and an actual renderer click followed by restore with zero action sends.

This ran existing reviewed dependencies without installation, a gateway process, host credentials or a full DSH host. Gateway/middleware findings are source observations and existing test definitions, not newly executed gateway tests. The fixture does not certify a working adapter, retry safety across both systems, combined installation, browser layout, production readiness, adoption or customer demand. Keep the inspected versions and separate working paths explicit until a bounded integration is deliberately tested.