AgentX needs a general-purpose way to support hypermedia driven UI behaviors without expanding core complexity or enforcing a single backend model. The objective is to enable a small core with a structured extension surface where optional capabilities such as streaming updates, advanced DOM patching, state bindings, and client side actions can be added as plugins.
Create a stable, documented plugin API and packaging approach so teams can compose hypermedia behaviors in AgentX with a minimal core surface, predictable lifecycle hooks, safe defaults, composability with dependency ordering, and optional bundles for common use cases.
This work does not aim to replace AgentX’s current rendering model in a single step, introduce a full SPA framework, or lock the platform into a single transport. Plain HTML responses should remain the baseline and streaming should be additive.
The system should treat most functionality as optional plugins, with only scanning, request dispatch, eventing, and a minimal swap mechanism in core. Declarative attributes in markup should map to actions resolved through a plugin registry. State handling can be fundamental, but most higher level behaviors should remain outside the core. The backend should be able to return either standard HTML fragments or streamed updates using event based transports.
Proposed architecture:
-
Minimal hypermedia core. The core is responsible for scanning the DOM or scoped subtrees for declarative hooks, dispatching HTTP requests, performing a default swap or patch operation, emitting lifecycle events, and exposing transport adapter interfaces. Fetch is the baseline transport, while streaming transports are provided by plugins.
-
Plugin API. Each plugin exposes metadata including name, version, dependencies, and optional priority. Plugins can declare capabilities such as attributes, actions, watchers, transport adapters, swap strategies, and response transforms. Lifecycle hooks include registration, scan time processing, event handling, request and response interception, and swap participation. Dependency resolution uses topological ordering with priority as a tiebreaker. Plugins interact only through documented public interfaces to avoid internal coupling.
-
Reference plugins. A small set of built in plugins should validate the API design. These include a declarative request plugin that handles triggers, targets, methods, and parameters, a default swap strategy, an optional DOM morph strategy, a multi target update plugin for handling multiple fragments in one response, a streaming transport adapter for server pushed updates, a loading state plugin that manages UI feedback during requests, and a response targeting plugin that routes updates based on status codes.
-
Security defaults. Actions triggered from declarative attributes must follow an allowlist model. HTML parsing should default to safe fragment insertion without script execution. Script evaluation is always opt in. Attribute conflict controls should allow scoped ignore zones to prevent collisions between plugins or with third party code.
-
Packaging and distribution. The system should support bundle presets such as core only, CRUD focused, and realtime focused. Teams should be able to define custom bundles to restrict available plugins. Versioning must include a compatibility matrix between core and plugins, with semantic versioning and a defined deprecation window for API changes.
Developer experience:
Development mode should provide structured logs for requests, swaps, events, and plugin decisions. At minimum there should be an event tap API for debugging, with the option of building visual tooling later. Documentation should include a plugin authoring guide and practical recipes such as optimistic updates, inline validation, pagination, and live streaming updates.
Implementation phases:
- Phase 0: Write an internal RFC defining plugin interfaces, lifecycles, dependency ordering, and core boundaries. Build a proof of concept plugin that introduces one declarative attribute and one action.
- Phase 1: Implement the event bus, request dispatcher, and DOM scanner. Deliver the declarative request plugin and default swap plugin. Add tests validating lifecycle order and dependency handling.
- Phase 2: Introduce a streaming transport plugin and at least one advanced swap strategy. Add a loading state plugin. Mark public interfaces as stable and internal APIs as private.
- Phase 3: Define bundle presets and a simple manifest driven bundling mechanism. Publish plugin development documentation and compatibility policies.
Acceptance criteria:
Third party plugins can be authored without importing internal AgentX modules. Plugins can define attributes and actions that execute deterministically with dependency resolution. Core size remains limited while optional features live entirely in plugins. Demonstrated scenarios include CRUD partial updates, multi target responses, and streaming UI updates. Tests cover lifecycle execution, dependency ordering, and security constraints preventing arbitrary code execution by default.
Open questions:
We need to decide the canonical attribute naming convention, whether responses must remain strictly HTML or can include structured data transformed by plugins, which streaming transports receive first class support, and how DOM scanning should balance performance with correctness when handling incremental updates.
AgentX needs a general-purpose way to support hypermedia driven UI behaviors without expanding core complexity or enforcing a single backend model. The objective is to enable a small core with a structured extension surface where optional capabilities such as streaming updates, advanced DOM patching, state bindings, and client side actions can be added as plugins.
Create a stable, documented plugin API and packaging approach so teams can compose hypermedia behaviors in AgentX with a minimal core surface, predictable lifecycle hooks, safe defaults, composability with dependency ordering, and optional bundles for common use cases.
This work does not aim to replace AgentX’s current rendering model in a single step, introduce a full SPA framework, or lock the platform into a single transport. Plain HTML responses should remain the baseline and streaming should be additive.
The system should treat most functionality as optional plugins, with only scanning, request dispatch, eventing, and a minimal swap mechanism in core. Declarative attributes in markup should map to actions resolved through a plugin registry. State handling can be fundamental, but most higher level behaviors should remain outside the core. The backend should be able to return either standard HTML fragments or streamed updates using event based transports.
Proposed architecture:
Minimal hypermedia core. The core is responsible for scanning the DOM or scoped subtrees for declarative hooks, dispatching HTTP requests, performing a default swap or patch operation, emitting lifecycle events, and exposing transport adapter interfaces. Fetch is the baseline transport, while streaming transports are provided by plugins.
Plugin API. Each plugin exposes metadata including name, version, dependencies, and optional priority. Plugins can declare capabilities such as attributes, actions, watchers, transport adapters, swap strategies, and response transforms. Lifecycle hooks include registration, scan time processing, event handling, request and response interception, and swap participation. Dependency resolution uses topological ordering with priority as a tiebreaker. Plugins interact only through documented public interfaces to avoid internal coupling.
Reference plugins. A small set of built in plugins should validate the API design. These include a declarative request plugin that handles triggers, targets, methods, and parameters, a default swap strategy, an optional DOM morph strategy, a multi target update plugin for handling multiple fragments in one response, a streaming transport adapter for server pushed updates, a loading state plugin that manages UI feedback during requests, and a response targeting plugin that routes updates based on status codes.
Security defaults. Actions triggered from declarative attributes must follow an allowlist model. HTML parsing should default to safe fragment insertion without script execution. Script evaluation is always opt in. Attribute conflict controls should allow scoped ignore zones to prevent collisions between plugins or with third party code.
Packaging and distribution. The system should support bundle presets such as core only, CRUD focused, and realtime focused. Teams should be able to define custom bundles to restrict available plugins. Versioning must include a compatibility matrix between core and plugins, with semantic versioning and a defined deprecation window for API changes.
Developer experience:
Development mode should provide structured logs for requests, swaps, events, and plugin decisions. At minimum there should be an event tap API for debugging, with the option of building visual tooling later. Documentation should include a plugin authoring guide and practical recipes such as optimistic updates, inline validation, pagination, and live streaming updates.
Implementation phases:
Acceptance criteria:
Third party plugins can be authored without importing internal AgentX modules. Plugins can define attributes and actions that execute deterministically with dependency resolution. Core size remains limited while optional features live entirely in plugins. Demonstrated scenarios include CRUD partial updates, multi target responses, and streaming UI updates. Tests cover lifecycle execution, dependency ordering, and security constraints preventing arbitrary code execution by default.
Open questions:
We need to decide the canonical attribute naming convention, whether responses must remain strictly HTML or can include structured data transformed by plugins, which streaming transports receive first class support, and how DOM scanning should balance performance with correctness when handling incremental updates.