UAT: A2aVersion and A2aVersionNegotiator have inconsistent version constants — JSON-RPC version conflated with A2A protocol version #4085

New issue

Open

opened 2026-04-06 10:12:02 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:12:02 +00:00

Owner

Metadata

Branch: fix/a2a-version-constants-naming
Commit Message: fix(a2a): clarify version constant naming — separate JSON-RPC version from A2A protocol version
Milestone: Backlog
Parent Epic: #933

Bug Report

Feature Area: API Versioning and Backward Compatibility
Severity: Medium
Found by: UAT Testing (automated)

Summary

There are two separate version constants for the A2A protocol that are inconsistent and conflate two different concepts:

A2aVersion.CURRENT = "2.0" (in src/cleveragents/a2a/models.py) — this is actually the JSON-RPC version, not the A2A protocol version
A2aVersionNegotiator.CURRENT_VERSION = "1.0" (in src/cleveragents/a2a/versioning.py) — this is the A2A protocol version

This inconsistency creates confusion about what "version" means in the A2A context and could lead to incorrect version comparisons.

Expected Behavior

The A2A protocol version and the JSON-RPC transport version should be clearly separated:

JSON-RPC version: "2.0" (transport layer, fixed)
A2A protocol version: "1.0" (application layer, negotiable)

These should be clearly named and documented to avoid confusion.

Actual Behavior

In src/cleveragents/a2a/models.py:

JSONRPC_VERSION: str = "2.0"

class A2aVersion:
    """A2A protocol version constants.
    Kept for backward compatibility — the wire format now uses the
    JSON-RPC 2.0 ``jsonrpc`` field with value ``"2.0"`` rather than
    a proprietary ``a2a_version`` field.
    """
    CURRENT: str = JSONRPC_VERSION  # "2.0" — this is JSON-RPC, not A2A!
    SUPPORTED: tuple[str, ...] = (JSONRPC_VERSION,)

In src/cleveragents/a2a/versioning.py:

class A2aVersionNegotiator:
    CURRENT_VERSION: str = "1.0"  # This is the actual A2A protocol version
    SUPPORTED_VERSIONS: tuple[str, ...] = ("1.0",)

The A2aVersion class docstring acknowledges this is "kept for backward compatibility" but the naming is misleading — A2aVersion.CURRENT = "2.0" looks like the A2A protocol version is 2.0, when in fact it's the JSON-RPC transport version.

Impact

Developers reading the code may confuse the JSON-RPC version ("2.0") with the A2A protocol version ("1.0")
Tests that check A2aVersion.CURRENT may be testing the wrong thing
Future version negotiation logic may use the wrong constant

Code Location

src/cleveragents/a2a/models.py — A2aVersion class (lines ~30-40)
src/cleveragents/a2a/versioning.py — A2aVersionNegotiator class

Suggested Fix

Rename A2aVersion to JsonRpcVersion or clearly document that it represents the JSON-RPC transport version, not the A2A application protocol version. Alternatively, remove A2aVersion entirely since JSONRPC_VERSION constant already exists.

Subtasks

Audit all usages of A2aVersion.CURRENT and A2aVersion.SUPPORTED across the codebase
Determine whether A2aVersion class should be renamed, deprecated, or removed
If renaming: rename A2aVersion → JsonRpcVersion (or similar) and update all call sites
If deprecating: add DeprecationWarning to A2aVersion with a pointer to the correct constant
Ensure A2aVersionNegotiator.CURRENT_VERSION is clearly documented as the A2A application protocol version
Update or add docstrings to distinguish transport-layer vs. application-layer versioning
Update any tests that reference A2aVersion.CURRENT to use the correct constant
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

