cleveragents/cleveragents-core

Fork 3

UAT: docs/api/a2a.md contains multiple stale API signatures — A2aLocalFacade, A2aRequest, A2aResponse, A2aEventQueue, and ServerConnectionConfig documented incorrectly #1683

New issue

Open

opened 2026-04-02 23:28:59 +00:00 by freemo · 2 comments

freemo commented

2026-04-02 23:28:59 +00:00

Owner

Metadata

Branch: fix/a2a-api-docs-stale-signatures
Commit Message: docs(a2a): correct stale API signatures in docs/api/a2a.md
Milestone: v3.7.0
Parent Epic: #933

Bug Report

Feature Area: REST API endpoints / A2A Protocol — API Documentation
Severity: Medium
Found by: UAT tester uat-tester-3993412-1775170781

What Was Tested

Verified that the public API documentation in docs/api/a2a.md accurately reflects the actual implementation in src/cleveragents/a2a/.

Expected Behavior (from spec)

API documentation should accurately describe the actual public interface of all classes and methods.

Actual Behavior

docs/api/a2a.md contains six stale/incorrect API signatures that do not match the actual implementation:

1. A2aLocalFacade.dispatch documented as async but is synchronous:

# docs/api/a2a.md says:
async def dispatch(self, request: A2aRequest) -> A2aResponse: ...

# Actual implementation (facade.py):
def dispatch(self, request: A2aRequest) -> A2aResponse:  # synchronous

Code calling await facade.dispatch(...) as documented will fail with a TypeError.

2. A2aRequest documented with wrong fields:

# docs/api/a2a.md says:
class A2aRequest(BaseModel):
    operation: str
    params: dict[str, Any] = {}
    version: A2aVersion = A2aVersion.V1  # A2aVersion.V1 does not exist!

# Actual implementation (models.py):
class A2aRequest(BaseModel):
    a2a_version: str = A2aVersion.CURRENT
    request_id: str = ""
    operation: str
    params: dict[str, Any] = {}
    auth: dict[str, Any] | None = None

A2aVersion.V1 does not exist — only A2aVersion.CURRENT and A2aVersion.SUPPORTED are defined.

3. A2aResponse documented with wrong fields:

# docs/api/a2a.md says:
class A2aResponse(BaseModel):
    success: bool          # field does not exist!
    data: Any | None = None  # wrong type, actual is dict[str, Any]
    error: A2aErrorDetail | None = None

# Actual implementation (models.py):
class A2aResponse(BaseModel):
    a2a_version: str = A2aVersion.CURRENT
    request_id: str
    status: str  # 'ok' or 'error', not a bool 'success'
    data: dict[str, Any] = {}
    error: A2aErrorDetail | None = None
    timing_ms: float | None = None

4. A2aEventQueue documented with non-existent subscribe() async iterator:

# docs/api/a2a.md says:
queue = A2aEventQueue()
async for event in queue.subscribe("plan-42"):  # subscribe() does not exist!
    print(event.type, event.payload)

# Actual implementation (events.py):
sub_id = queue.subscribe_local(callback)  # synchronous callback-based
queue.subscribe_remote(endpoint)  # raises A2aNotAvailableError

A2aEventQueue has no subscribe() method. The documented async iterator pattern is entirely absent.

5. ServerConnectionConfig documented with wrong constructor arguments:

# docs/api/a2a.md says:
config = ServerConnectionConfig(url="https://my-server.example.com", token="...")

# Actual implementation (server_config.py):
config = ServerConnectionConfig(
    server_url="https://my-server.example.com",  # 'url' -> 'server_url'
    auth_token_ref="MY_TOKEN_ENV_VAR",           # 'token' -> 'auth_token_ref'
)

The documented url and token parameters do not exist. Using the documented API raises ValidationError.

6. StubServerClient/StubRemoteExecutionClient/StubAuthClient documented as raising A2aNotAvailableError but actually raise NotImplementedError:

