task: add WebSocket transport binding

[muscariello]

Type: Task

Summary

Add a WebSocket transport binding so the workspace supports a bidirectional A2A transport alongside the current JSON-RPC over HTTP, REST / HTTP+JSON, gRPC, and SSE streaming support.

Why

The current bindings cover request/response transports plus server-driven streaming. WebSocket support would add a long-lived bidirectional option while still reusing the existing client transport registry, RequestHandler-based server boundary, and shared error and metadata conventions.

Scope / plan

• Add a WebSocket protocol identifier and agent-card negotiation path
• Implement a client transport and register it in the client transport/factory layer
• Implement server wrapper(s) that translate framed WebSocket messages into RequestHandler operations
• Define framing rules, request correlation, and streaming event shapes over a bidirectional connection
• Define ServiceParams propagation during connection setup and per-message metadata handling
• Define A2AError mapping for protocol violations, close conditions, and operation failures
• Extend the helloworld transport end-to-end coverage and supporting docs as needed

Acceptance criteria

• Agent cards can advertise WebSocket and the client factory can negotiate it without regressing existing binding selection
• Unary and streaming operations work over a single documented bidirectional connection
• Framing, request correlation, metadata propagation, and A2AError mapping are covered by tests
• End-to-end coverage includes happy-path flows and at least one close or protocol-error path

Parent feature: #12

[Rushit]

Hey - I would like to take up this task, here are proposed changes based on my context. If this seem correct direction, I can polish it and get it ready for merge. Please provide feedback here.

WebSocket Transport Binding - Proposed Changes

Overview

Add WebSocket transport binding for bidirectional A2A communication alongside existing HTTP/REST/gRPC/SSE bindings.

Refs: #14 | Parent Feature: #12

---

Architecture Overview

┌─────────────────┐
│   Agent Card    │
│  [WEBSOCKET]    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Client Factory  │
│  (Negotiates)   │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│  WS    │ │ Other  │
│ Client │ │Trans.  │
└───┬────┘ └────────┘
    │
    ▼
┌─────────────────┐
│  WS Server      │
│  Router/Handler │
└─────────────────┘

---

Change Summary

Layer	Components	Status
Core	Protocol ID, Framing envelopes	New module
Client	WebSocket transport, Factory registration	New module
Server	WebSocket router, Message handler	New module
Examples	Server mount, E2E tests	Modify
Docs	README documentation	Modify

---

Acceptance Criteria

Criterion	Test Location
WebSocket negotiation	factory.rs
Unary + streaming operations	transports_e2e.rs
Framing/correlation	transports_e2e.rs
Metadata propagation	transports_e2e.rs
Error mapping	transports_e2e.rs

---

File Changes

Status	Path
new	a2a/src/websocket.rs
new	a2a-client/src/websocket.rs
new	a2a-server/src/websocket.rs
edit	a2a/src/lib.rs, a2a/src/types.rs
edit	a2a-client/src/lib.rs, a2a-client/src/factory.rs
edit	a2a-server/src/lib.rs
edit	examples/src/helloworld/server.rs
edit	examples/tests/transports_e2e.rs
edit	examples/Cargo.toml, Cargo.lock
edit	README.md

---

Detailed Changes

1. Protocol Identifier & Negotiation

File	Changes
a2a/src/types.rs	Add TRANSPORT_PROTOCOL_WEBSOCKET = "WEBSOCKET"
a2a/src/lib.rs	Export websocket module
examples/src/helloworld/server.rs	Add AgentInterface::new("ws://localhost:3000/ws", TRANSPORT_PROTOCOL_WEBSOCKET)
a2a-client/src/factory.rs	Register WebSocketTransportFactory; add negotiation tests

Tests to add:

• test_create_from_card_selects_websocket_when_only_match
• test_create_from_card_honors_websocket_preference

Default preference order: JSON-RPC → HTTP+JSON → WebSocket

2. Client Transport

Component	Details
WebSocketTransport	Implements Transport trait; UUID v7 correlation; pending call management
WebSocketTransportFactory	Validates ws:///wss:// URLs; returns transport instances
Error handling	Maps connection/serialization errors to A2AError variants

Key features:

• Support all unary and streaming A2A operations
• UUID v7 string IDs for request correlation
• Arc<Mutex<HashMap>> for pending unary and streaming calls
• fail_all_pending() for connection close and protocol errors

3. Server Handler

Function	Purpose
websocket_router()	Mount WebSocket upgrade handler
handle_websocket()	Extract ServiceParams from headers
serve_socket()	Manage bidirectional communication
handle_text_frame()	Parse envelopes; merge params; dispatch requests
spawn_streaming_call()	Handle streaming methods with event frames
handle_unary_request()	Handle unary methods (send_message, get_task, etc.)

Unary methods: send_message, get_task, list_tasks, cancel_task, push config operations, get_extended_agent_card

Streaming methods: send_streaming_message, subscribe_to_task

Frame handling:

• Reject binary frames with UNSUPPORTED close code
• Route text frames through handle_text_frame()
• Send stream_event frames for each stream item
• Send stream_error on failure
• Send stream_end on completion

4. Framing Protocol

Direction	Envelope	Key Fields
Client → Server	WebSocketRequestEnvelope	jsonrpc, id, method, params, service_params
Server → Client	WebSocketResponseEnvelope	jsonrpc, id, result/error/stream_event/stream_error/stream_end

Helper constructors: success(), error(), stream_event(), stream_error(), stream_end()

Streaming pattern: stream_event → stream_event → ... → stream_end or stream_error

5. ServiceParams Propagation

Location	Mechanism
Connection setup	Extracted from HTTP headers via service_params_from_headers()
Per-message	Optional service_params field in request envelope
Merge logic	Connection params merged with per-message params in handle_text_frame()

Test: websocket_transport_propagates_message_service_params - verifies per-message ServiceParams override request params

6. Error Mapping

Error Type	Client Mapping	Server Mapping
Invalid URL	A2AError::invalid_request()	N/A
Connection failure	A2AError::internal()	N/A
Frame serialization	A2AError::internal()	N/A
Channel closure	A2AError::unsupported_operation()	N/A
Invalid JSON	A2AError::internal()	PARSE_ERROR (-32700)
Invalid jsonrpc version	N/A	invalid_request
Binary frames	N/A	UNSUPPORTED close code
Parse errors	A2AError::parse_error()	parse_error() helper

Test: websocket_transport_reports_malformed_frame - verifies server responds with PARSE_ERROR JSON-RPC error

7. Tests & Documentation

Test	Coverage
websocket_transport_end_to_end	Unary + streaming + error paths
websocket_transport_propagates_message_service_params	Metadata propagation
websocket_transport_reports_malformed_frame	Protocol error handling

Dependencies to add:

• tokio-tungstenite in examples/Cargo.toml for ws protocol implementation

Documentation updates:

• Add WebSocket to supported bindings list
• Document agent card advertisement with WEBSOCKET protocol binding
• Document default factory registration and preference order
• Document frame correlation via string id
• Document response frame types: result, error, stream_event, stream_error, streamEnd
• Document streaming behavior: zero or more streamEvent followed by streamEnd or streamError
• Document Service params propagation: connection headers + per-message merge
• Update client usage description to include WebSocket

[hackeramitkumar]

Hi @Rushit,
I am currently working on this issue. I have already written the proposal and spec for WebSocket CPB; once it is reviewed and approved, I will raise a PR with the implementation.
Could you please pick up another task?