a2a

package
v0.32.3 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package a2a implements the nexus.io.a2a serve plugin: an HTTP listener that exposes this Nexus instance as an Agent2Agent (A2A) agent.

It mounts three surfaces on one listener:

  • GET /.well-known/agent-card.json — the discovery document (specification section 8.2), served from hand-authored config with its interfaces, capabilities and security requirements derived from the live listener.
  • POST <jsonrpc_path> — the JSON-RPC 2.0 binding (section 9).
  • <rest_prefix>/… — the HTTP+JSON/REST binding (section 11).

The wire format is entirely pkg/a2a's; this package contributes the listener, the credential guard, the card assembly and the routing. It is the A2A sibling of nexus.io.agui and is, like it, an external interop transport with its own wire, not a Nexus UI (see .claude/docs/io-transport.md).

Round-trip

Inbound: a SendMessage or SendStreamingMessage becomes a Nexus io.input. The message's text parts are the turn's prompt and its contextId selects the session (see resolveContextLocked). Each call creates exactly one Task, which is one Nexus agent turn: created SUBMITTED, moved to WORKING when the agent turn starts, and ended COMPLETED at agent.turn.end — or FAILED when the turn dies with an error nobody will retry.

Outbound: the plugin subscribes to the bus events that describe a turn and translates them into A2A stream frames. SendStreamingMessage writes them as text/event-stream records; the blocking SendMessage folds the same frames into the Task it returns, so both bindings answer from one translation rather than two that can drift.

What a turn publishes

Artifacts carry OUTPUT (specification section 3.7):

  • The final assistant text, plus an application/json Part when that text is a JSON document, so structured output is a document rather than a string.
  • Every tool result, UNCONDITIONALLY. It is not behind a flag: an interop transport whose observability depends on the operator having enabled it is one a partner cannot rely on.
  • Every file the turn wrote, with contents inline as a base64 raw Part.

The Nexus extension carries what A2A has no canonical field for — thinking steps, tool calls, subagent progress and token usage — as TaskStatusUpdateEvent.metadata keyed by a2a.NexusExtensionURI. It is declared in the Agent Card and delivered ONLY to clients that opted in with the A2A-Extensions service parameter, so a client that did not ask gets an unpolluted canonical stream.

Volume is bounded, and the bound is load-bearing rather than tuning: unconditional tool-result artifacts, times inline base64 file parts, times a disk-persisted store is an unbounded product. artifacts.max_file_bytes and artifacts.max_tool_output_bytes bound one artifact, artifacts.max_task_bytes bounds one task, and tasks.max_per_context bounds the store. Every cap DEGRADES rather than drops: an over-cap file becomes a metadata note naming it, and a task that spends its budget publishes a notice saying how much it withheld. See artifacts.go.

File detection is tool.result-based and therefore incomplete BY DESIGN: a file is published only when a tool reports having written it (ToolResult.OutputFile, or a structured key named by artifacts.file_sources). Snapshot-diffing the workspace is out of scope, so an uninstrumented write is missed.

Durability

Tasks are not a transient side effect of the request that created them. Each one is written to a session-scoped SQLite store (taskstore.go) BEFORE its turn is allowed to start, and every status transition and artifact is written through as the frame reporting it is queued for the wire. The record is filed under the authenticated Principal, and the store's only read surface is scoped to one principal, so a task can never be reached by a caller that did not create it. Retention (tasks.ttl, tasks.max_per_context) bounds the store.

Reading tasks back

GetTask, ListTasks and SubscribeToTask answer from that store (tasks.go). Every one of them goes through the store's principal-scoped view, so a task belonging to another caller is reported exactly as an unknown task id is — the same TaskNotFoundError, from the same single lookup, with no second query whose presence or absence could leak the difference. SubscribeToTask attaches to the live run when there is one and replays the current state first, so a client that joins mid-turn is never told about an update to a task it has not been shown.

Interruption and cancellation

A task leaves the ordinary WORKING path two ways, and both are bus-driven.

