Merge branch 'main' into issue_698

Author: ehsavoie

AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md
+
+## Project Overview
+
+Java SDK for the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/). Multi-module Maven project (`io.github.a2asdk` group) providing client and server libraries for A2A agent communication over JSON-RPC, gRPC, and REST transports.
+
+## Build
+
+Requires Java 17+.
+Tests output is redirected to files by default.
+
+```bash
+mvn clean install
+```
+
+
+## Project Structure
+
+- `spec/` — A2A specification types (Java POJOs for the protocol)
+- `spec-grpc/` — gRPC protobuf definitions and generated classes
+- `common/` — Shared utilities used across modules
+- `client/` — Client SDK
+  - `base/` — Core client API
+  - `transport/spi/` — Transport SPI
+  - `transport/jsonrpc/`, `transport/grpc/`, `transport/rest/` — Transport implementations
+- `server-common/` — Server-side core (AgentExecutor, TaskStore, QueueManager)
+- `transport/` — Server transport layer (jsonrpc, grpc, rest)
+- `http-client/` — HTTP client abstraction
+- `jsonrpc-common/` — Shared JSON-RPC utilities
+- `reference/` — Reference server implementations built on Quarkus
+  - `common/`, `jsonrpc/`, `grpc/`, `rest/`
+- `tck/` — Technology Compatibility Kit (protocol conformance tests)
+- `tests/` — Integration tests
+- `extras/` — Optional add-ons (OpenTelemetry, JPA task/notification stores, replicated queue manager, Vert.x HTTP client)
+- `integrations/` — Runtime integrations (e.g., MicroProfile Config)
+- `boms/` — Bill of Materials POMs (sdk, extras, reference, test-utils)
+- `examples/` — Sample applications (helloworld, cloud-deployment)
+
+## Key Conventions
+
+- Package root: `io.a2a`
+- Serialization: Gson (see `gson.version` in parent POM)
+- Null safety: NullAway + JSpecify annotations enforced via Error Prone
+- Reference server runtime: Quarkus
+- Testing: JUnit 5, Mockito, REST Assured, Testcontainers
+
+### Code Style
+
+- Import statements are sorted
+- Remove any unused import statements
+- Do not use "star" imports (eg `import java.util.*`)
+- Use Java `record` for immutable data types
+- Use `@Nullable` (from org.jspecify.annotations) for optional fields
+- Use `io.a2a.util.Assert.checkNotNullParam()` in the compact constructor to validate required fields
+- Use `List.copyOf()` and `Map.copyOf()` for defensive copying of collections
+- Apply the Builder pattern for records with many fields (see `AgentCard.java` as reference)
+
+### Code generation
+
+- Be concise
+- Try to use existing code instead of generating new similar code
+- Use the same code convention than existing code. If the existing convention seems incorrect, make suggestion before doing any changes
+
+### PR instructions
+- Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for the commit title and message
+- Always ask if the commit is related to a GitHub issue. If that's the case, add a `This fixes #{issue_number}` at the end of the commit message
+
+### Skills
+
+- [update-a2a-proto](skills/update-a2a-proto/SKILL.md) — Update the gRPC proto file `a2a.proto` from upstream and regenerate Java sources
+
+### Commands
+
+- `mvn clean install` — Clean build of the project
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Fork the repo, create a branch per issue, submit PRs against `main`.

client/base/src/main/java/io/a2a/client/AbstractClient.java

@@ -19,7 +19,6 @@
 import io.a2a.spec.ListTasksParams;
 import io.a2a.spec.Message;
 import io.a2a.spec.MessageSendParams;
-import io.a2a.spec.PushNotificationConfig;
 import io.a2a.spec.Task;
 import io.a2a.spec.TaskIdParams;
 import io.a2a.spec.TaskPushNotificationConfig;
