fix(server): resolve lint, type, and spelling errors in route helpers

Author: martimfasantos

.github/actions/spelling/allow.txt

@@ -20,6 +20,7 @@ amannn
 aproject
 ARequest
 ARun
+ARoute
 AServer
 AServers
 AService
@@ -94,6 +95,8 @@ notif
 npx
 oauthoidc
 oidc
+oneof
+oneofs
 Oneof
 OpenAPI
 openapiv
@@ -112,6 +115,7 @@ proto
 protobuf
 Protobuf
 protoc
+protojson
 pydantic
 pyi
 pypistats
@@ -125,6 +129,7 @@ rmi
 RS256
 RUF
 SECP256R1
+SFIXED
 SLF
 socio
 sse

CLAUDE.md

@@ -0,0 +1,5 @@
+# Claude Code Guidelines
+
+## Commits
+
+- Never include `Co-Authored-By: Claude` or any AI attribution in commit messages.

src/a2a/server/routes/helpers/__init__.py

@@ -1,5 +1,6 @@
 from a2a.server.routes.helpers.fastapi import add_a2a_routes_to_fastapi
 
+
 __all__ = [
     'add_a2a_routes_to_fastapi',
 ]

src/a2a/server/routes/helpers/_proto_schema.py

@@ -3,14 +3,15 @@
 from typing import Any
 
 from google.protobuf.descriptor import Descriptor, FieldDescriptor
+from google.protobuf.message import Message
 
 from a2a.types.a2a_pb2 import (
     SendMessageRequest,
     TaskPushNotificationConfig,
 )
 
 