# docs/api/a2a.md says:
# "StubServerClient, StubRemoteExecutionClient, and StubAuthClient raise
#  A2aNotAvailableError for all methods until server mode is fully implemented."

# Actual implementation (clients.py):
class StubServerClient:
    def health_check(self) -> bool:
        raise NotImplementedError(_STUB_MSG)  # NOT A2aNotAvailableError!

Steps to Reproduce

from cleveragents.a2a.facade import A2aLocalFacade
from cleveragents.a2a.models import A2aRequest, A2aVersion
from cleveragents.a2a.events import A2aEventQueue
from cleveragents.a2a.server_config import ServerConnectionConfig
import inspect

# Bug 1: dispatch is not async
facade = A2aLocalFacade()
print(inspect.iscoroutinefunction(facade.dispatch))  # False, docs say True

# Bug 2: A2aVersion.V1 does not exist
print(hasattr(A2aVersion, 'V1'))  # False

# Bug 3: A2aResponse has no 'success' field
from cleveragents.a2a.models import A2aResponse
resp = A2aResponse(request_id='x', status='ok')
print('success' in resp.model_dump())  # False

# Bug 4: A2aEventQueue has no 'subscribe' method
queue = A2aEventQueue()
print(hasattr(queue, 'subscribe'))  # False

# Bug 5: ServerConnectionConfig rejects 'url' and 'token'
try:
    ServerConnectionConfig(url="https://example.com", token="abc")
except Exception as e:
    print(type(e).__name__)  # ValidationError

# Bug 6: StubServerClient raises NotImplementedError, not A2aNotAvailableError
from cleveragents.a2a.clients import StubServerClient
from cleveragents.a2a.errors import A2aNotAvailableError
stub = StubServerClient()
try:
    stub.health_check()
except NotImplementedError:
    print("NotImplementedError raised, not A2aNotAvailableError")

Code Location

Documentation: docs/api/a2a.md
Actual implementation: src/cleveragents/a2a/facade.py, src/cleveragents/a2a/models.py, src/cleveragents/a2a/events.py, src/cleveragents/a2a/server_config.py, src/cleveragents/a2a/clients.py

Impact

Developers following the API documentation will write broken code. The async def dispatch signature is particularly dangerous as it will cause silent failures in async contexts.

Subtasks

