Merge remote-tracking branch 'refs/remotes/origin/guglielmoc/refactor_json_rpc_server' into guglielmoc/refactor_json_rpc_server

Author: guglielmo-san

.github/actions/spelling/allow.txt

@@ -35,6 +35,7 @@ cls
 coc
 codegen
 coro
+culsans
 datamodel
 deepwiki
 drivername
@@ -127,7 +128,7 @@ taskupdate
 testuuid
 Tful
 tiangolo
+TResponse
 typ
 typeerror
 vulnz
-TResponse

AGENTS.md

@@ -0,0 +1,3 @@
+Always check @./GEMINI.md for the full instruction list.
+
+This file exists for compatibility with tools that look for AGENTS.md.

GEMINI.md

@@ -1,20 +1,25 @@
-**A2A specification:** https://a2a-protocol.org/latest/specification/
+# Agent Command Center
 
-## Project frameworks
-- uv as package manager
+## 1. Project Overview & Purpose
+**Primary Goal**: This is the Python SDK for the Agent2Agent (A2A) Protocol. It allows developers to build and run agentic applications as A2A-compliant servers. It handles complex messaging, task management, and communication across different transports (REST, gRPC, JSON-RPC).
+**Specification**: [A2A-Protocol](https://a2a-protocol.org/latest/specification/)
 
-## Code style and mandatory checks
-1. Whenever writing python code, write types as well.
-2. After making the changes run ruff to check and fix the formatting issues
-   ```
-   uv run ruff check --fix
-   uv run ruff format
-   ```
-3. Run mypy type checkers to check for type errors
-   ```
-   uv run mypy src
-   ```
-4. Run the unit tests to make sure that none of the unit tests are broken.
-  ```
-  uv run pytest
-  ```
+## 2. Technology Stack & Architecture
+
+- **Language**: Python 3.10+
+- **Package Manager**: `uv`
+- **Lead Transports**: FastAPI (REST/JSON-RPC), gRPC
+- **Data Layer**: SQLAlchemy (SQL), Pydantic (Logic/Legacy), Protobuf (Modern Messaging)
+- **Key Directories**:
+    - `/src`: Core implementation logic.
+    - `/tests`: Comprehensive test suite.
+    - `/docs`: AI guides.
+
+## 3. Style Guidelines & Mandatory Checks
+- **Style Guidelines**: Follow the rules in @./docs/ai/coding_conventions.md for every response involving code.
+- **Mandatory Checks**: Run the commands in @./docs/ai/mandatory_checks.md after making any changes to the code and before committing.
+
+## 4. Mandatory AI Workflow for Coding Tasks
+1. **Required Reading**: You MUST read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task.
+2. **Initial Checklist**: Every `task.md` you create MUST include a section for **Mandatory Checks** from @./docs/ai/mandatory_checks.md.
+3. **Verification Requirement**: You MUST run all mandatory checks before declaring any task finished.

README.md

@@ -36,7 +36,10 @@
 
 ## 🧩 Compatibility
 
-This SDK implements the A2A Protocol Specification [`v0.3.0`](https://a2a-protocol.org/v0.3.0/specification).
+This SDK implements the A2A Protocol Specification [`0.3`](https://a2a-protocol.org/v0.3.0/specification).
+
+> [!IMPORTANT]
+> There is an [**alpha version**](https://github.com/a2aproject/a2a-python/releases?q=%22v1.0.0-alpha%22&expanded=true) available with support for both [`1.0`](https://a2a-protocol.org/v1.0.0/specification/) and [`0.3`](https://a2a-protocol.org/v0.3.0/specification) versions. Development for this version is taking place in the [`1.0-dev`](https://github.com/a2aproject/a2a-python/tree/1.0-dev) branch, tracked in [#701](https://github.com/a2aproject/a2a-python/issues/701).
 
 | Transport | Client | Server |
 | :--- | :---: | :---: |
@@ -65,6 +68,7 @@ Install the core SDK and any desired extras using your preferred package manager
 | **gRPC Support**         | `uv add "a2a-sdk[grpc]"`                   | `pip install "a2a-sdk[grpc]"`                |
 | **OpenTelemetry Tracing**| `uv add "a2a-sdk[telemetry]"`              | `pip install "a2a-sdk[telemetry]"`           |
 | **Encryption**           | `uv add "a2a-sdk[encryption]"`             | `pip install "a2a-sdk[encryption]"`          |
+| **Vertex AI Task Store** | `uv add "a2a-sdk[vertex]"`                 | `pip install "a2a-sdk[vertex]"`              |
 |                          |                                            |                                              |
 | **Database Drivers**     |                                            |                                              |
 | **PostgreSQL**           | `uv add "a2a-sdk[postgresql]"`             | `pip install "a2a-sdk[postgresql]"`          |

docs/ai/coding_conventions.md

@@ -0,0 +1,21 @@
+### Coding Conventions & Style Guide
+
+Non-negotiable rules for code quality and style.
+
+1. **Python Types**: All Python code MUST include type hints. All function definitions MUST include return types.
+2. **Type Safety**: All code MUST pass `mypy` and `pyright` checks.
+3. **Formatting & Linting**: All code MUST be formatted with `ruff`.
+
+#### Examples:
+
+**Correct Typing:**
+```python
+async def get_task_status(task: Task) -> TaskStatus:
+    return task.status
+```
+
+**Incorrect (Do NOT do this):**
+```python
+async def get_task_status(task): # Missing type hints for argument and return value
+    return task.status
+```

docs/ai/mandatory_checks.md

@@ -0,0 +1,26 @@
+### Test and Fix Commands
+
+Exact shell commands required to test the project and fix formatting issues.
+
+1. **Formatting & Linting**:
+   ```bash
+   uv run ruff check --fix
+   uv run ruff format
+   ```
+
+2. **Type Checking**:
+   ```bash
+   uv run mypy src
+   uv run pyright src
+   ```
+
+3. **Testing**:
+   ```bash
+   uv run pytest
+   ```
+
+4. **Coverage**:
+Only run this command after adding new source code and before committing.
+   ```bash
+   uv run pytest --cov=src --cov-report=term-missing
+   ```

pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
   "google-api-core>=1.26.0",
   "json-rpc>=1.15.0",
   "googleapis-common-protos>=1.70.0",
+  "culsans>=0.11.0 ; python_full_version < '3.13'",
 ]
 
 classifiers = [

src/a2a/client/transports/http_helpers.py

@@ -78,7 +78,22 @@ async def send_http_stream_request(
         async with aconnect_sse(
             httpx_client, method, url, **kwargs
         ) as event_source:
-            event_source.response.raise_for_status()
+            try:
+                event_source.response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                # Read upfront streaming error content immediately, otherwise lower-level handlers
+                # (e.g. response.json()) crash with 'ResponseNotRead' Access errors.
+                await event_source.response.aread()
+                raise e
+
+            # If the response is not a stream, read it standardly (e.g., upfront JSON-RPC error payload)
+            if 'text/event-stream' not in event_source.response.headers.get(
+                'content-type', ''
+            ):
+                content = await event_source.response.aread()
+                yield content.decode('utf-8')
+                return
+
             async for sse in event_source.aiter_sse():
                 if not sse.data:
                     continue

src/a2a/compat/v0_3/grpc_handler.py

@@ -29,7 +29,7 @@
 from a2a.server.request_handlers.request_handler import RequestHandler
 from a2a.types.a2a_pb2 import AgentCard
 from a2a.utils.errors import A2AError, InvalidParamsError
-from a2a.utils.helpers import maybe_await, validate, validate_async_generator
+from a2a.utils.helpers import maybe_await, validate
 
 
 logger = logging.getLogger(__name__)
@@ -170,17 +170,17 @@ async def _handler(
             context, _handler, a2a_v0_3_pb2.SendMessageResponse()
         )
 
-    @validate_async_generator(
-        lambda self: self.agent_card.capabilities.streaming,
-        'Streaming is not supported by the agent',
-    )
     async def SendStreamingMessage(
         self,
         request: a2a_v0_3_pb2.SendMessageRequest,
         context: grpc.aio.ServicerContext,
     ) -> AsyncIterable[a2a_v0_3_pb2.StreamResponse]:
         """Handles the 'SendStreamingMessage' gRPC method (v0.3)."""
 
+        @validate(
+            lambda _: self.agent_card.capabilities.streaming,
+            'Streaming is not supported by the agent',
+        )
         async def _handler(
             server_context: ServerCallContext,
         ) -> AsyncIterable[a2a_v0_3_pb2.StreamResponse]:
@@ -233,17 +233,17 @@ async def _handler(
 
         return await self._handle_unary(context, _handler, a2a_v0_3_pb2.Task())
 
-    @validate_async_generator(
-        lambda self: self.agent_card.capabilities.streaming,
-        'Streaming is not supported by the agent',
-    )
     async def TaskSubscription(
         self,
         request: a2a_v0_3_pb2.TaskSubscriptionRequest,
         context: grpc.aio.ServicerContext,
     ) -> AsyncIterable[a2a_v0_3_pb2.StreamResponse]:
         """Handles the 'TaskSubscription' gRPC method (v0.3)."""
 
+        @validate(
+            lambda _: self.agent_card.capabilities.streaming,
+            'Streaming is not supported by the agent',
+        )
         async def _handler(
             server_context: ServerCallContext,
         ) -> AsyncIterable[a2a_v0_3_pb2.StreamResponse]:
@@ -260,17 +260,17 @@ async def _handler(
         async for item in self._handle_stream(context, _handler):
             yield item
 
-    @validate(
-        lambda self: self.agent_card.capabilities.push_notifications,
-        'Push notifications are not supported by the agent',
-    )
     async def CreateTaskPushNotificationConfig(
         self,
         request: a2a_v0_3_pb2.CreateTaskPushNotificationConfigRequest,
         context: grpc.aio.ServicerContext,
     ) -> a2a_v0_3_pb2.TaskPushNotificationConfig:
         """Handles the 'CreateTaskPushNotificationConfig' gRPC method (v0.3)."""
 
+        @validate(
+            lambda _: self.agent_card.capabilities.push_notifications,
+            'Push notifications are not supported by the agent',
+        )
         async def _handler(
             server_context: ServerCallContext,
         ) -> a2a_v0_3_pb2.TaskPushNotificationConfig:

src/a2a/compat/v0_3/rest_handler.py

@@ -31,7 +31,6 @@
 from a2a.utils import constants
 from a2a.utils.helpers import (
     validate,
-    validate_async_generator,
     validate_version,
 )
 from a2a.utils.telemetry import SpanKind, trace_class
@@ -85,7 +84,7 @@ async def on_message_send(
         return MessageToDict(pb2_v03_resp)
 
     @validate_version(constants.PROTOCOL_VERSION_0_3)
-    @validate_async_generator(
+    @validate(
         lambda self: self.agent_card.capabilities.streaming,
         'Streaming is not supported by the agent',
     )
@@ -143,7 +142,7 @@ async def on_cancel_task(
         return MessageToDict(pb2_v03_task)
 
     @validate_version(constants.PROTOCOL_VERSION_0_3)
-    @validate_async_generator(
+    @validate(
         lambda self: self.agent_card.capabilities.streaming,
         'Streaming is not supported by the agent',
     )