[Porposal] : STDIO Custom Protocol Binding for A2A

## Abstract

This proposal requests the creation of an `experimental-cpb-stdio` repository under the `a2aproject` GitHub organization to host the **STDIO** custom protocol binding for A2A.

STDIO carries the existing A2A method inventory - the same operations, request/response shapes, and server-streaming semantics used by the standard bindings - over the standard input and standard output streams of a locally spawned agent process. Rather than communicating over a network URL and port, the client spawns the agent as a subprocess and exchanges messages over its `STDIN`/`STDOUT` pipes, with `STDERR` reserved for diagnostics. There is no listening socket, no port, and no network endpoint; the operating-system process boundary provides isolation and a local trust boundary that removes the need for application-level authentication headers in the parent-child case. This is a **transport-scoped local control** - it proves who was launched and which private pipe delivered a message - and is deliberately **not** portable agent identity: durable, cross-host proof or receipts remain an optional, separate audit surface, never inferred from stdio delivery success. This is the same local integration model used by the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) and the [Model Context Protocol stdio transport](https://modelcontextprotocol.io/docs/concepts/transports).

The binding defines **two interchangeable serialization variants**, negotiated at startup, so a single transport serves both the JSON- and Protobuf-oriented halves of the A2A ecosystem:

- **`stdio-json`** - [JSON-RPC 2.0](https://www.jsonrpc.org/specification) messages using the same objects, method inventory, and numeric error codes as the A2A JSON-RPC binding (ProtoJSON serialization).
- **`stdio-proto`** - Protocol Buffers v3 binary messages using the same `a2a.proto` service definition, message types, and status codes as the A2A gRPC binding.

Both variants expose the identical A2A method inventory and semantics and differ only in how each message is serialized; the transport, framing, lifecycle, and error semantics are shared.

## Motivation

The core A2A specification defines three standard bindings: HTTP+JSON, HTTP JSON-RPC, and gRPC. All three assume that agents are addressable via URLs and ports, which presupposes a running network server that listens on a socket.

STDIO represents a different model: the agent is a local companion process that the client spawns and owns, communicating over private pipes rather than a network endpoint. This makes it well-suited for scenarios such as:

- Local, on-host integrations - IDE and editor extensions, CLIs, and desktop apps - where the agent should run as a subprocess with no network surface, no port allocation, and no firewall prompts
- Deterministic lifecycle without discovery, where spawning the process is the connection and the OS reaps the agent when the client exits, so a crashed client cannot leave an orphaned server listening
- Sandboxed or constrained runtimes where trust is the OS process/user boundary and the client controls the exact executable, arguments, environment, and privileges granted to the agent

These characteristics cannot be achieved by layering on top of the existing standard bindings, which are defined around a listening network endpoint, and warrant a dedicated custom protocol binding.

## Specification

A draft specification for the STDIO binding is provided [here](https://github.com/hackeramitkumar/A2A/blob/stdio_spec/docs/bindings/stdio.md). It supports the full A2A method inventory, including server-streaming, over LSP-style `Content-Length`-framed messages on the process's stdio streams, with the serialization variant (`stdio-json` or `stdio-proto`) negotiated during the startup handshake. The `stdio-json` variant reuses the JSON-RPC binding's request/response and numeric-coded error objects; the `stdio-proto` variant reuses the gRPC binding's `a2a.proto` message types and `google.rpc` status codes. Transport, process lifecycle, framing, multiplexing, service-parameter transmission, and OS-boundary authentication are shared across both variants. The specification also draws an explicit identity boundary: the OS process boundary is a local, transport-scoped control (launch provenance and pipe origin), not portable agent identity; emitted tasks/results carry a stable local session binding in metadata, and any durable proof/receipt pointer is an optional, separate field that a verifier must never infer from stdio transport success. A short conformance profile makes this boundary testable, and it is intended to compose with external receipt-chain systems (e.g. SATP / AgentFolio-style receipt histories) without A2A choosing a reputation backend.

## Reference Implementations

Reference implementations are planned for:

- **Python:** Planned (client spawn helper and server runtime)
- **TypeScript/JavaScript:** Planned (Node.js host embedding, editor-extension friendly)
- **Rust:** Planned (as part of the `a2a-rs` SDK)

## Request

Per the Extension and Protocol Binding Governance process, this proposal requests:

1. An A2A Maintainer to sponsor this proposal
2. Creation of the `experimental-cpb-stdio` repository under `a2aproject`
3. The initial content of the repository would be the specification draft and links to reference implementations

## References

- [Language Server Protocol - Base Protocol / Header Part](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#headerPart)
- [Model Context Protocol - Transports (stdio)](https://modelcontextprotocol.io/docs/concepts/transports)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
- [Protocol Buffers](https://protobuf.dev/)
- [A2A Protocol Specification v1.0.0](https://a2a-protocol.org/v1.0.0/specification/)
- [A2A JSON-RPC Protocol Binding](https://a2a-protocol.org/v1.0.0/specification/#9-json-rpc-protocol-binding)
- [A2A gRPC Protocol Binding](https://a2a-protocol.org/v1.0.0/specification/#10-grpc-protocol-binding)
- [A2A Custom Protocol Bindings](https://a2a-protocol.org/latest/topics/custom-protocol-bindings/)
- [A2A Extension and Protocol Binding Governance](https://a2a-protocol.org/latest/topics/extension-and-binding-governance/)