Add an optional transport API for AG-UI interoperability

[haofeif]

Summary

Add a small, optional transport interface so Agentation can communicate with AG-UI agent runtimes without adding AG-UI dependencies to the core browser bundle.

Agentation would continue to own element selection, drawing, layout tools, markers, and its structured DOM/React/source metadata. AG-UI would provide the standardized run, message, shared-state, tool-call, progress, and human-in-the-loop layer between the toolbar and an agent runtime.

Motivation

Agentation already has the domain primitives needed for this integration:

• Structured annotation metadata
• Annotation and submit callbacks
• Optional REST/SSE synchronization
• Webhooks
• MCP tools for acknowledgement, resolution, dismissal, and replies

The current browser/server event protocol is Agentation-specific. An optional AG-UI adapter would allow Agentation to work as a frontend for AG-UI-compatible agents while preserving the existing local, webhook, REST/SSE, and MCP workflows.

AG-UI and MCP are complementary here: AG-UI connects the agent runtime to the user-facing toolbar, while MCP continues to expose annotation, repository, and coding tools to the agent.

Proposed direction

1. Add an optional AgentationTransport interface to the core package.
2. Move the current REST/SSE behavior behind a legacy/default transport implementation.
3. Keep the core agentation package free of new AG-UI runtime dependencies.
4. Implement AG-UI support in a separate optional package or repository, such as agentation-ag-ui.
5. Consolidate the package, MCP, and published JSON annotation schemas into one versioned contract.

Suggested AG-UI mapping:

Agentation behavior	AG-UI mechanism
Submit annotations	RunAgentInput
DOM, React, source, and page metadata	state.agentation
Agent responses	TEXT_MESSAGE_*
Live progress	ACTIVITY_*
Annotation status and thread changes	STATE_SNAPSHOT / STATE_DELTA
Highlight, scroll, inspect, request selection	Client-provided tools
Approval of mutating actions	Interrupt and resume
Transient toolbar effects	Namespaced CUSTOM events

Potential frontend tools include:

• agentation_inspect_element
• agentation_highlight_element
• agentation_scroll_to_element
• agentation_request_selection
• agentation_acknowledge
• agentation_resolve
• agentation_reply
• agentation_propose_change

Read-only interactions could run automatically. Clicking, typing, form submission, or other state-changing browser actions should remain opt-in and approval-gated.

Non-goals

• Replacing Agentation's annotation UI or metadata schema
• Replacing MCP
• Adding AG-UI dependencies to the default browser bundle
• Exposing arbitrary JavaScript execution to agents
• Breaking existing props, callbacks, storage, webhook, or endpoint behavior

Acceptance criteria

• Existing consumers require no code changes.
• The core package gains no required AG-UI runtime dependency or meaningful bundle-size increase.
• A transport can submit the complete structured annotation payload without dropping metadata.
• An optional AG-UI adapter can send RunAgentInput and consume the mandatory run lifecycle events.
• State snapshots and RFC 6902 deltas can update annotation status and threads.
• Safe frontend tools support inspect, highlight, selection, reply, and resolution interactions.
• Errors and interrupted runs are represented explicitly.
• Legacy and AG-UI transports have contract coverage.

Would a PR be welcome?

If this direction fits Agentation's roadmap, would the maintainers welcome a PR? We could start with the transport interface and canonical schema as a backward-compatible first PR, then keep the AG-UI adapter isolated as an optional integration.

[benjitaylor]

An AG-UI adapter can be explored independently of the core transport. We are keeping this request open and outside the current release.