Documentation
¶
Overview ¶
Package agui implements the nexus.io.agui serve plugin: an HTTP listener that exposes the AG-UI ("Agent-User Interaction") endpoint. Clients POST a RunAgentInput and receive a text/event-stream SSE response, one stream per run. The wire format is defined by pkg/agui (not the pkg/ui Envelope used by the browser transport).
Round-trip ¶
Inbound: a POST RunAgentInput maps its messages to a Nexus io.input on the bus (threadId selects/records the session, runId identifies the turn). Outbound: the plugin subscribes to the same bus events as the browser transport and translates them to canonical AG-UI SSE events for the single in-flight run, terminating the stream at RunFinished.
Concurrency model: bus handlers run on arbitrary engine goroutines and never touch the SSE writer. Each handler translates its payload and pushes AG-UI events onto the active run's buffered channel; the HTTP handler goroutine is the sole reader of that channel and the sole writer to the SSE stream. A mutex guards the "active run" pointer. This keeps the SSEWriter race-free.
Non-canonical Nexus bus events (workflow.progress, subagent.*, code.exec.stdout, ...) have no canonical AG-UI equivalent; they consistently ride the AG-UI Custom event (name = bus event type). See docs/src/plugins/io-agui.md.
Index ¶
- Constants
- func New() engine.Plugin
- type Plugin
- func (p *Plugin) Capabilities() []engine.Capability
- func (p *Plugin) ConfigSchema() []byte
- func (p *Plugin) Dependencies() []string
- func (p *Plugin) Emissions() []string
- func (p *Plugin) ID() string
- func (p *Plugin) Init(ctx engine.PluginContext) error
- func (p *Plugin) Name() string
- func (p *Plugin) Ready() error
- func (p *Plugin) Requires() []engine.Requirement
- func (p *Plugin) Shutdown(_ context.Context) error
- func (p *Plugin) Subscriptions() []engine.EventSubscription
- func (p *Plugin) Version() string
- type Server
Constants ¶
const DefaultHeartbeatInterval = 15 * time.Second
DefaultHeartbeatInterval is the gap an idle AG-UI stream is allowed before it writes a keepalive comment.
15s is chosen against the shortest idle timeout a deployment realistically meets — 30s, which is both nginx's proxy_read_timeout default and the GKE Gateway backend default — so two heartbeats fall inside the smallest window rather than one landing on its edge.
⚠ IT DOES NOT HELP AGAINST A TOTAL-DURATION CAP. A GKE GCPBackendPolicy timeoutSec bounds the WHOLE response, not the gap between writes, so a turn longer than it is cut however often this writes. Keepalives answer idle timeouts; a duration cap has to be raised where it is configured.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the AG-UI serve plugin. It stands up an embedded *http.Server that exposes the AG-UI POST endpoint with safe-by-default exposure: loopback bind, optional bearer-token auth, and configurable CORS. It also owns the bus subscriptions that feed the outbound SSE translation.
func (*Plugin) Capabilities ¶
func (p *Plugin) Capabilities() []engine.Capability
func (*Plugin) ConfigSchema ¶
ConfigSchema implements engine.ConfigSchemaProvider.
func (*Plugin) Dependencies ¶
func (*Plugin) Emissions ¶
Emissions declares the event types the inbound handler emits onto the bus. hitl.responded is emitted by the resume path (E2-S2): a continuation RunAgentInput carrying resume[] resolves the pending interrupt(s) that ended a prior run, unblocking the still-parked in-process agent. Both the resolved and the cancelled resume statuses ride hitl.responded (Cancelled:true for the latter) — the shape the control/hitl waiter matches on.
func (*Plugin) Init ¶
func (p *Plugin) Init(ctx engine.PluginContext) error
Init reads config, constructs the server, and wires the outbound bus subscriptions. Nothing binds a socket here; the listener starts in Ready so all plugins have finished Init first.
func (*Plugin) Requires ¶
func (p *Plugin) Requires() []engine.Requirement
func (*Plugin) Subscriptions ¶
func (p *Plugin) Subscriptions() []engine.EventSubscription
Subscriptions declares every bus event the outbound translator consumes. It must stay in lockstep with the Subscribe calls in Init (the contract harness enforces this).
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the embedded AG-UI HTTP server. It owns an *http.Server bound to a loopback address by default, authenticates requests through a nexusauth validator chain, and answers CORS preflight for browser AG-UI clients.
func NewServer ¶
func NewServer(cfg serverConfig) *Server
NewServer builds a Server from cfg. The socket is not bound until Start.