All subtasks above are completed and checked off
A2aVersion and A2aVersionNegotiator version constants are clearly named and documented to avoid conflation of JSON-RPC transport version with A2A application protocol version
No call site uses the wrong version constant for its context
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, 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
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%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.0 (A2A Protocol Compliance epic). It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `fix/a2a-version-constants-naming` - **Commit Message**: `fix(a2a): clarify version constant naming — separate JSON-RPC version from A2A protocol version` - **Milestone**: Backlog - **Parent Epic**: #933 ## Bug Report **Feature Area:** API Versioning and Backward Compatibility **Severity:** Medium **Found by:** UAT Testing (automated) ### Summary There are two separate version constants for the A2A protocol that are inconsistent and conflate two different concepts: 1. `A2aVersion.CURRENT = "2.0"` (in `src/cleveragents/a2a/models.py`) — this is actually the **JSON-RPC version**, not the A2A protocol version 2. `A2aVersionNegotiator.CURRENT_VERSION = "1.0"` (in `src/cleveragents/a2a/versioning.py`) — this is the **A2A protocol version** This inconsistency creates confusion about what "version" means in the A2A context and could lead to incorrect version comparisons. ### Expected Behavior The A2A protocol version and the JSON-RPC transport version should be clearly separated: - JSON-RPC version: `"2.0"` (transport layer, fixed) - A2A protocol version: `"1.0"` (application layer, negotiable) These should be clearly named and documented to avoid confusion. ### Actual Behavior In `src/cleveragents/a2a/models.py`: ```python JSONRPC_VERSION: str = "2.0" class A2aVersion: """A2A protocol version constants. Kept for backward compatibility — the wire format now uses the JSON-RPC 2.0 ``jsonrpc`` field with value ``"2.0"`` rather than a proprietary ``a2a_version`` field. """ CURRENT: str = JSONRPC_VERSION # "2.0" — this is JSON-RPC, not A2A! SUPPORTED: tuple[str, ...] = (JSONRPC_VERSION,) ``` In `src/cleveragents/a2a/versioning.py`: ```python class A2aVersionNegotiator: CURRENT_VERSION: str = "1.0" # This is the actual A2A protocol version SUPPORTED_VERSIONS: tuple[str, ...] = ("1.0",) ``` The `A2aVersion` class docstring acknowledges this is "kept for backward compatibility" but the naming is misleading — `A2aVersion.CURRENT = "2.0"` looks like the A2A protocol version is 2.0, when in fact it's the JSON-RPC transport version. ### Impact - Developers reading the code may confuse the JSON-RPC version ("2.0") with the A2A protocol version ("1.0") - Tests that check `A2aVersion.CURRENT` may be testing the wrong thing - Future version negotiation logic may use the wrong constant ### Code Location - `src/cleveragents/a2a/models.py` — `A2aVersion` class (lines ~30-40) - `src/cleveragents/a2a/versioning.py` — `A2aVersionNegotiator` class ### Suggested Fix Rename `A2aVersion` to `JsonRpcVersion` or clearly document that it represents the JSON-RPC transport version, not the A2A application protocol version. Alternatively, remove `A2aVersion` entirely since `JSONRPC_VERSION` constant already exists. ## Subtasks - [ ] Audit all usages of `A2aVersion.CURRENT` and `A2aVersion.SUPPORTED` across the codebase - [ ] Determine whether `A2aVersion` class should be renamed, deprecated, or removed - [ ] If renaming: rename `A2aVersion` → `JsonRpcVersion` (or similar) and update all call sites - [ ] If deprecating: add `DeprecationWarning` to `A2aVersion` with a pointer to the correct constant - [ ] Ensure `A2aVersionNegotiator.CURRENT_VERSION` is clearly documented as the A2A application protocol version - [ ] Update or add docstrings to distinguish transport-layer vs. application-layer versioning - [ ] Update any tests that reference `A2aVersion.CURRENT` to use the correct constant - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] All subtasks above are completed and checked off - [ ] `A2aVersion` and `A2aVersionNegotiator` version constants are clearly named and documented to avoid conflation of JSON-RPC transport version with A2A application protocol version - [ ] No call site uses the wrong version constant for its context - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, 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 - [ ] 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% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0 (A2A Protocol Compliance epic). It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:12:20 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo added the

Points

label

2026-04-06 10:15:35 +00:00

freemo referenced this issue

2026-04-06 10:23:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775