@@ -137,7 +136,7 @@ public abstract void sendMessage(@NonNull Message request,
      * @throws A2AClientException if sending the message fails for any reason
      */
     public void sendMessage(@NonNull Message request,
-                            @Nullable PushNotificationConfig pushNotificationConfiguration,
+                            @Nullable TaskPushNotificationConfig pushNotificationConfiguration,
                             @Nullable Map<String, Object> metadata) throws A2AClientException {
         sendMessage(request, pushNotificationConfiguration, metadata, null);
     }
@@ -158,7 +157,7 @@ public void sendMessage(@NonNull Message request,
      * @throws A2AClientException if sending the message fails for any reason
      */
     public abstract void sendMessage(@NonNull Message request,
-                                     @Nullable PushNotificationConfig pushNotificationConfiguration,
+                                     @Nullable TaskPushNotificationConfig pushNotificationConfiguration,
                                      @Nullable Map<String, Object> metadata,
                                      @Nullable ClientCallContext context) throws A2AClientException;
 

client/base/src/main/java/io/a2a/client/Client.java

@@ -26,7 +26,6 @@
 import io.a2a.spec.Message;
 import io.a2a.spec.MessageSendConfiguration;
 import io.a2a.spec.MessageSendParams;
-import io.a2a.spec.PushNotificationConfig;
 import io.a2a.spec.StreamingEventKind;
 import io.a2a.spec.Task;
 import io.a2a.spec.TaskArtifactUpdateEvent;
@@ -132,10 +131,11 @@
  * <b>Push notifications:</b> Configure webhooks to receive task updates:
  * <pre>{@code
  * // Configure push notifications for a task
- * PushNotificationConfig pushConfig = new PushNotificationConfig(
- *     "https://my-app.com/webhooks/task-updates",
- *     Map.of("Authorization", "Bearer my-token")
- * );
+ * TaskPushNotificationConfig pushConfig = TaskPushNotificationConfig.builder()
+ *     .id("config-1")
+ *     .url("https://my-app.com/webhooks/task-updates")
+ *     .authentication(new AuthenticationInfo("Bearer", "my-token"))
+ *     .build();
  *
  * // Send message with push notifications
  * client.sendMessage(
@@ -236,7 +236,7 @@ public void sendMessage(@NonNull Message request,
                             @NonNull List<BiConsumer<ClientEvent, AgentCard>> consumers,
                             @Nullable Consumer<Throwable> streamingErrorHandler,
                             @Nullable ClientCallContext context) throws A2AClientException {
-        MessageSendConfiguration messageSendConfiguration = createMessageSendConfiguration(clientConfig.getPushNotificationConfig());
+        MessageSendConfiguration messageSendConfiguration = createMessageSendConfiguration(clientConfig.getTaskPushNotificationConfig());
 
         MessageSendParams messageSendParams = MessageSendParams.builder()
                 .message(request)
@@ -267,10 +267,11 @@ public void sendMessage(@NonNull Message request,
      * <p>
      * <b>With push notifications:</b>
      * <pre>{@code
-     * PushNotificationConfig pushConfig = new PushNotificationConfig(
-     *     "https://my-app.com/webhook",
-     *     Map.of("Authorization", "Bearer token")
-     * );
+     * TaskPushNotificationConfig pushConfig = TaskPushNotificationConfig.builder()
+     *     .id("config-1")
+     *     .url("https://my-app.com/webhook")
+     *     .authentication(new AuthenticationInfo("Bearer", "token"))
+     *     .build();
      * client.sendMessage(userMessage, pushConfig, null, null);
      * }</pre>
      * <p>
@@ -289,11 +290,11 @@ public void sendMessage(@NonNull Message request,
      * @param context custom call context for request interceptors (optional)
      * @throws A2AClientException if the message cannot be sent or if the agent returns an error
      * @see #sendMessage(Message, List, Consumer, ClientCallContext)
-     * @see PushNotificationConfig
+     * @see TaskPushNotificationConfig
      */
     @Override
     public void sendMessage(@NonNull Message request,
-                            @Nullable PushNotificationConfig pushNotificationConfiguration,
+                            @Nullable TaskPushNotificationConfig pushNotificationConfiguration,
                             @Nullable Map<String, Object> metadata,
                             @Nullable ClientCallContext context) throws A2AClientException {
         MessageSendConfiguration messageSendConfiguration = createMessageSendConfiguration(pushNotificationConfiguration);
@@ -459,16 +460,12 @@ public Task cancelTask(CancelTaskParams request, @Nullable ClientCallContext con
      * <p>
      * Example:
      * <pre>{@code
-     * TaskPushNotificationConfig config = new TaskPushNotificationConfig(
-     *     "task-123",
-     *     new PushNotificationConfig(
-     *         "https://my-app.com/webhooks/task-updates",
-     *         Map.of(
-     *             "Authorization", "Bearer my-webhook-secret",
-     *             "X-App-ID", "my-app"
-     *         )
-     *     )
-     * );
+     * TaskPushNotificationConfig config = TaskPushNotificationConfig.builder()
+     *     .id("config-1")
+     *     .taskId("task-123")
+     *     .url("https://my-app.com/webhooks/task-updates")
+     *     .authentication(new AuthenticationInfo("Bearer", "my-webhook-secret"))
+     *     .build();
      * client.createTaskPushNotificationConfiguration(config);
      * }</pre>
      *
@@ -477,7 +474,6 @@ public Task cancelTask(CancelTaskParams request, @Nullable ClientCallContext con
      * @return the stored configuration (may include server-assigned IDs)
      * @throws A2AClientException if the configuration cannot be set
      * @see TaskPushNotificationConfig
-     * @see PushNotificationConfig
      */
     @Override
     public TaskPushNotificationConfig createTaskPushNotificationConfiguration(
@@ -495,7 +491,7 @@ public TaskPushNotificationConfig createTaskPushNotificationConfiguration(
      * TaskPushNotificationConfig config =
      *     client.getTaskPushNotificationConfiguration(params);
      * System.out.println("Webhook URL: " +
-     *     config.pushNotificationConfig().url());
+     *     config.url());
      * }</pre>
      *
      * @param request the parameters specifying which task's configuration to retrieve
@@ -522,7 +518,7 @@ public TaskPushNotificationConfig getTaskPushNotificationConfiguration(
      *     client.listTaskPushNotificationConfigurations(params);
      * for (TaskPushNotificationConfig config : result.configurations()) {
      *     System.out.println("Task " + config.taskId() + " -> " +
-     *         config.pushNotificationConfig().url());
+     *         config.url());
      * }
      * }</pre>
      *
@@ -697,12 +693,12 @@ private ClientEvent getClientEvent(StreamingEventKind event, ClientTaskManager t
         }
     }
 
-    private MessageSendConfiguration createMessageSendConfiguration(@Nullable PushNotificationConfig pushNotificationConfig) {
+    private MessageSendConfiguration createMessageSendConfiguration(@Nullable TaskPushNotificationConfig taskPushNotificationConfig) {
         return MessageSendConfiguration.builder()
                 .acceptedOutputModes(clientConfig.getAcceptedOutputModes())
                 .blocking(!clientConfig.isPolling())
                 .historyLength(clientConfig.getHistoryLength())
-                .pushNotificationConfig(pushNotificationConfig)
+                .taskPushNotificationConfig(taskPushNotificationConfig)
                 .build();
     }
 

client/base/src/main/java/io/a2a/client/config/ClientConfig.java

@@ -5,7 +5,7 @@
 import java.util.List;
 import java.util.Map;
 
-import io.a2a.spec.PushNotificationConfig;
+import io.a2a.spec.TaskPushNotificationConfig;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -79,12 +79,13 @@
  * <p>
  * <b>Push notifications:</b> Configure default webhook for all task updates:
  * <pre>{@code
- * PushNotificationConfig pushConfig = new PushNotificationConfig(
- *     "https://my-app.com/webhooks/tasks",
- *     Map.of("Authorization", "Bearer my-token")
- * );
+ * TaskPushNotificationConfig pushConfig = TaskPushNotificationConfig.builder()
+ *     .id("config-1")
+ *     .url("https://my-app.com/webhooks/tasks")
+ *     .authentication(new AuthenticationInfo("bearer", "my-token"))
+ *     .build();
  * ClientConfig config = new ClientConfig.Builder()
- *     .setPushNotificationConfig(pushConfig)
+ *     .setTaskPushNotificationConfig(pushConfig)
  *     .build();
  * // All sendMessage() calls will use this webhook config
  * }</pre>
@@ -125,7 +126,7 @@
  *   <li>useClientPreference: {@code false} (server preference)</li>
  *   <li>acceptedOutputModes: empty list (accept all)</li>
  *   <li>historyLength: {@code null} (no history)</li>
- *   <li>pushNotificationConfig: {@code null} (no push notifications)</li>
+ *   <li>taskPushNotificationConfig: {@code null} (no push notifications)</li>
  *   <li>metadata: empty map</li>
  * </ul>
  * <p>
@@ -134,15 +135,15 @@
  *
  * @see io.a2a.client.Client
  * @see io.a2a.client.ClientBuilder
- * @see PushNotificationConfig
+ * @see TaskPushNotificationConfig
  */
 public class ClientConfig {
 
     private final Boolean streaming;
     private final Boolean polling;
     private final Boolean useClientPreference;
     private final List<String> acceptedOutputModes;
-    private final @Nullable PushNotificationConfig pushNotificationConfig;
+    private final @Nullable TaskPushNotificationConfig taskPushNotificationConfig;
     private final @Nullable Integer historyLength;
     private final Map<String, Object> metadata;
 
@@ -151,7 +152,7 @@ private ClientConfig(Builder builder) {
         this.polling = builder.polling == null ? false : builder.polling;
         this.useClientPreference = builder.useClientPreference == null ? false : builder.useClientPreference;
         this.acceptedOutputModes = builder.acceptedOutputModes;
-        this.pushNotificationConfig = builder.pushNotificationConfig;
+        this.taskPushNotificationConfig = builder.taskPushNotificationConfig;
         this.historyLength = builder.historyLength;
         this.metadata = builder.metadata;
     }
@@ -219,10 +220,10 @@ public List<String> getAcceptedOutputModes() {
      * calls unless overridden with a different configuration.
      *
      * @return the push notification config, or {@code null} if not configured
-     * @see io.a2a.client.Client#sendMessage(io.a2a.spec.Message, io.a2a.spec.PushNotificationConfig, java.util.Map, io.a2a.client.transport.spi.interceptors.ClientCallContext)
+     * @see io.a2a.client.Client#sendMessage(io.a2a.spec.Message, io.a2a.spec.TaskPushNotificationConfig, java.util.Map, io.a2a.client.transport.spi.interceptors.ClientCallContext)
      */
-    public @Nullable PushNotificationConfig getPushNotificationConfig() {
-        return pushNotificationConfig;
+    public @Nullable TaskPushNotificationConfig getTaskPushNotificationConfig() {
+        return taskPushNotificationConfig;
     }
 
     /**
@@ -278,7 +279,7 @@ public static class Builder {
         private @Nullable Boolean polling;
         private @Nullable Boolean useClientPreference;
         private List<String> acceptedOutputModes = new ArrayList<>();
-        private @Nullable PushNotificationConfig pushNotificationConfig;
+        private @Nullable TaskPushNotificationConfig taskPushNotificationConfig;
         private @Nullable Integer historyLength;
         private Map<String, Object> metadata = new HashMap<>();
 
@@ -347,12 +348,12 @@ public Builder setAcceptedOutputModes(List<String> acceptedOutputModes) {
          * This webhook configuration will be used for all sendMessage calls
          * unless overridden. The agent will POST task update events to the specified URL.
          *
-         * @param pushNotificationConfig the push notification configuration
+         * @param taskPushNotificationConfig the push notification configuration
          * @return this builder for method chaining
-         * @see io.a2a.client.Client#sendMessage(io.a2a.spec.Message, io.a2a.spec.PushNotificationConfig, java.util.Map, io.a2a.client.transport.spi.interceptors.ClientCallContext)
+         * @see io.a2a.client.Client#sendMessage(io.a2a.spec.Message, io.a2a.spec.TaskPushNotificationConfig, java.util.Map, io.a2a.client.transport.spi.interceptors.ClientCallContext)
          */
-        public Builder setPushNotificationConfig(PushNotificationConfig pushNotificationConfig) {
-            this.pushNotificationConfig = pushNotificationConfig;
+        public Builder setTaskPushNotificationConfig(TaskPushNotificationConfig taskPushNotificationConfig) {
+            this.taskPushNotificationConfig = taskPushNotificationConfig;
             return this;
         }
 
@@ -396,7 +397,7 @@ public Builder setMetadata(Map<String, Object> metadata) {
          *   <li>polling: {@code false}</li>
          *   <li>useClientPreference: {@code false}</li>
          *   <li>acceptedOutputModes: empty list</li>
-         *   <li>pushNotificationConfig: {@code null}</li>
+         *   <li>taskPushNotificationConfig: {@code null}</li>
          *   <li>historyLength: {@code null}</li>
          *   <li>metadata: empty map</li>
          * </ul>

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransport.java

@@ -235,12 +235,7 @@ public TaskPushNotificationConfig createTaskPushNotificationConfiguration(TaskPu
             @Nullable ClientCallContext context) throws A2AClientException {
         checkNotNullParam("request", request);
 
-        String configId = request.config().id();
-        io.a2a.grpc.CreateTaskPushNotificationConfigRequest grpcRequest = io.a2a.grpc.CreateTaskPushNotificationConfigRequest.newBuilder()
-                .setTaskId(request.taskId())
-                .setConfig(ToProto.taskPushNotificationConfig(request).getPushNotificationConfig())
-                .setTenant(resolveTenant(request.tenant()))
-                .build();
+        io.a2a.grpc.TaskPushNotificationConfig grpcRequest = ToProto.taskPushNotificationConfig(request);
         PayloadAndHeaders payloadAndHeaders = applyInterceptors(SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD, grpcRequest, agentCard, context);
 
         try {