Merge branch 'main' into dependabot/maven/no.entur.mapstruct.spi-protobuf-spi-impl-1.53.0

Author: ehsavoie

.claude/architecture/compatibility_0.3.md

@@ -168,6 +168,18 @@ These fields coexist alongside the v1.0 `supportedInterfaces` field. v1.0 client
 
 `Legacy_0_3_AgentInterface` is a separate record from `AgentInterface` because they serialize to different JSON field names (`transport`/`url` vs `protocolBinding`/`url`/`tenant`).
 
+### Version-Aware Push Notifications
+
+Push notification payloads are formatted according to the protocol version used when the push notification configuration was registered. The v0.3 transport handlers pass `A2AProtocol_v0_3.PROTOCOL_VERSION` when constructing the `ServerCallContext`, which propagates through to `PushNotificationConfigStore.setInfo()`. When a notification is later sent:
+
+1. `BasePushNotificationSender` retrieves the protocol version stored alongside each push notification configuration
+2. It looks up a `PushNotificationPayloadFormatter` matching that version (discovered via CDI)
+3. The formatter serializes the payload in the appropriate wire format:
+   - **v0.3** (`PushNotificationPayloadFormatter_v0_3`): sends a v0.3 `Task` JSON object, skipping `Message` events (not supported in v0.3 push notifications)
+   - **v1.0** (default): sends a `StreamResponse` wrapper containing the event
+
+If no protocol version is stored (e.g., for configurations created before this feature), the version defaults to `AgentInterface.CURRENT_PROTOCOL_VERSION` (`"1.0"`).
+
 ---
 
 ## Module Structure
@@ -436,7 +448,7 @@ AgentCard card = // ... fetch agent card from /.well-known/agent-card.json
 
 // Find the v0.3 interface from the agent card
 AgentInterface v03Interface = card.supportedInterfaces().stream()
-        .filter(iface -> "0.3".equals(iface.protocolVersion()))
+        .filter(iface -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(iface.protocolVersion()))
         .findFirst()
         .orElseThrow();
 
@@ -536,10 +548,10 @@ For JSON-RPC and REST, multi-version convenience modules are also available that
 
 ## Status
 
-The v0.3 compatibility layer is fully implemented: spec types, gRPC generation, conversion layer, all three transport handlers (JSON-RPC, gRPC, REST), client API and transports, reference servers, multi-version deployment, test infrastructure, 125+ integration tests, and TCK module are all in place.
+The v0.3 compatibility layer is fully implemented: spec types, gRPC generation, conversion layer, all three transport handlers (JSON-RPC, gRPC, REST), client API and transports, reference servers, multi-version deployment, version-aware push notifications, test infrastructure, 125+ integration tests, and TCK module are all in place.
 
 🔲 **Outstanding:**
-- Push notification test porting (requires TestHttpClient; version-aware push notifications in PR #857)
+- Push notification test porting (requires TestHttpClient)
 - Test metadata classes (classpath scanning)
 - Replace FQNs with imports (97 occurrences in 34 files)
 - Unify AgentCard producers across reference modules

.github/workflows/run-tck.yml

@@ -12,7 +12,7 @@ on:
 env:
   # Tag/branch of the TCK
   TCK_VERSION: 1.0-dev
-  TCK_VERSION_0_3: 0.3.0.beta4
+  TCK_VERSION_0_3: 0.3.x
   # Tells uv to not need a venv, and instead use system
   UV_SYSTEM_PYTHON: 1
   SUT_URL: http://localhost:9999

README.md

@@ -373,6 +373,10 @@ The two interface lists serve different clients:
 - `additionalInterfaces` — used by **v0.3 clients** to discover endpoints (uses `Legacy_0_3_AgentInterface` with v0.3 field names: `transport`/`url`)
 - `url` and `preferredTransport` — top-level fields that v0.3 clients use to discover the primary endpoint
 
+#### Push Notification Behavior
+
+Push notification payloads are automatically formatted to match the protocol version used when the push notification configuration was registered. When a v0.3 client registers a push notification configuration (via any transport), the server records the protocol version alongside the configuration. When a notification is later sent to that webhook, the payload is formatted as a v0.3 Task object. Configurations registered by v1.0 clients receive v1.0 `StreamResponse` payloads as usual. This happens transparently — no additional configuration is needed beyond adding the compat reference module.
+
 ## A2A Client
 
 The A2A Java SDK provides a Java client implementation of the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/), allowing communication with A2A servers. The Java client implementation supports the following transports:
@@ -776,7 +780,7 @@ AgentCard card = new A2ACardResolver("http://localhost:1234").getAgentCard();
 
 // Find the v0.3 interface from the agent card
 AgentInterface v03Interface = card.supportedInterfaces().stream()
-        .filter(iface -> "0.3".equals(iface.protocolVersion()))
+        .filter(iface -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(iface.protocolVersion()))
         .findFirst()
         .orElseThrow();
 

