UAT: A2A-Version HTTP header not sent or validated in server mode — spec requires this header on every request #3638

Open
opened 2026-04-05 21:02:29 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: bugfix/backlog-a2a-version-header-validation
  • Commit Message: fix(a2a): send and validate A2A-Version HTTP header on every request
  • Milestone: (none — backlog)
  • Parent Epic: #366

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background and Context

Per docs/specification.md (lines 23577–23579 and 43376–43417), the A2A protocol requires that:

  • The A2A protocol version is declared in the Agent Card and sent via the A2A-Version HTTP header on every request.
  • The CleverAgents extension version is declared in the Agent Card's extensions section under _cleveragents.version.
  • All subsequent operations after initial handshake must include the A2A-Version header.

The A2aVersionNegotiator class in src/cleveragents/a2a/versioning.py implements version negotiation logic, but it is not wired into the HTTP layer. Neither the ASGI server app nor the HTTP transport client currently reads, sends, or validates this header.

Current Behavior

  1. The ASGI app (src/cleveragents/a2a/asgi.py) does not read or validate any A2A-Version header on incoming requests.
  2. The A2aHttpTransport (src/cleveragents/a2a/transport.py) is a stub that raises A2aNotAvailableError on all operations and never sends any headers.
  3. The A2aVersionNegotiator (src/cleveragents/a2a/versioning.py) exists but is not connected to the HTTP request/response pipeline.
  4. Requests with unsupported or missing versions are not rejected with a -32007 (Version mismatch) JSON-RPC error.

Expected Behavior

Per the spec:

  1. The server ASGI app must read the A2A-Version header from every incoming HTTP request.
  2. If the version is unsupported or absent, the server must return a JSON-RPC 2.0 error response with code -32007 (Version mismatch).
  3. The HTTP transport client must send A2A-Version: 1.0 on every outgoing request.
  4. The A2aVersionNegotiator must be wired into the ASGI request-handling pipeline so version checks are enforced at the transport boundary.

Acceptance Criteria

  • The ASGI app reads the A2A-Version header from every incoming request.
  • Requests with an unsupported or missing A2A-Version header receive a JSON-RPC 2.0 error with code -32007.
  • The HTTP transport client sends A2A-Version: 1.0 (or the negotiated version) on every outgoing request.
  • A2aVersionNegotiator is integrated into the ASGI middleware/handler pipeline.
  • Unit tests cover: valid version accepted, unsupported version rejected with -32007, missing header rejected.
  • All nox stages pass and coverage ≥ 97%.

Supporting Information

Code Locations:

  • src/cleveragents/a2a/versioning.pyA2aVersionNegotiator exists but is not wired to the HTTP layer
  • src/cleveragents/a2a/asgi.py — ASGI app does not read A2A-Version header
  • src/cleveragents/a2a/transport.py — stub transport never sends headers

Spec References:

  • docs/specification.md lines 23577–23579: version header declaration requirement
  • docs/specification.md lines 43376–43417: header sent on every request requirement
  • JSON-RPC error code -32007: Version mismatch

Impact: Without A2A-Version header validation, the server cannot enforce protocol version compatibility. External A2A clients that send the required header will not have their version validated. Non-critical since server mode is not yet implemented.

