[AUTO-BUG-6] a2a/facade: A2aLocalFacade.dispatch() raises A2aOperationNotFoundError instead of returning JSON-RPC 2.0 error response (code -32601) #10376

New issue

Open

opened 2026-04-18 09:16:00 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-18 09:16:00 +00:00

Owner

Metadata

Field	Value
Branch	`fix/a2a-facade-dispatch-operation-not-found`
Commit Message	`fix(a2a/facade): return JSON-RPC 2.0 error response for unknown methods instead of raising A2aOperationNotFoundError`
Milestone	v3.5.0
Parent Epic	—

Background and Context

A2aLocalFacade.dispatch() in src/cleveragents/a2a/facade.py explicitly re-raises A2aOperationNotFoundError when an unknown A2A method is requested, instead of converting it to a structured JSON-RPC 2.0 error response. This breaks the JSON-RPC 2.0 specification contract.

Current Behavior

Code (src/cleveragents/a2a/facade.py, dispatch() method):

def dispatch(self, request: A2aRequest) -> A2aResponse:
    ...
    try:
        data = self._route_operation(request.method, request.params)
        elapsed = (time.monotonic() - start) * 1000.0
        ...
        return A2aResponse(id=request.id, result=data)
    except A2aOperationNotFoundError:
        raise  # ← BUG: re-raises instead of returning error response
    except Exception as exc:
        ...
        return A2aResponse(id=request.id, error=A2aErrorDetail(code=code, message=message))

When dispatch() is called with an unknown method (e.g., "unknown/method"), it raises A2aOperationNotFoundError as an exception. All other errors are caught and returned as A2aResponse with an error field. This inconsistency means callers must handle both exceptions AND error responses, violating the uniform error handling contract.

Expected Behavior

Per JSON-RPC 2.0 specification (Section 5.1), when a method is not found, the server MUST return an error response with code -32601 (Method not found), not raise an exception:

{
  "jsonrpc": "2.0",
  "id": "...",
  "error": {
    "code": -32601,
    "message": "Method not found: unknown/method"
  }
}

The fix is to catch A2aOperationNotFoundError in dispatch() and return it as an A2aResponse with error.code = -32601:

except A2aOperationNotFoundError as exc:
    return A2aResponse(
        id=request.id,
        error=A2aErrorDetail(
            code=-32601,  # JSON-RPC 2.0 Method not found
            message=str(exc),
        ),
    )

Steps to Reproduce

from cleveragents.a2a.facade import A2aLocalFacade
from cleveragents.a2a.models import A2aRequest

facade = A2aLocalFacade()
request = A2aRequest(method="unknown/method", params={})
# This raises A2aOperationNotFoundError instead of returning an error response:
response = facade.dispatch(request)

Impact

Severity: High — breaks the JSON-RPC 2.0 contract
Affected callers: Any code that calls dispatch() and expects a uniform A2aResponse return value
Spec violation: JSON-RPC 2.0 Section 5.1 requires error responses, not exceptions, for method-not-found

Acceptance Criteria

dispatch() catches A2aOperationNotFoundError and returns A2aResponse(error=A2aErrorDetail(code=-32601, ...))
dispatch() never raises A2aOperationNotFoundError to callers
The error code -32601 matches the JSON-RPC 2.0 "Method not found" standard
All existing tests pass
TDD scenario from #10362 passes after the fix

Subtasks

Update dispatch() in src/cleveragents/a2a/facade.py to catch A2aOperationNotFoundError and return an error response with code -32601
Add -32601 as a named constant (e.g., METHOD_NOT_FOUND = -32601) in src/cleveragents/a2a/errors.py
Export the new constant in errors.__all__
Verify TDD scenario from #10362 passes
Run nox -s unit_tests to confirm no regressions
Verify coverage >= 97% via nox -s coverage_report

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 of the commit message matches the Commit Message in Metadata exactly.
The commit is pushed to the remote on the branch fix/a2a-facade-dispatch-operation-not-found.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Blocked by #10362 (TDD counterpart must be merged first)

Automated by CleverAgents Bot
Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

