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

freemo commented

2026-03-14 01:13:16 +00:00

Owner

Background and Context

The specification designates the Agent-to-Agent (A2A) Protocol as the sole communication protocol for all client-server interaction (spec §Overview, §Glossary, §Architecture). A2A is built on JSON-RPC 2.0 and defines the fundamental boundary between the Presentation and Application layers. Every CLI command maps to an A2A operation.

The current implementation in src/cleveragents/a2a/ (~25% complete) uses a custom A2aRequest/A2aResponse envelope that does not follow JSON-RPC 2.0 framing. Standard A2A operations (message/send, message/stream, Agent Card discovery) are entirely absent. Zero _cleveragents/*-prefixed extension methods are implemented. The stdio transport for local mode does not exist (the facade is a direct in-process Python call), and the HTTP transport is a stub that raises A2aNotAvailableError.

Expected Behavior

The A2A layer must be a fully compliant JSON-RPC 2.0 protocol layer serving as the sole boundary between presentation and application. Standard A2A operations and all CleverAgents extension methods must be routed through this protocol regardless of deployment mode.

Acceptance Criteria

A2A request/response envelopes use JSON-RPC 2.0 framing (jsonrpc: "2.0", id, method, params, result/error)
Standard A2A operations implemented: message/send, message/stream, Agent Card discovery
CleverAgents extension methods implemented under _cleveragents/ namespace:
- _cleveragents/plan/* (create, execute, apply, status, cancel, tree, explain, correct, diff, artifacts, prompt, rollback)
- _cleveragents/registry/* (tools, resources, actors, skills, validations CRUD)
- _cleveragents/context/* (get, set, inspect, simulate)
- _cleveragents/sync/* (auto-sync, pull, push, status)
- _cleveragents/fs/* (file operations)
- _cleveragents/terminal/* (terminal interaction)
stdio transport for local mode (agent as subprocess, JSON-RPC over stdin/stdout)
HTTP/SSE transport for server mode (functional, not stub)
A2aLocalFacade routes all operations through JSON-RPC dispatch
All CLI commands route through A2A operations (not direct service calls)
Version negotiation per A2A spec
Authentication support (OAuth2/API key) for server mode

Subtasks

Refactor A2aRequest/A2aResponse to JSON-RPC 2.0 envelope format
Implement standard A2A operations (message/send, message/stream, Agent Card)
Implement _cleveragents/plan/* extension methods
Implement _cleveragents/registry/* extension methods
Implement _cleveragents/context/* extension methods
Implement _cleveragents/sync/* extension methods
Implement _cleveragents/fs/* extension methods
Implement _cleveragents/terminal/* extension methods
Implement stdio JSON-RPC transport for local mode
Implement HTTP/SSE transport for server mode
Wire all CLI commands through A2A operations
Tests (Behave): Add scenarios for JSON-RPC 2.0 framing compliance
Tests (Behave): Add scenarios for each extension method namespace
Tests (Robot): Add integration tests for stdio and HTTP transports
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This epic is complete when all child issues are closed AND the A2A protocol layer is fully JSON-RPC 2.0 compliant, all extension methods are routed through the protocol, both transports are functional, and all CLI commands operate exclusively through A2A operations.

## Background and Context The specification designates the Agent-to-Agent (A2A) Protocol as the **sole** communication protocol for all client-server interaction (spec §Overview, §Glossary, §Architecture). A2A is built on **JSON-RPC 2.0** and defines the fundamental boundary between the Presentation and Application layers. Every CLI command maps to an A2A operation. The current implementation in `src/cleveragents/a2a/` (~25% complete) uses a custom `A2aRequest`/`A2aResponse` envelope that does not follow JSON-RPC 2.0 framing. Standard A2A operations (`message/send`, `message/stream`, Agent Card discovery) are entirely absent. Zero `_cleveragents/*`-prefixed extension methods are implemented. The stdio transport for local mode does not exist (the facade is a direct in-process Python call), and the HTTP transport is a stub that raises `A2aNotAvailableError`. ## Expected Behavior The A2A layer must be a fully compliant JSON-RPC 2.0 protocol layer serving as the sole boundary between presentation and application. Standard A2A operations and all CleverAgents extension methods must be routed through this protocol regardless of deployment mode. ## Acceptance Criteria - [ ] A2A request/response envelopes use JSON-RPC 2.0 framing (`jsonrpc: "2.0"`, `id`, `method`, `params`, `result`/`error`) - [ ] Standard A2A operations implemented: `message/send`, `message/stream`, Agent Card discovery - [ ] CleverAgents extension methods implemented under `_cleveragents/` namespace: - `_cleveragents/plan/*` (create, execute, apply, status, cancel, tree, explain, correct, diff, artifacts, prompt, rollback) - `_cleveragents/registry/*` (tools, resources, actors, skills, validations CRUD) - `_cleveragents/context/*` (get, set, inspect, simulate) - `_cleveragents/sync/*` (auto-sync, pull, push, status) - `_cleveragents/fs/*` (file operations) - `_cleveragents/terminal/*` (terminal interaction) - [ ] stdio transport for local mode (agent as subprocess, JSON-RPC over stdin/stdout) - [ ] HTTP/SSE transport for server mode (functional, not stub) - [ ] `A2aLocalFacade` routes all operations through JSON-RPC dispatch - [ ] All CLI commands route through A2A operations (not direct service calls) - [ ] Version negotiation per A2A spec - [ ] Authentication support (OAuth2/API key) for server mode ## Subtasks - [ ] Refactor `A2aRequest`/`A2aResponse` to JSON-RPC 2.0 envelope format - [ ] Implement standard A2A operations (`message/send`, `message/stream`, Agent Card) - [ ] Implement `_cleveragents/plan/*` extension methods - [ ] Implement `_cleveragents/registry/*` extension methods - [ ] Implement `_cleveragents/context/*` extension methods - [ ] Implement `_cleveragents/sync/*` extension methods - [ ] Implement `_cleveragents/fs/*` extension methods - [ ] Implement `_cleveragents/terminal/*` extension methods - [ ] Implement stdio JSON-RPC transport for local mode - [ ] Implement HTTP/SSE transport for server mode - [ ] Wire all CLI commands through A2A operations - [ ] Tests (Behave): Add scenarios for JSON-RPC 2.0 framing compliance - [ ] Tests (Behave): Add scenarios for each extension method namespace - [ ] Tests (Robot): Add integration tests for stdio and HTTP transports - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This epic is complete when all child issues are closed AND the A2A protocol layer is fully JSON-RPC 2.0 compliant, all extension methods are routed through the protocol, both transports are functional, and all CLI commands operate exclusively through A2A operations.

freemo added the

labels

2026-03-14 01:15:28 +00:00

freemo added this to the v3.4.0 milestone

2026-03-14 01:15:47 +00:00

freemo commented

2026-03-14 01:18:51 +00:00

Author

Owner

Dependency Links

Parent Legendary: cleverthis/cleveragents#3 — Core Functionality

Related issues in this repo:

#936 (Output Rendering) — depends on A2A CLI wiring from this Epic
Existing #884 (output envelope alignment) — partially overlaps with A2A response envelope

Standalone child candidates (to be broken out from this Epic's subtasks):

JSON-RPC 2.0 envelope refactor
_cleveragents/plan/* extension methods
_cleveragents/registry/* extension methods
stdio transport implementation
HTTP/SSE transport implementation

## Dependency Links **Parent Legendary**: [cleverthis/cleveragents#3 — Core Functionality](https://git.cleverthis.com/cleverthis/cleveragents/issues/3) **Related issues in this repo**: - #936 (Output Rendering) — depends on A2A CLI wiring from this Epic - Existing #884 (output envelope alignment) — partially overlaps with A2A response envelope **Standalone child candidates** (to be broken out from this Epic's subtasks): - JSON-RPC 2.0 envelope refactor - `_cleveragents/plan/*` extension methods - `_cleveragents/registry/*` extension methods - stdio transport implementation - HTTP/SSE transport implementation

freemo referenced this issue

2026-03-14 01:18:54 +00:00

Epic: LSP Runtime Implementation — Functional Language Server Lifecycle and Context Enrichment #934

freemo referenced this issue

2026-03-14 01:18:56 +00:00

Epic: ACMS Context Assembly Pipeline — Functional CRP Handlers and Pipeline Components #935

freemo referenced this issue

2026-03-14 01:18:59 +00:00

Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework #936

freemo added the

Points

88

label

2026-03-14 03:14:49 +00:00

freemo referenced this issue

2026-03-14 03:15:20 +00:00

Legendary: Specification Alignment — Close All Gaps Between Implementation and Specification #945

freemo added a new dependency

2026-03-14 03:19:36 +00:00

#945 Legendary: Specification Alignment — Close All Gaps Between Implementation and Specification

freemo self-assigned this

2026-03-14 04:27:03 +00:00

freemo was unassigned by brent.edwards

2026-03-30 18:34:41 +00:00

brent.edwards self-assigned this

2026-03-30 18:34:41 +00:00

brent.edwards commented

2026-03-30 18:38:18 +00:00

Member

Implementation journal update (Phase 2 start):

Verified issue #933 is open and reassigned to brent.edwards.
Attempted to transition label from State/Verified to State/In Progress via Forgejo API; assignee update succeeded but state label change appears restricted by repository permissions (state remained State/Verified).
In isolated workspace /tmp/cleveragents-933, I reviewed:
- docs/specification.md (A2A as sole JSON-RPC 2.0 boundary)
- CONTRIBUTING.md (nox-only quality gates, >=97% coverage, commit/PR rules)
- docs/timeline.md (M9 A2A stream context)
I integrated the existing in-repo M9 A2A implementation commits as the working baseline for this issue:
- JSON-RPC 2.0 envelope + router/handlers + tests
- stdio transport + tests
- HTTP transport + tests
During integration, I resolved transport-layer merge conflicts by preserving both selector APIs (A2aTransportSelector and TransportSelector) to keep compatibility with existing feature + robot suites.

Next steps:

run nox gates and identify breakages,
patch integration gaps (extension namespace coverage, selector/protocol compatibility, transport contract consistency),
update subtasks/checklists and provide final quality metrics.

Implementation journal update (Phase 2 start): - Verified issue #933 is open and reassigned to `brent.edwards`. - Attempted to transition label from `State/Verified` to `State/In Progress` via Forgejo API; assignee update succeeded but state label change appears restricted by repository permissions (state remained `State/Verified`). - In isolated workspace `/tmp/cleveragents-933`, I reviewed: - `docs/specification.md` (A2A as sole JSON-RPC 2.0 boundary) - `CONTRIBUTING.md` (nox-only quality gates, >=97% coverage, commit/PR rules) - `docs/timeline.md` (M9 A2A stream context) - I integrated the existing in-repo M9 A2A implementation commits as the working baseline for this issue: - JSON-RPC 2.0 envelope + router/handlers + tests - stdio transport + tests - HTTP transport + tests - During integration, I resolved transport-layer merge conflicts by preserving both selector APIs (`A2aTransportSelector` and `TransportSelector`) to keep compatibility with existing feature + robot suites. Next steps: 1) run nox gates and identify breakages, 2) patch integration gaps (extension namespace coverage, selector/protocol compatibility, transport contract consistency), 3) update subtasks/checklists and provide final quality metrics.

Rows
Columns

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

Background and Context

Expected Behavior

Acceptance Criteria

Subtasks

Definition of Done

Dependency Links