Subtasks

  • Add ASGI middleware (or handler logic) in src/cleveragents/a2a/asgi.py to read the A2A-Version header from incoming requests
  • Wire A2aVersionNegotiator.is_supported() into the ASGI pipeline to validate the extracted version
  • Return a JSON-RPC 2.0 error with code -32007 when the version is unsupported or missing
  • Implement header injection in A2aHttpTransport to send A2A-Version: <version> on every outgoing request
  • Tests (pytest/Behave): Add unit tests for ASGI version header validation (valid, unsupported, missing)
  • Tests (pytest/Behave): Add unit tests for transport header injection
  • Verify coverage ≥ 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(a2a): send and validate A2A-Version HTTP header on every request), followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (bugfix/backlog-a2a-version-header-validation).
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `bugfix/backlog-a2a-version-header-validation` - **Commit Message**: `fix(a2a): send and validate A2A-Version HTTP header on every request` - **Milestone**: *(none — backlog)* - **Parent Epic**: #366 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context Per `docs/specification.md` (lines 23577–23579 and 43376–43417), the A2A protocol requires that: - The A2A protocol version is declared in the Agent Card and sent via the `A2A-Version` HTTP header on **every** request. - The CleverAgents extension version is declared in the Agent Card's extensions section under `_cleveragents.version`. - All subsequent operations after initial handshake must include the `A2A-Version` header. The `A2aVersionNegotiator` class in `src/cleveragents/a2a/versioning.py` implements version negotiation logic, but it is not wired into the HTTP layer. Neither the ASGI server app nor the HTTP transport client currently reads, sends, or validates this header. ## Current Behavior 1. The ASGI app (`src/cleveragents/a2a/asgi.py`) does not read or validate any `A2A-Version` header on incoming requests. 2. The `A2aHttpTransport` (`src/cleveragents/a2a/transport.py`) is a stub that raises `A2aNotAvailableError` on all operations and never sends any headers. 3. The `A2aVersionNegotiator` (`src/cleveragents/a2a/versioning.py`) exists but is not connected to the HTTP request/response pipeline. 4. Requests with unsupported or missing versions are not rejected with a `-32007` (Version mismatch) JSON-RPC error. ## Expected Behavior Per the spec: 1. The server ASGI app must read the `A2A-Version` header from every incoming HTTP request. 2. If the version is unsupported or absent, the server must return a JSON-RPC 2.0 error response with code `-32007` (Version mismatch). 3. The HTTP transport client must send `A2A-Version: 1.0` on every outgoing request. 4. The `A2aVersionNegotiator` must be wired into the ASGI request-handling pipeline so version checks are enforced at the transport boundary. ## Acceptance Criteria - [ ] The ASGI app reads the `A2A-Version` header from every incoming request. - [ ] Requests with an unsupported or missing `A2A-Version` header receive a JSON-RPC 2.0 error with code `-32007`. - [ ] The HTTP transport client sends `A2A-Version: 1.0` (or the negotiated version) on every outgoing request. - [ ] `A2aVersionNegotiator` is integrated into the ASGI middleware/handler pipeline. - [ ] Unit tests cover: valid version accepted, unsupported version rejected with `-32007`, missing header rejected. - [ ] All nox stages pass and coverage ≥ 97%. ## Supporting Information **Code Locations:** - `src/cleveragents/a2a/versioning.py` — `A2aVersionNegotiator` exists but is not wired to the HTTP layer - `src/cleveragents/a2a/asgi.py` — ASGI app does not read `A2A-Version` header - `src/cleveragents/a2a/transport.py` — stub transport never sends headers **Spec References:** - `docs/specification.md` lines 23577–23579: version header declaration requirement - `docs/specification.md` lines 43376–43417: header sent on every request requirement - JSON-RPC error code `-32007`: Version mismatch **Impact:** Without `A2A-Version` header validation, the server cannot enforce protocol version compatibility. External A2A clients that send the required header will not have their version validated. Non-critical since server mode is not yet implemented. ## Subtasks - [ ] Add ASGI middleware (or handler logic) in `src/cleveragents/a2a/asgi.py` to read the `A2A-Version` header from incoming requests - [ ] Wire `A2aVersionNegotiator.is_supported()` into the ASGI pipeline to validate the extracted version - [ ] Return a JSON-RPC 2.0 error with code `-32007` when the version is unsupported or missing - [ ] Implement header injection in `A2aHttpTransport` to send `A2A-Version: <version>` on every outgoing request - [ ] Tests (pytest/Behave): Add unit tests for ASGI version header validation (valid, unsupported, missing) - [ ] Tests (pytest/Behave): Add unit tests for transport header injection - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(a2a): send and validate A2A-Version HTTP header on every request`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`bugfix/backlog-a2a-version-header-validation`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#366 Epic: Post-MVP Deferred Work
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3638
No description provided.