cleveragents/cleveragents-core

Fork 3

UAT: `A2aErrorDetail.code` is typed as `str` — JSON-RPC 2.0 requires integer error codes #2462

New issue

Open

opened 2026-04-03 18:30:36 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:30:36 +00:00

Owner

Metadata

Branch: fix/a2a-error-code-integer
Commit Message: fix(a2a): change A2aErrorDetail.code from str to int for JSON-RPC 2.0 conformance
Milestone: v3.8.0
Parent Epic: #690

Summary

A2aErrorDetail.code in src/cleveragents/a2a/models.py is typed as str, but the JSON-RPC 2.0 specification (which A2A is built on) requires the error code field to be an integer. This means A2A error responses produced by CleverAgents are non-conformant with the JSON-RPC 2.0 standard, and any strictly-conformant A2A client will reject them.

What Was Tested

Code analysis of src/cleveragents/a2a/models.py
Code analysis of src/cleveragents/a2a/errors.py
JSON-RPC 2.0 specification review

Expected Behavior (from spec)

Per JSON-RPC 2.0 specification (which A2A is built on, per docs/specification.md line 55):

"A2A is built on JSON-RPC 2.0"

JSON-RPC 2.0 error object format:

{
  "code": -32600,
  "message": "Invalid Request",
  "data": {}
}

The code field MUST be an integer. Standard JSON-RPC 2.0 error codes:

-32700 Parse error
-32600 Invalid Request
-32601 Method not found
-32602 Invalid params
-32603 Internal error
-32000 to -32099 Server error (reserved)

Actual Behavior

In src/cleveragents/a2a/models.py (line 69):

class A2aErrorDetail(BaseModel):
    code: str  # ← WRONG: should be int
    message: str
    details: dict[str, Any] = {}

In src/cleveragents/a2a/errors.py, the error codes are defined as string constants:

NOT_FOUND: str = "NOT_FOUND"
VALIDATION_ERROR: str = "VALIDATION_ERROR"
INVALID_STATE: str = "INVALID_STATE"
PLAN_ERROR: str = "PLAN_ERROR"
AUTH_ERROR: str = "AUTH_ERROR"
FORBIDDEN: str = "FORBIDDEN"
CONFIGURATION_ERROR: str = "CONFIGURATION_ERROR"
INTERNAL_ERROR: str = "INTERNAL_ERROR"

And map_domain_error() returns tuple[str, str] — both code and message as strings.

Code Location

src/cleveragents/a2a/models.py line 69: code: str
src/cleveragents/a2a/errors.py lines 32-39: string error code constants
src/cleveragents/a2a/errors.py line 102: def map_domain_error(exc: Exception) -> tuple[str, str]:

Impact

Any A2A client that validates JSON-RPC 2.0 conformance will reject error responses from CleverAgents because code is a string instead of an integer. This breaks interoperability with the A2A ecosystem.

Subtasks

Change A2aErrorDetail.code from str to int in models.py
Replace string error code constants in errors.py with integer constants (using JSON-RPC 2.0 standard codes where applicable, and server-defined codes in the -32000 to -32099 range for application errors)
Update map_domain_error() return type from tuple[str, str] to tuple[int, str]
Update all call sites that construct A2aErrorDetail with string codes
Update BDD tests to use integer error codes
Verify all CI checks pass

Definition of Done