## Metadata | Field | Value | |---|---| | **Branch** | `fix/a2a-facade-dispatch-operation-not-found` | | **Commit Message** | `fix(a2a/facade): return JSON-RPC 2.0 error response for unknown methods instead of raising A2aOperationNotFoundError` | | **Milestone** | v3.5.0 | | **Parent Epic** | — | ## Background and Context `A2aLocalFacade.dispatch()` in `src/cleveragents/a2a/facade.py` explicitly re-raises `A2aOperationNotFoundError` when an unknown A2A method is requested, instead of converting it to a structured JSON-RPC 2.0 error response. This breaks the JSON-RPC 2.0 specification contract. ## Current Behavior **Code** (`src/cleveragents/a2a/facade.py`, `dispatch()` method): ```python def dispatch(self, request: A2aRequest) -> A2aResponse: ... try: data = self._route_operation(request.method, request.params) elapsed = (time.monotonic() - start) * 1000.0 ... return A2aResponse(id=request.id, result=data) except A2aOperationNotFoundError: raise # ← BUG: re-raises instead of returning error response except Exception as exc: ... return A2aResponse(id=request.id, error=A2aErrorDetail(code=code, message=message)) ``` When `dispatch()` is called with an unknown method (e.g., `"unknown/method"`), it raises `A2aOperationNotFoundError` as an exception. All other errors are caught and returned as `A2aResponse` with an `error` field. This inconsistency means callers must handle both exceptions AND error responses, violating the uniform error handling contract. ## Expected Behavior Per JSON-RPC 2.0 specification (Section 5.1), when a method is not found, the server MUST return an error response with code `-32601` (Method not found), not raise an exception: ```json { "jsonrpc": "2.0", "id": "...", "error": { "code": -32601, "message": "Method not found: unknown/method" } } ``` The fix is to catch `A2aOperationNotFoundError` in `dispatch()` and return it as an `A2aResponse` with `error.code = -32601`: ```python except A2aOperationNotFoundError as exc: return A2aResponse( id=request.id, error=A2aErrorDetail( code=-32601, # JSON-RPC 2.0 Method not found message=str(exc), ), ) ``` ## Steps to Reproduce ```python from cleveragents.a2a.facade import A2aLocalFacade from cleveragents.a2a.models import A2aRequest facade = A2aLocalFacade() request = A2aRequest(method="unknown/method", params={}) # This raises A2aOperationNotFoundError instead of returning an error response: response = facade.dispatch(request) ``` ## Impact - **Severity**: High — breaks the JSON-RPC 2.0 contract - **Affected callers**: Any code that calls `dispatch()` and expects a uniform `A2aResponse` return value - **Spec violation**: JSON-RPC 2.0 Section 5.1 requires error responses, not exceptions, for method-not-found ## Acceptance Criteria - [ ] `dispatch()` catches `A2aOperationNotFoundError` and returns `A2aResponse(error=A2aErrorDetail(code=-32601, ...))` - [ ] `dispatch()` never raises `A2aOperationNotFoundError` to callers - [ ] The error code `-32601` matches the JSON-RPC 2.0 "Method not found" standard - [ ] All existing tests pass - [ ] TDD scenario from #10362 passes after the fix ## Subtasks - [ ] Update `dispatch()` in `src/cleveragents/a2a/facade.py` to catch `A2aOperationNotFoundError` and return an error response with code `-32601` - [ ] Add `-32601` as a named constant (e.g., `METHOD_NOT_FOUND = -32601`) in `src/cleveragents/a2a/errors.py` - [ ] Export the new constant in `errors.__all__` - [ ] Verify TDD scenario from #10362 passes - [ ] Run `nox -s unit_tests` to confirm no regressions - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## 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** of the commit message matches the Commit Message in Metadata exactly. - The commit is pushed to the remote on the branch `fix/a2a-facade-dispatch-operation-not-found`. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. **Blocked by #10362** (TDD counterpart must be merged first) --- Automated by CleverAgents Bot Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

HAL9000 added the

labels

2026-04-18 09:17:12 +00:00