task: add stdio transport binding

[muscariello]

Type: Task

Summary

Add a stdio transport binding for subprocess-hosted agents using stdin/stdout, alongside the current JSON-RPC over HTTP, REST / HTTP+JSON, gRPC, and SSE streaming support.

Why

The existing bindings are network-oriented. A stdio transport would make local subprocess execution a first-class option for tool-style integrations, local development, and process-scoped agent hosting while still reusing the core transport abstraction and shared protocol types.

Scope / plan

• Add a stdio protocol identifier and interface contract for subprocess-backed agents
• Implement a client transport that spawns and manages a subprocess over stdin/stdout
• Define request framing, startup handshake, streaming behavior, shutdown, and cancellation semantics
• Define how ServiceParams are carried without HTTP or gRPC metadata
• Define A2AError mapping for process exits, broken pipes, invalid frames, and timeouts
• Add integration tests and supporting docs for the stdio contract and lifecycle behavior

Acceptance criteria

• A client can launch a subprocess-backed agent and complete unary and streaming operations over stdio
• Lifecycle handling is deterministic for startup failure, clean exit, cancellation, and broken-pipe cases
• ServiceParams propagation and A2AError mapping are specified and covered by tests
• Docs describe the stdio contract clearly enough for another implementation to interoperate

Parent feature: #12

[Ketankhunti]

Hi, I'd like to work on this task. I've analyzed the codebase and existing transport implementations (JSON-RPC, REST, gRPC, SLIMRPC) to understand the patterns. Before starting, I have some design questions:

1. Wire Protocol

The existing JSON-RPC transport already has request/response types, method routing, and streaming semantics. Should the stdio transport reuse JSON-RPC 2.0 as its protocol over stdin/stdout, or should it use a different approach (raw ProtoJSON, binary protobuf)?

2. Request Framing

How should messages be delimited on stdin/stdout? Two common options:

• Content-Length headers (LSP style): Content-Length: N\r\n\r\n{json} — more robust, allows additional headers
• Newline-delimited JSON (NDJSON): one JSON object per \n — simpler but no natural place for out-of-band metadata

Is there a preference, or is there an existing convention in the broader A2A ecosystem?

3. ServiceParams Propagation

HTTP transports carry ServiceParams as headers, gRPC uses metadata. For stdio:

• Should ServiceParams go in frame headers (if using Content-Length framing)?
• Or in an extension field on the JSON-RPC envelope (e.g. "metadata": {...})?
• Or passed as environment variables to the subprocess at spawn time?

4. Agent Card / Discovery

Stdio agents are local subprocesses, not network services. Should a stdio agent be representable in an AgentCard? If so:

• What should the url field contain? (e.g. stdio:///path/to/binary, stdio:my-agent)
• How are command-line arguments specified?
• Or is stdio primarily used via direct StdioTransport::spawn() without agent card discovery?

5. Startup Handshake

Should the subprocess emit a "ready" message before the client sends requests? For example:

• A specific JSON-RPC notification on stdout indicating the agent is initialized
• Or should the client just start writing to stdin immediately after spawn?

6. Streaming Behavior

For streaming methods (SendStreamingMessage, SubscribeToTask):

• Multiple JSON-RPC responses with the same id, one per frame — is this the expected approach?
• How does the client know the stream is complete? Terminal task state, a special end-of-stream message, or EOF on stdout?

7. Shutdown & Cancellation

• Clean shutdown: Close stdin → subprocess detects EOF → exits cleanly? Or send a specific shutdown message first?
• Cancel in-flight request: Send a JSON-RPC CancelTask request on stdin? Or kill the process?
• Timeout: Should there be a configurable timeout for subprocess startup and per-request response?

8. Crate Structure

Should this be a new a2a-stdio crate in the workspace (like a2a-grpc, a2a-slimrpc), or should it live inside a2a-client/a2a-server?

9. Server Side

The issue mentions "subprocess-hosted agents." Should there also be a stdio server helper (reads stdin, dispatches to RequestHandler, writes to stdout) — similar to how a2a-grpc has both GrpcTransport (client) and GrpcHandler (server)? Or is the server side out of scope for the initial PR?

Happy to start with whichever subset makes sense for an initial PR.

[muscariello]

Background https://gist.github.com/muscariello/23ac09c71874cbfe7b7ffe8561337474

And also https://a2a-protocol.org/latest/topics/extension-and-binding-governance/ recently defined by the A2A community and approved by the A2A TSC.