-REST_BODY_TYPES: dict[tuple[str, str], type] = {
+REST_BODY_TYPES: dict[tuple[str, str], type[Message]] = {
     ('/message:send', 'POST'): SendMessageRequest,
     ('/message:stream', 'POST'): SendMessageRequest,
     ('/tasks/{id}/pushNotificationConfigs', 'POST'): TaskPushNotificationConfig,
@@ -73,7 +74,7 @@ def field_schema(
 
 
 def message_schema(
-    descriptor: Descriptor, components: dict[str, Any]
+    descriptor: Descriptor | Any, components: dict[str, Any]
 ) -> dict[str, Any]:
     """Returns a $ref to descriptor's schema, registering it in components if needed."""
     if descriptor.full_name in _WELL_KNOWN_SCHEMAS:

src/a2a/server/routes/helpers/fastapi.py

@@ -1,15 +1,21 @@
 from typing import TYPE_CHECKING, Any
 
-from a2a.server.routes.helpers._proto_schema import (REST_BODY_TYPES,
-                                                     message_schema)
-from a2a.server.routes.helpers.jsonrpc import \
-    DESCRIPTION as _JSONRPC_DESCRIPTION
-from a2a.server.routes.helpers.jsonrpc import \
-    envelope_schema as _jsonrpc_envelope_schema
+from a2a.server.routes.helpers._proto_schema import (
+    REST_BODY_TYPES,
+    message_schema,
+)
+from a2a.server.routes.helpers.jsonrpc import (
+    DESCRIPTION as _JSONRPC_DESCRIPTION,
+)
+from a2a.server.routes.helpers.jsonrpc import (
+    envelope_schema as _jsonrpc_envelope_schema,
+)
 from a2a.utils.constants import PROTOCOL_VERSION_1_0, VERSION_HEADER
 
+
 if TYPE_CHECKING:
     from fastapi import FastAPI
+    from fastapi.routing import APIRoute as _A2ARoute
     from starlette.routing import BaseRoute, Route
 
     _package_fastapi_installed = True
@@ -169,14 +175,26 @@ def add_a2a_routes_to_fastapi(
 
     for route in jsonrpc_routes or ():
         extra = jsonrpc_extra if isinstance(route, Route) else None
-        _attach_route(app, route, _JSONRPC_TAG, openapi_extra=extra, require_version_header=True)
+        _attach_route(
+            app,
+            route,
+            _JSONRPC_TAG,
+            openapi_extra=extra,
+            require_version_header=True,
+        )
 
     for route in rest_routes or ():
         extra = (
             _rest_body_extra(route, rest_extras)
             if isinstance(route, Route)
             else None
         )
-        _attach_route(app, route, _REST_TAG, openapi_extra=extra, require_version_header=True)
+        _attach_route(
+            app,
+            route,
+            _REST_TAG,
+            openapi_extra=extra,
+            require_version_header=True,
+        )
 
     _install_components(app, components)

src/a2a/server/routes/helpers/jsonrpc.py

@@ -2,6 +2,8 @@
 
 from typing import Any
 
+from google.protobuf.message import Message
+
 from a2a.server.routes.helpers._proto_schema import message_schema
 from a2a.types.a2a_pb2 import (
     CancelTaskRequest,
@@ -17,7 +19,7 @@
 )
 
 
-METHOD_TYPES: dict[str, type] = {
+METHOD_TYPES: dict[str, type[Message]] = {
     'SendMessage': SendMessageRequest,
     'SendStreamingMessage': SendMessageRequest,
     'GetTask': GetTaskRequest,

tests/server/routes/helpers/test_fastapi.py

@@ -70,9 +70,7 @@ def test_routes_dispatch_under_fastapi(
     app = _build_app(agent_card, mock_handler)
     client = TestClient(app)
 
-    assert (
-        client.get(AGENT_CARD_WELL_KNOWN_PATH).json()['name'] == 'Test Agent'
-    )
+    assert client.get(AGENT_CARD_WELL_KNOWN_PATH).json()['name'] == 'Test Agent'
     rpc_response = client.post(
         '/', json={'jsonrpc': '2.0', 'id': '1', 'method': 'NoSuchMethod'}
     ).json()
@@ -155,7 +153,10 @@ def test_routes_without_body_have_no_request_body(
     assert 'requestBody' not in paths[AGENT_CARD_WELL_KNOWN_PATH]['get']
     assert 'requestBody' not in paths['/tasks']['get']
     assert 'requestBody' not in paths['/tasks/{id}:cancel']['post']
-    assert 'requestBody' not in paths['/tasks/{id}/pushNotificationConfigs/{push_id}']['delete']
+    assert (
+        'requestBody'
+        not in paths['/tasks/{id}/pushNotificationConfigs/{push_id}']['delete']
+    )
 
 
 def test_a2a_version_header_on_dispatcher_routes(
@@ -167,8 +168,7 @@ def test_a2a_version_header_on_dispatcher_routes(
 
     def _has_version_header(op: dict) -> bool:
         return any(
-            p.get('name') == VERSION_HEADER
-            for p in op.get('parameters', [])
+            p.get('name') == VERSION_HEADER for p in op.get('parameters', [])
         )
 
     assert _has_version_header(paths['/']['post'])

tests/server/routes/helpers/test_jsonrpc.py

@@ -36,7 +36,10 @@ def test_envelope_schema_deduplicates_shared_param_types():
     # SendMessage and SendStreamingMessage share SendMessageRequest.
     components = {}
     envelope_schema(components)
-    refs = [r['$ref'] for r in components['A2ARequest']['properties']['params']['oneOf']]
+    refs = [
+        r['$ref']
+        for r in components['A2ARequest']['properties']['params']['oneOf']
+    ]
     assert len(refs) == len(set(refs))
 
 

tests/server/routes/helpers/test_proto_schema.py

@@ -29,7 +29,10 @@ def test_message_schema_recurses_into_nested_types():
 
 def test_message_schema_well_known_type_inline():
     from google.protobuf.descriptor_pool import Default
-    struct_descriptor = Default().FindMessageTypeByName('google.protobuf.Struct')
+
+    struct_descriptor = Default().FindMessageTypeByName(
+        'google.protobuf.Struct'
+    )
     components = {}
     schema = message_schema(struct_descriptor, components)
     assert schema == {'type': 'object'}
@@ -54,7 +57,9 @@ def test_message_schema_oneof_variants_have_required():
 
 def test_field_schema_repeated_wraps_in_array():
     components = {}
-    msg_descriptor = SendMessageRequest.DESCRIPTOR.fields_by_name['message'].message_type
+    msg_descriptor = SendMessageRequest.DESCRIPTOR.fields_by_name[
+        'message'
+    ].message_type
     parts_field = msg_descriptor.fields_by_name['parts']
     schema = field_schema(parts_field, components)
     assert schema['type'] == 'array'