boms/extras/pom.xml

@@ -102,7 +102,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-invoker-plugin</artifactId>
-                <version>3.10.0</version>
+                <version>3.10.1</version>
                 <configuration>
                     <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
                     <localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>

boms/reference/pom.xml

@@ -112,7 +112,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-invoker-plugin</artifactId>
-                <version>3.10.0</version>
+                <version>3.10.1</version>
                 <configuration>
                     <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
                     <localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>

boms/sdk/pom.xml

@@ -291,7 +291,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-invoker-plugin</artifactId>
-                <version>3.10.0</version>
+                <version>3.10.1</version>
                 <configuration>
                     <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
                     <localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>

compat-0.3/reference/jsonrpc/src/main/java/org/a2aproject/sdk/compat03/server/apps/quarkus/A2AServerRoutes_v0_3.java

@@ -33,6 +33,7 @@
 import io.vertx.ext.web.RoutingContext;
 import io.vertx.ext.web.handler.BodyHandler;
 import org.a2aproject.sdk.compat03.common.A2AHeaders_v0_3;
+import org.a2aproject.sdk.compat03.conversion.A2AProtocol_v0_3;
 import org.a2aproject.sdk.compat03.json.JsonProcessingException_v0_3;
 import org.a2aproject.sdk.compat03.json.JsonUtil_v0_3;
 import org.a2aproject.sdk.compat03.spec.AgentCard_v0_3;
@@ -327,7 +328,7 @@ public String getUsername() {
             List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders_v0_3.X_A2A_EXTENSIONS);
             Set<String> requestedExtensions = A2AExtensions.getRequestedExtensions(extensionHeaderValues);
 
-            return new ServerCallContext(user, state, requestedExtensions);
+            return new ServerCallContext(user, state, requestedExtensions, A2AProtocol_v0_3.PROTOCOL_VERSION);
         } else {
             CallContextFactory_v0_3 builder = callContextFactory.get();
             return builder.build(rc);

compat-0.3/reference/jsonrpc/src/main/java/org/a2aproject/sdk/compat03/server/apps/quarkus/CallContextFactory_v0_3.java

@@ -3,6 +3,13 @@
 import org.a2aproject.sdk.server.ServerCallContext;
 import io.vertx.ext.web.RoutingContext;
 
+/**
+ * Factory interface for creating ServerCallContext from a Vert.x RoutingContext.
+ *
+ * <p>Implementations MUST pass {@link org.a2aproject.sdk.compat03.conversion.A2AProtocol_v0_3#PROTOCOL_VERSION}
+ * as the protocol version when constructing {@link ServerCallContext} so that push notification
+ * payloads are formatted correctly.</p>
+ */
 public interface CallContextFactory_v0_3 {
     ServerCallContext build(RoutingContext rc);
 }

compat-0.3/reference/rest/src/main/java/org/a2aproject/sdk/compat03/server/rest/quarkus/A2AServerRoutes_v0_3.java

@@ -33,6 +33,7 @@
 import io.vertx.ext.web.RoutingContext;
 import io.vertx.ext.web.handler.BodyHandler;
 import org.a2aproject.sdk.compat03.common.A2AHeaders_v0_3;
+import org.a2aproject.sdk.compat03.conversion.A2AProtocol_v0_3;
 import org.a2aproject.sdk.compat03.spec.CancelTaskRequest_v0_3;
 import org.a2aproject.sdk.compat03.spec.DeleteTaskPushNotificationConfigRequest_v0_3;
 import org.a2aproject.sdk.compat03.spec.GetTaskPushNotificationConfigRequest_v0_3;
@@ -431,7 +432,7 @@ public String getUsername() {
             List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders_v0_3.X_A2A_EXTENSIONS);
             Set<String> requestedExtensions = A2AExtensions.getRequestedExtensions(extensionHeaderValues);
 
-            return new ServerCallContext(user, state, requestedExtensions);
+            return new ServerCallContext(user, state, requestedExtensions, A2AProtocol_v0_3.PROTOCOL_VERSION);
         } else {
             CallContextFactory_v0_3 builder = callContextFactory.get();
             return builder.build(rc);

compat-0.3/reference/rest/src/main/java/org/a2aproject/sdk/compat03/server/rest/quarkus/CallContextFactory_v0_3.java

@@ -3,6 +3,13 @@
 import org.a2aproject.sdk.server.ServerCallContext;
 import io.vertx.ext.web.RoutingContext;
 
+/**
+ * Factory interface for creating ServerCallContext from a Vert.x RoutingContext.
+ *
+ * <p>Implementations MUST pass {@link org.a2aproject.sdk.compat03.conversion.A2AProtocol_v0_3#PROTOCOL_VERSION}
+ * as the protocol version when constructing {@link ServerCallContext} so that push notification
+ * payloads are formatted correctly.</p>
+ */
 public interface CallContextFactory_v0_3 {
     ServerCallContext build(RoutingContext rc);
 }