Correct A2aLocalFacade.dispatch signature in docs/api/a2a.md — remove async, mark as synchronous
Correct A2aRequest model fields in docs/api/a2a.md — add a2a_version, request_id, auth; remove non-existent version: A2aVersion.V1
Correct A2aResponse model fields in docs/api/a2a.md — replace success: bool with status: str; fix data type to dict[str, Any]; add timing_ms
Correct A2aEventQueue API in docs/api/a2a.md — remove non-existent subscribe() async iterator; document actual subscribe_local() and subscribe_remote() methods
Correct ServerConnectionConfig constructor args in docs/api/a2a.md — rename url → server_url, token → auth_token_ref
Correct stub client exception documentation in docs/api/a2a.md — replace A2aNotAvailableError with NotImplementedError for StubServerClient, StubRemoteExecutionClient, StubAuthClient
Cross-check all other public symbols in docs/api/a2a.md against current implementation to catch any additional drift
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
All six documented API discrepancies in docs/api/a2a.md are corrected to match the actual implementation.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (docs(a2a): correct stale API signatures in docs/api/a2a.md), 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 (fix/a2a-api-docs-stale-signatures).
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**: `fix/a2a-api-docs-stale-signatures` - **Commit Message**: `docs(a2a): correct stale API signatures in docs/api/a2a.md` - **Milestone**: v3.7.0 - **Parent Epic**: #933 ## Bug Report **Feature Area**: REST API endpoints / A2A Protocol — API Documentation **Severity**: Medium **Found by**: UAT tester uat-tester-3993412-1775170781 ### What Was Tested Verified that the public API documentation in `docs/api/a2a.md` accurately reflects the actual implementation in `src/cleveragents/a2a/`. ### Expected Behavior (from spec) API documentation should accurately describe the actual public interface of all classes and methods. ### Actual Behavior `docs/api/a2a.md` contains **six stale/incorrect API signatures** that do not match the actual implementation: **1. `A2aLocalFacade.dispatch` documented as `async` but is synchronous:** ```python # docs/api/a2a.md says: async def dispatch(self, request: A2aRequest) -> A2aResponse: ... # Actual implementation (facade.py): def dispatch(self, request: A2aRequest) -> A2aResponse: # synchronous ``` Code calling `await facade.dispatch(...)` as documented will fail with a `TypeError`. **2. `A2aRequest` documented with wrong fields:** ```python # docs/api/a2a.md says: class A2aRequest(BaseModel): operation: str params: dict[str, Any] = {} version: A2aVersion = A2aVersion.V1 # A2aVersion.V1 does not exist! # Actual implementation (models.py): class A2aRequest(BaseModel): a2a_version: str = A2aVersion.CURRENT request_id: str = "" operation: str params: dict[str, Any] = {} auth: dict[str, Any] | None = None ``` `A2aVersion.V1` does not exist — only `A2aVersion.CURRENT` and `A2aVersion.SUPPORTED` are defined. **3. `A2aResponse` documented with wrong fields:** ```python # docs/api/a2a.md says: class A2aResponse(BaseModel): success: bool # field does not exist! data: Any | None = None # wrong type, actual is dict[str, Any] error: A2aErrorDetail | None = None # Actual implementation (models.py): class A2aResponse(BaseModel): a2a_version: str = A2aVersion.CURRENT request_id: str status: str # 'ok' or 'error', not a bool 'success' data: dict[str, Any] = {} error: A2aErrorDetail | None = None timing_ms: float | None = None ``` **4. `A2aEventQueue` documented with non-existent `subscribe()` async iterator:** ```python # docs/api/a2a.md says: queue = A2aEventQueue() async for event in queue.subscribe("plan-42"): # subscribe() does not exist! print(event.type, event.payload) # Actual implementation (events.py): sub_id = queue.subscribe_local(callback) # synchronous callback-based queue.subscribe_remote(endpoint) # raises A2aNotAvailableError ``` `A2aEventQueue` has no `subscribe()` method. The documented async iterator pattern is entirely absent. **5. `ServerConnectionConfig` documented with wrong constructor arguments:** ```python # docs/api/a2a.md says: config = ServerConnectionConfig(url="https://my-server.example.com", token="...") # Actual implementation (server_config.py): config = ServerConnectionConfig( server_url="https://my-server.example.com", # 'url' -> 'server_url' auth_token_ref="MY_TOKEN_ENV_VAR", # 'token' -> 'auth_token_ref' ) ``` The documented `url` and `token` parameters do not exist. Using the documented API raises `ValidationError`. **6. `StubServerClient`/`StubRemoteExecutionClient`/`StubAuthClient` documented as raising `A2aNotAvailableError` but actually raise `NotImplementedError`:** ```python # docs/api/a2a.md says: # "StubServerClient, StubRemoteExecutionClient, and StubAuthClient raise # A2aNotAvailableError for all methods until server mode is fully implemented." # Actual implementation (clients.py): class StubServerClient: def health_check(self) -> bool: raise NotImplementedError(_STUB_MSG) # NOT A2aNotAvailableError! ``` ### Steps to Reproduce ```python from cleveragents.a2a.facade import A2aLocalFacade from cleveragents.a2a.models import A2aRequest, A2aVersion from cleveragents.a2a.events import A2aEventQueue from cleveragents.a2a.server_config import ServerConnectionConfig import inspect # Bug 1: dispatch is not async facade = A2aLocalFacade() print(inspect.iscoroutinefunction(facade.dispatch)) # False, docs say True # Bug 2: A2aVersion.V1 does not exist print(hasattr(A2aVersion, 'V1')) # False # Bug 3: A2aResponse has no 'success' field from cleveragents.a2a.models import A2aResponse resp = A2aResponse(request_id='x', status='ok') print('success' in resp.model_dump()) # False # Bug 4: A2aEventQueue has no 'subscribe' method queue = A2aEventQueue() print(hasattr(queue, 'subscribe')) # False # Bug 5: ServerConnectionConfig rejects 'url' and 'token' try: ServerConnectionConfig(url="https://example.com", token="abc") except Exception as e: print(type(e).__name__) # ValidationError # Bug 6: StubServerClient raises NotImplementedError, not A2aNotAvailableError from cleveragents.a2a.clients import StubServerClient from cleveragents.a2a.errors import A2aNotAvailableError stub = StubServerClient() try: stub.health_check() except NotImplementedError: print("NotImplementedError raised, not A2aNotAvailableError") ``` ### Code Location - Documentation: `docs/api/a2a.md` - Actual implementation: `src/cleveragents/a2a/facade.py`, `src/cleveragents/a2a/models.py`, `src/cleveragents/a2a/events.py`, `src/cleveragents/a2a/server_config.py`, `src/cleveragents/a2a/clients.py` ### Impact Developers following the API documentation will write broken code. The `async def dispatch` signature is particularly dangerous as it will cause silent failures in async contexts. ## Subtasks - [ ] Correct `A2aLocalFacade.dispatch` signature in `docs/api/a2a.md` — remove `async`, mark as synchronous - [ ] Correct `A2aRequest` model fields in `docs/api/a2a.md` — add `a2a_version`, `request_id`, `auth`; remove non-existent `version: A2aVersion.V1` - [ ] Correct `A2aResponse` model fields in `docs/api/a2a.md` — replace `success: bool` with `status: str`; fix `data` type to `dict[str, Any]`; add `timing_ms` - [ ] Correct `A2aEventQueue` API in `docs/api/a2a.md` — remove non-existent `subscribe()` async iterator; document actual `subscribe_local()` and `subscribe_remote()` methods - [ ] Correct `ServerConnectionConfig` constructor args in `docs/api/a2a.md` — rename `url` → `server_url`, `token` → `auth_token_ref` - [ ] Correct stub client exception documentation in `docs/api/a2a.md` — replace `A2aNotAvailableError` with `NotImplementedError` for `StubServerClient`, `StubRemoteExecutionClient`, `StubAuthClient` - [ ] Cross-check all other public symbols in `docs/api/a2a.md` against current implementation to catch any additional drift - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - All six documented API discrepancies in `docs/api/a2a.md` are corrected to match the actual implementation. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`docs(a2a): correct stale API signatures in docs/api/a2a.md`), 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 (`fix/a2a-api-docs-stale-signatures`). - 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

freemo added this to the v3.7.0 milestone

2026-04-02 23:29:38 +00:00

freemo added a new dependency

2026-04-02 23:35:19 +00:00

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

freemo added the

labels

2026-04-02 23:36:27 +00:00

freemo referenced this issue

2026-04-02 23:37:56 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 441 — v3.7.0 #1734

freemo referenced this issue

2026-04-02 23:40:27 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463

freemo commented

2026-04-02 23:47:55 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels based on issue content
Reason: Per CONTRIBUTING.md, every issue must have exactly one State/*, Type/*, and Priority/* label.

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

Label compliance fix applied: - Added missing labels based on issue content - Reason: Per CONTRIBUTING.md, every issue must have exactly one `State/*`, `Type/*`, and `Priority/*` label. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo commented

2026-04-02 23:51:13 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or spec compliance issue.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo removed the

labels

2026-04-02 23:52:11 +00:00

freemo referenced this issue

2026-04-02 23:55:03 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463