A hitl.requested — a Nexus agent asking a human something — parks the task at TASK_STATE_INPUT_REQUIRED with the question on the status message. The task stays LIVE: attached streams stay open (specification section 11.7's close rule keys off terminal states, which this is not), the transition is written through to the store, and a client that reconnects meanwhile reads the question from GetTask or from SubscribeToTask's opening snapshot. The client answers with a new message naming the same taskId and contextId, which is A2A's own resume mechanism (section 3.4): the answer is routed to hitl.responded and the task returns to WORKING inside the SAME turn — no io.input, no second task. Because a human takes human time, the wait has a deadline (tasks.input_timeout); on expiry the task is failed and hitl.cancel retracts the question so the agent loop stops waiting.

A CancelTask settles the task at TASK_STATE_CANCELED, then tells the bus: hitl.cancel if it was parked, then cancel.request, which is the control.cancel capability's entry point — the same event the TUI emits. An already-terminal task is refused with TaskNotCancelableError and nothing is written.

Task lifetime is the task's, not the request's

A run is registered as this listener's single active task and released when the TASK reaches a terminal state, not when the HTTP request that started it returns. So a client may disconnect mid-turn and reattach with SubscribeToTask, a question may be parked for as long as answering it takes, and configuration.returnImmediately is answerable rather than refused. The cost is the reason CancelTask landed alongside: a turn nobody is watching would otherwise hold the process's one agent loop with nothing able to interrupt it.

Concurrency

The model is nexus.io.agui's, extended in one direction: from one observer per run to many. Bus handlers run on arbitrary engine goroutines and NEVER touch a response writer. Each handler translates its payload and hands the frames to the active run, which — under one lock — folds them into the task snapshot and copies them into every attached stream's buffered channel. Each of those channels is drained by exactly ONE HTTP handler goroutine, which is the sole writer of that goroutine's response. A stream too far behind to be given a coherent sequence is dropped rather than allowed to stall the agent loop.

A mutex guards the active-run pointer and the bound context. Everything else the handlers read (the resolved config, the rendered card, the validator chain) is immutable after Init.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func New

func New() engine.Plugin

New creates a new A2A serve plugin.

Types

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin is the A2A serve plugin.

func (*Plugin) Capabilities

func (p *Plugin) Capabilities() []engine.Capability

func (*Plugin) Card

func (p *Plugin) Card() a2a.AgentCard

Card returns the rendered Agent Card. It exists for tests and for embedders that need to publish the same document out-of-band (specification section 8.2 lists direct configuration as a discovery mechanism).

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 bus events the inbound mapping publishes:

  • before:io.input / io.input — one turn's worth of user input, gated first so the same guardrails that see a TUI keypress see an A2A message.
  • hitl.responded — a message continuing an interrupted task, routed to the question that task is parked on. It is NOT an io.input: a resumed task continues the turn that asked, and emitting input would start a second.
  • hitl.cancel — the parked question is retracted when the task is canceled or its input deadline elapses, so the agent loop blocked in ask_user unblocks instead of waiting for an answer that is never coming.
  • cancel.request — CancelTask's route to the control.cancel capability. The same event the TUI and the browser transport emit; cancellation is that plugin's job, not this one's.

func (*Plugin) ID

func (p *Plugin) ID() string

func (*Plugin) Init

func (p *Plugin) Init(ctx engine.PluginContext) error

Init resolves configuration, renders the Agent Card and constructs the server. Nothing binds a socket here; the listener starts in Ready so every plugin has 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 unsubscribes, fails any in-flight task so its HTTP handler returns promptly, and gracefully stops the HTTP server.

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 that, and each entry below earns its place by driving a frame:

  • agent.turn.start -> the WORKING status update
  • llm.request -> the output schema the turn was constrained to
  • llm.response -> the terminal assistant text (tool-call-free responses), and per-call token usage as extension telemetry
  • io.output -> the same text after the output gates had their say
  • agent.turn.end -> the artifacts plus the COMPLETED status
  • core.error -> a FAILED status when nothing will retry
  • hitl.requested -> the INPUT_REQUIRED status carrying the question
  • hitl.responded -> back to WORKING once the question is answered
  • tool.invoke -> a tool call, as extension telemetry
  • tool.result -> an ARTIFACT per result, plus an artifact per file the result reports having written, plus the same as telemetry
  • thinking.step -> a reasoning step, as extension telemetry
  • subagent.started / .iteration / .complete -> delegated-work progress, as extension telemetry

The two hitl.* entries are how a Nexus agent asking a human becomes A2A's own interruption mechanism. They are SUBSCRIPTIONS, not calls: nexus.control.hitl owns ask_user and the pending-request registry, and this plugin renders what it sees on the bus rather than reaching into it. The same is true of every entry below it: this transport watches the bus and renders what it sees.

func (*Plugin) Version

func (p *Plugin) Version() string

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the embedded A2A HTTP server. It owns an *http.Server bound to a loopback address by default, authenticates requests through a nexusauth validator chain, and mounts the discovery document alongside both HTTP bindings.

func NewServer

func NewServer(cfg serverConfig) *Server

NewServer builds a Server from cfg. The socket is not bound until Start.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler builds the request multiplexer. It is exported through Start, and split out so tests can exercise routing without binding a socket.

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