Documentation
¶
Overview ¶
Package realtime implements the nexus.io.realtime plugin: a WebSocket transport that streams LLM token deltas, tool previews, voice audio, and cancellation envelopes to connected clients, and accepts text input, audio chunks, cancel, and HITL responses going the other way.
This is Phase 3 of Idea 18 (multimodal & voice IO). Phase 4 will land nexus.io.voice (VAD + ASR + TTS); Phase 5 may eventually fold the envelope shape into io/browser. Until then the realtime transport stands alongside the TUI and browser plugins as a lower-latency option for clients that want raw stream.delta deltas without the browser UI's hub state machine.
Security: there is **no auth in v1**. Origin checks and bearer-token validation are tracked as follow-ups; operators running this on a public network must front it with a reverse proxy that does its own authentication. See docs/src/configuration/reference.md for the nexus.io.realtime entry.
Index ¶
- func New() engine.Plugin
- type Plugin
- func (p *Plugin) Capabilities() []engine.Capability
- 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(ctx context.Context) error
- func (p *Plugin) Subscriptions() []engine.EventSubscription
- func (p *Plugin) Version() string
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the realtime IO plugin. It hosts a WebSocket server and bridges a small set of bus events into JSON envelopes for clients.
func (*Plugin) Capabilities ¶
func (p *Plugin) Capabilities() []engine.Capability
func (*Plugin) Dependencies ¶
func (*Plugin) Init ¶
func (p *Plugin) Init(ctx engine.PluginContext) error
Init reads config and constructs (but does not start) the server.
func (*Plugin) Requires ¶
func (p *Plugin) Requires() []engine.Requirement
func (*Plugin) Subscriptions ¶
func (p *Plugin) Subscriptions() []engine.EventSubscription
Subscriptions declares the events forwarded to clients. We attach a vetoable subscription for before:tool.invoke for read-only observation — the handler never sets Veto. The remainder are post-event observers.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the HTTP/WebSocket front-end for the realtime IO plugin. It owns a connection set, a single mux registered at the configured path, and a handler that the plugin calls into for each inbound envelope.
func NewServer ¶
func NewServer(logger *slog.Logger, addr, path string, maxClients int, onInbound func(env envelope, headers map[string]string)) *Server
NewServer constructs a server but does not listen yet — call Start. Mostly broken out from the plugin so tests can construct a server against an ephemeral port without touching plugin lifecycle. onInbound is called once per inbound frame with the frame and the X-Nexus-* headers of the upgrade the connection was opened with. The headers are passed alongside rather than folded into the envelope on purpose: the envelope is the client-authored wire type, so a field on it would be something a client could set, and these must come from the transport.
func (*Server) Addr ¶
Addr returns the listener's bound address (useful for tests where addr=":0" picks an ephemeral port).
func (*Server) Broadcast ¶
func (s *Server) Broadcast(env envelope)
Broadcast queues an envelope for every connected client. A client whose send buffer is full is logged and dropped on this frame — we do not block on slow consumers.
func (*Server) ClientCount ¶
ClientCount returns the number of currently-connected clients.
func (*Server) Handler ¶
Handler returns the http.Handler the server uses to upgrade incoming WebSocket connections. Exposed so tests can mount it on httptest.Server without going through Start().