agui

package
v0.32.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
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

func New

func New() engine.Plugin

New creates a new AG-UI serve plugin.

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

func (p *Plugin) ConfigSchema() []byte

ConfigSchema implements engine.ConfigSchemaProvider.

func (*Plugin) Dependencies

func (p *Plugin) Dependencies() []string

func (*Plugin) Emissions

func (p *Plugin) Emissions() []string

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) ID

func (p *Plugin) ID() string

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) Name

func (p *Plugin) Name() string

func (*Plugin) Ready

func (p *Plugin) Ready() error

Ready starts the HTTP listener.

func (*Plugin) Requires

func (p *Plugin) Requires() []engine.Requirement

func (*Plugin) Shutdown

func (p *Plugin) Shutdown(_ context.Context) error

Shutdown gracefully stops the HTTP server and unsubscribes from the bus.

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).

func (*Plugin) Version

func (p *Plugin) Version() string

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.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully stops the HTTP server.

func (*Server) Start

func (s *Server) Start() error

Start binds the listener and serves in a background goroutine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL