Add JSON-RPC 2.0 router with batch, notification, and handler registration support #10864

New issue

Open

opened 2026-04-26 07:52:59 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-26 07:52:59 +00:00

Owner

Metadata

Commit Message: feat(shared): add JSON-RPC 2.0 router with batch, notification, and handler registration
Branch: feature/m9-jsonrpc-router

Background and context

The A2A server (M9) requires a standalone, reusable JSON-RPC 2.0 router that strictly adheres to the specification at https://www.jsonrpc.org/specification. The existing A2aLocalFacade has hardcoded handlers and no batch or notification support. A generic JsonRpcRouter in shared/ will serve as the foundation for the A2A HTTP and stdio transports.

Current behavior

No standalone JSON-RPC 2.0 router exists. The A2aLocalFacade dispatches to hardcoded handlers and does not support:

Batch requests (array of request objects)
Notifications (requests without id — no response expected)
Generic handler registration via register(method, handler)

Expected behavior

A JsonRpcRouter class in src/cleveragents/shared/jsonrpc.py that:

Validates strict JSON-RPC 2.0 request/response structure (jsonrpc, method, params, id fields)
Returns proper error objects with code, message, data fields (standard codes: -32700, -32600, -32601, -32602, -32603)
Processes batch requests (list of request objects → list of responses, notifications omitted)
Handles notifications (requests without id) by processing but returning no response
Routes method calls to registered handlers via register(method, handler)

Acceptance criteria

JsonRpcRouter.register(method, handler) binds a callable to a method name
JsonRpcRouter.dispatch(raw_dict) returns a response dict or None for notifications
JsonRpcRouter.dispatch_batch(raw_list) returns a list of response dicts
JsonRpcRouter.process(payload) auto-detects single vs batch
Unknown methods return -32601 Method not found
Missing/invalid jsonrpc field returns -32600 Invalid Request
Handler exceptions return -32603 Internal error
Notifications (no id) produce no response entry
All quality gates pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report)

Supporting information

JSON-RPC 2.0 specification: https://www.jsonrpc.org/specification
Milestone: v3.8.0 (M9: Server Implementation)
Related: src/cleveragents/a2a/models.py (existing A2A wire models), src/cleveragents/a2a/facade.py (existing facade)

Subtasks

Create src/cleveragents/shared/jsonrpc.py with JsonRpcRouter class
Export new symbols from src/cleveragents/shared/__init__.py
Write Behave BDD feature file features/jsonrpc_router.feature
Write step definitions features/steps/jsonrpc_router_steps.py
Run nox -e lint and fix any issues
Run nox -e typecheck and fix any issues
Run nox -e unit_tests and fix any issues
Run nox -e coverage_report and verify >= 97%

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 matches the Commit Message in Metadata exactly.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The commit is submitted as a PR to master, reviewed, and merged.

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor

## Metadata - **Commit Message:** `feat(shared): add JSON-RPC 2.0 router with batch, notification, and handler registration` - **Branch:** `feature/m9-jsonrpc-router` ## Background and context The A2A server (M9) requires a standalone, reusable JSON-RPC 2.0 router that strictly adheres to the specification at https://www.jsonrpc.org/specification. The existing `A2aLocalFacade` has hardcoded handlers and no batch or notification support. A generic `JsonRpcRouter` in `shared/` will serve as the foundation for the A2A HTTP and stdio transports. ## Current behavior No standalone JSON-RPC 2.0 router exists. The `A2aLocalFacade` dispatches to hardcoded handlers and does not support: - Batch requests (array of request objects) - Notifications (requests without `id` — no response expected) - Generic handler registration via `register(method, handler)` ## Expected behavior A `JsonRpcRouter` class in `src/cleveragents/shared/jsonrpc.py` that: 1. Validates strict JSON-RPC 2.0 request/response structure (`jsonrpc`, `method`, `params`, `id` fields) 2. Returns proper error objects with `code`, `message`, `data` fields (standard codes: -32700, -32600, -32601, -32602, -32603) 3. Processes batch requests (list of request objects → list of responses, notifications omitted) 4. Handles notifications (requests without `id`) by processing but returning no response 5. Routes method calls to registered handlers via `register(method, handler)` ## Acceptance criteria - `JsonRpcRouter.register(method, handler)` binds a callable to a method name - `JsonRpcRouter.dispatch(raw_dict)` returns a response dict or `None` for notifications - `JsonRpcRouter.dispatch_batch(raw_list)` returns a list of response dicts - `JsonRpcRouter.process(payload)` auto-detects single vs batch - Unknown methods return `-32601 Method not found` - Missing/invalid `jsonrpc` field returns `-32600 Invalid Request` - Handler exceptions return `-32603 Internal error` - Notifications (no `id`) produce no response entry - All quality gates pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report`) ## Supporting information - JSON-RPC 2.0 specification: https://www.jsonrpc.org/specification - Milestone: v3.8.0 (M9: Server Implementation) - Related: `src/cleveragents/a2a/models.py` (existing A2A wire models), `src/cleveragents/a2a/facade.py` (existing facade) ## Subtasks - [ ] Create `src/cleveragents/shared/jsonrpc.py` with `JsonRpcRouter` class - [ ] Export new symbols from `src/cleveragents/shared/__init__.py` - [ ] Write Behave BDD feature file `features/jsonrpc_router.feature` - [ ] Write step definitions `features/steps/jsonrpc_router_steps.py` - [ ] Run `nox -e lint` and fix any issues - [ ] Run `nox -e typecheck` and fix any issues - [ ] Run `nox -e unit_tests` and fix any issues - [ ] Run `nox -e coverage_report` and verify >= 97% ## 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 matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The commit is submitted as a PR to master, reviewed, and merged. --- Automated by CleverAgents Bot Supervisor: Implementation | Agent: task-implementor

HAL9000 added this to the v3.8.0 milestone

2026-04-26 07:52:59 +00:00