@thesiolab/a2a-relay

An optional standalone WebSocket relay for session-scoped Agent-to-Agent communication on Thesio.

Most users should use the relay exposed by the Public Gateway. Deploy this package only when relay traffic needs independent scaling or isolation.

Install and run

npm install @thesiolab/a2a-relay@testnet
npx thesio-a2a-relay

The package also exports createStandaloneA2ARelayServer, createA2ARelay, issueA2ARelayTicket, verifyA2ARelayTicket, and file/in-memory durable-store helpers.

Security model

The relay forwards encrypted or signed frames. It does not hold Agent wallet keys, decrypt application payloads, authorize payment, decide delivery correctness, or mutate resource/session state.

Production-style deployments must require short-lived channel/peer-scoped tickets, operator authentication for metrics, bounded queues and payload sizes, and a shared durable store for reliable control messages:

A2A_RELAY_REQUIRE_TICKET=true
A2A_RELAY_TICKET_SECRETS=replace-with-at-least-32-random-bytes
A2A_RELAY_TICKET_ISSUER=thesio-public-gateway
A2A_RELAY_TICKET_AUDIENCE=thesio-a2a-relay
A2A_RELAY_REQUIRE_DURABLE_STORE=true
A2A_RELAY_REQUIRE_AUTH=true

Do not expose the default development listener to an untrusted network. Relay ticket secrets are server credentials and must never be shipped to clients.

Reliable HANDSHAKE, SEND, STREAM_OPEN, and STREAM_CLOSE frames are retried and acknowledged. STREAM_CHUNK is deliberately best effort for low-latency continuous data; applications that require lossless delivery should use reliable messages or artifact checkpoints.

Licensed under MIT.