A2aErrorDetail.code is typed as int
Error codes are integers conforming to JSON-RPC 2.0 specification
map_domain_error() returns tuple[int, str]
All existing tests updated and passing
All CI checks pass
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/a2a-error-code-integer` - **Commit Message**: `fix(a2a): change A2aErrorDetail.code from str to int for JSON-RPC 2.0 conformance` - **Milestone**: v3.8.0 - **Parent Epic**: #690 ## Summary `A2aErrorDetail.code` in `src/cleveragents/a2a/models.py` is typed as `str`, but the JSON-RPC 2.0 specification (which A2A is built on) requires the error `code` field to be an **integer**. This means A2A error responses produced by CleverAgents are non-conformant with the JSON-RPC 2.0 standard, and any strictly-conformant A2A client will reject them. ## What Was Tested - Code analysis of `src/cleveragents/a2a/models.py` - Code analysis of `src/cleveragents/a2a/errors.py` - JSON-RPC 2.0 specification review ## Expected Behavior (from spec) Per JSON-RPC 2.0 specification (which A2A is built on, per `docs/specification.md` line 55): > "A2A is built on JSON-RPC 2.0" JSON-RPC 2.0 error object format: ```json { "code": -32600, "message": "Invalid Request", "data": {} } ``` The `code` field MUST be an integer. Standard JSON-RPC 2.0 error codes: - `-32700` Parse error - `-32600` Invalid Request - `-32601` Method not found - `-32602` Invalid params - `-32603` Internal error - `-32000` to `-32099` Server error (reserved) ## Actual Behavior In `src/cleveragents/a2a/models.py` (line 69): ```python class A2aErrorDetail(BaseModel): code: str # ← WRONG: should be int message: str details: dict[str, Any] = {} ``` In `src/cleveragents/a2a/errors.py`, the error codes are defined as string constants: ```python NOT_FOUND: str = "NOT_FOUND" VALIDATION_ERROR: str = "VALIDATION_ERROR" INVALID_STATE: str = "INVALID_STATE" PLAN_ERROR: str = "PLAN_ERROR" AUTH_ERROR: str = "AUTH_ERROR" FORBIDDEN: str = "FORBIDDEN" CONFIGURATION_ERROR: str = "CONFIGURATION_ERROR" INTERNAL_ERROR: str = "INTERNAL_ERROR" ``` And `map_domain_error()` returns `tuple[str, str]` — both code and message as strings. ## Code Location - `src/cleveragents/a2a/models.py` line 69: `code: str` - `src/cleveragents/a2a/errors.py` lines 32-39: string error code constants - `src/cleveragents/a2a/errors.py` line 102: `def map_domain_error(exc: Exception) -> tuple[str, str]:` ## Impact Any A2A client that validates JSON-RPC 2.0 conformance will reject error responses from CleverAgents because `code` is a string instead of an integer. This breaks interoperability with the A2A ecosystem. ## Subtasks - [ ] Change `A2aErrorDetail.code` from `str` to `int` in `models.py` - [ ] Replace string error code constants in `errors.py` with integer constants (using JSON-RPC 2.0 standard codes where applicable, and server-defined codes in the `-32000` to `-32099` range for application errors) - [ ] Update `map_domain_error()` return type from `tuple[str, str]` to `tuple[int, str]` - [ ] Update all call sites that construct `A2aErrorDetail` with string codes - [ ] Update BDD tests to use integer error codes - [ ] Verify all CI checks pass ## Definition of Done - [ ] `A2aErrorDetail.code` is typed as `int` - [ ] Error codes are integers conforming to JSON-RPC 2.0 specification - [ ] `map_domain_error()` returns `tuple[int, str]` - [ ] All existing tests updated and passing - [ ] All CI checks pass - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-03 18:30:40 +00:00

freemo added a new dependency

2026-04-03 18:31:15 +00:00

#690 feat(a2a): Implement JSON-RPC 2.0 wire format and method routing

freemo referenced this issue

2026-04-03 18:33:21 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1561 — v3.7.0 #2467

freemo added the

MoSCoW

Must have

label

2026-04-03 18:34:44 +00:00

freemo commented

2026-04-03 18:34:58 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — A2aErrorDetail.code typed as str but JSON-RPC 2.0 requires integer error codes. This breaks protocol compliance.
MoSCoW: Must Have — JSON-RPC 2.0 compliance is non-negotiable. Integer error codes are a hard protocol requirement.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: High — `A2aErrorDetail.code` typed as `str` but JSON-RPC 2.0 requires integer error codes. This breaks protocol compliance. - **MoSCoW**: Must Have — JSON-RPC 2.0 compliance is non-negotiable. Integer error codes are a hard protocol requirement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:37:10 +00:00

[CA-GROOMER] Backlog Groomer — Session State (groomer-1) #2386

freemo referenced this issue

2026-04-03 18:37:27 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo referenced this issue

2026-04-03 19:02:20 +00:00

UAT: A2aErrorDetail.code is typed as str — JSON-RPC 2.0 requires error codes to be integers #2563

freemo referenced this issue

2026-04-03 19:03:22 +00:00

[CA-GROOMER] Backlog Groomer — Session State (groomer-1) #2386

freemo referenced this issue

2026-04-04 19:28:53 +00:00

UAT: A2aErrorDetail.code is str but JSON-RPC 2.0 requires integer error codes; map_domain_error returns string codes instead of integer codes #2746

freemo commented

2026-04-04 19:28:59 +00:00

Author

Owner

⚠️ Potential duplicate detected: This issue appears to describe the same bug as #2746 ("UAT: A2aErrorDetail.code is str but JSON-RPC 2.0 requires integer error codes; map_domain_error returns string codes instead of integer codes").

Both issues describe A2aErrorDetail.code being typed as str instead of int, targeting the same code locations and milestone (v3.8.0).

Note: #2746 is more comprehensive and is already in State/Verified. Consider closing this issue (#2462) as a duplicate of #2746.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

⚠️ **Potential duplicate detected**: This issue appears to describe the same bug as #2746 ("UAT: A2aErrorDetail.code is str but JSON-RPC 2.0 requires integer error codes; map_domain_error returns string codes instead of integer codes"). Both issues describe `A2aErrorDetail.code` being typed as `str` instead of `int`, targeting the same code locations and milestone (v3.8.0). **Note**: #2746 is more comprehensive and is already in `State/Verified`. Consider closing this issue (#2462) as a duplicate of #2746. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo removed the

MoSCoW

Must have

label

2026-04-05 03:45:45 +00:00