feat: Add bidirectional mapper for StreamResponse and StreamingEventKind

Created StreamResponseMapper to handle conversion between:
- Proto: io.a2a.grpc.StreamResponse (protobuf oneof field)
- Domain: io.a2a.spec.StreamingEventKind (sealed interface)

The mapper supports all four streaming event types:
- Task (complete task state)
- Message (full message)
- TaskStatusUpdateEvent (status update events)
- TaskArtifactUpdateEvent (artifact update events)

Implementation details:
- toProto(): Uses instanceof pattern matching to determine which oneof field to set
- fromProto(): Uses switch expression on PayloadCase enum
- Delegates to existing mappers: TaskMapper, MessageMapper,
  TaskStatusUpdateEventMapper, TaskArtifactUpdateEventMapper
- Throws IllegalArgumentException when payload is not set

Added comprehensive test coverage:
- Bidirectional conversion for all four event types
- Error handling for unset payload
- Roundtrip tests to verify data preservation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ehsavoie

spec-grpc/src/main/java/io/a2a/grpc/mapper/StreamResponseMapper.java

@@ -0,0 +1,90 @@
+package io.a2a.grpc.mapper;
+
+import io.a2a.spec.Message;
+import io.a2a.spec.StreamingEventKind;
+import io.a2a.spec.Task;
+import io.a2a.spec.TaskArtifactUpdateEvent;
+import io.a2a.spec.TaskStatusUpdateEvent;
+import org.mapstruct.Mapper;
+
+/**
+ * Mapper between {@link io.a2a.spec.StreamingEventKind} and {@link io.a2a.grpc.StreamResponse}.
+ * <p>
+ * StreamResponse uses a protobuf oneof field to represent polymorphic streaming events.
+ * StreamingEventKind is a sealed interface with four permitted implementations:
+ * <ul>
+ *   <li>{@link Task} - Complete task state</li>
+ *   <li>{@link Message} - Full message</li>
+ *   <li>{@link TaskStatusUpdateEvent} - Status update event</li>
+ *   <li>{@link TaskArtifactUpdateEvent} - Artifact update event</li>
+ * </ul>
+ * <p>
+ * This mapper provides bidirectional conversion using instanceof checks (toProto)
+ * and switch expressions on the oneof case (fromProto).
+ */
+@Mapper(config = A2AProtoMapperConfig.class,
+        uses = {TaskMapper.class, MessageMapper.class, TaskStatusUpdateEventMapper.class, TaskArtifactUpdateEventMapper.class})
+public interface StreamResponseMapper {
+
+    StreamResponseMapper INSTANCE = A2AMappers.getMapper(StreamResponseMapper.class);
+
+    /**
+     * Converts domain StreamingEventKind to proto StreamResponse.
+     * Uses instanceof checks to determine which oneof field to set.
+     *
+     * @param domain the streaming event kind (Task, Message, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent)
+     * @return the proto StreamResponse with the appropriate oneof field set
+     */
+    default io.a2a.grpc.StreamResponse toProto(StreamingEventKind domain) {
+        if (domain == null) {
+            return null;
+        }
+
+        if (domain instanceof Task task) {
+            return io.a2a.grpc.StreamResponse.newBuilder()
+                    .setTask(TaskMapper.INSTANCE.toProto(task))
+                    .build();
+        } else if (domain instanceof Message message) {
+            return io.a2a.grpc.StreamResponse.newBuilder()
+                    .setMsg(MessageMapper.INSTANCE.toProto(message))
+                    .build();
+        } else if (domain instanceof TaskStatusUpdateEvent statusUpdate) {
+            return io.a2a.grpc.StreamResponse.newBuilder()
+                    .setStatusUpdate(TaskStatusUpdateEventMapper.INSTANCE.toProto(statusUpdate))
+                    .build();
+        } else if (domain instanceof TaskArtifactUpdateEvent artifactUpdate) {
+            return io.a2a.grpc.StreamResponse.newBuilder()
+                    .setArtifactUpdate(TaskArtifactUpdateEventMapper.INSTANCE.toProto(artifactUpdate))
+                    .build();
+        }
+
+        throw new IllegalArgumentException("Unknown StreamingEventKind type: " + domain.getClass().getName());
+    }
+
+    /**
+     * Converts proto StreamResponse to domain StreamingEventKind.
+     * Uses switch expression on the oneof case to determine which type to return.
+     *
+     * @param proto the proto StreamResponse
+     * @return the corresponding domain streaming event kind
+     * @throws IllegalArgumentException if the oneof field is not set
+     */
+    default StreamingEventKind fromProto(io.a2a.grpc.StreamResponse proto) {
+        if (proto == null) {
+            return null;
+        }
+
+        return switch (proto.getPayloadCase()) {
+            case TASK ->
+                TaskMapper.INSTANCE.fromProto(proto.getTask());
+            case MSG ->
+                MessageMapper.INSTANCE.fromProto(proto.getMsg());
+            case STATUS_UPDATE ->
+                TaskStatusUpdateEventMapper.INSTANCE.fromProto(proto.getStatusUpdate());
+            case ARTIFACT_UPDATE ->
+                TaskArtifactUpdateEventMapper.INSTANCE.fromProto(proto.getArtifactUpdate());
+            case PAYLOAD_NOT_SET ->
+                throw new IllegalArgumentException("StreamResponse payload oneof field not set");
+        };
+    }
+}

spec-grpc/src/test/java/io/a2a/grpc/mapper/StreamResponseMapperTest.java

@@ -0,0 +1,274 @@
+package io.a2a.grpc.mapper;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import io.a2a.spec.Artifact;
+import io.a2a.spec.Message;
+import io.a2a.spec.StreamingEventKind;
+import io.a2a.spec.Task;
+import io.a2a.spec.TaskArtifactUpdateEvent;
+import io.a2a.spec.TaskState;
+import io.a2a.spec.TaskStatus;
+import io.a2a.spec.TaskStatusUpdateEvent;
+import io.a2a.spec.TextPart;
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+
+public class StreamResponseMapperTest {
+
+    @Test
+    void testConvertTask_ToProto() {
+        // Arrange
+        Task task = new Task.Builder()
+                .id("task-123")
+                .contextId("context-456")
+                .status(new TaskStatus(TaskState.COMPLETED))
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse result = StreamResponseMapper.INSTANCE.toProto(task);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(io.a2a.grpc.StreamResponse.PayloadCase.TASK, result.getPayloadCase());
+        assertEquals("task-123", result.getTask().getId());
+        assertEquals("context-456", result.getTask().getContextId());
+        assertEquals(io.a2a.grpc.TaskState.TASK_STATE_COMPLETED, result.getTask().getStatus().getState());
+    }
+
+    @Test
+    void testConvertTask_FromProto() {
+        // Arrange
+        io.a2a.grpc.StreamResponse proto = io.a2a.grpc.StreamResponse.newBuilder()
+                .setTask(io.a2a.grpc.Task.newBuilder()
+                        .setId("task-123")
+                        .setContextId("context-456")
+                        .setStatus(io.a2a.grpc.TaskStatus.newBuilder()
+                                .setState(io.a2a.grpc.TaskState.TASK_STATE_COMPLETED)
+                                .build())
+                        .build())
+                .build();
+
+        // Act
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(Task.class, result);
+        Task task = (Task) result;
+        assertEquals("task-123", task.getId());
+        assertEquals("context-456", task.getContextId());
+        assertEquals(TaskState.COMPLETED, task.getStatus().state());
+    }
+
+    @Test
+    void testConvertMessage_ToProto() {
+        // Arrange
+        Message message = new Message.Builder()
+                .messageId("msg-123")
+                .contextId("context-456")
+                .role(Message.Role.USER)
+                .parts(Collections.singletonList(new TextPart("Hello")))
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse result = StreamResponseMapper.INSTANCE.toProto(message);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(io.a2a.grpc.StreamResponse.PayloadCase.MSG, result.getPayloadCase());
+        assertEquals("msg-123", result.getMsg().getMessageId());
+        assertEquals("context-456", result.getMsg().getContextId());
+        assertEquals(io.a2a.grpc.Role.ROLE_USER, result.getMsg().getRole());
+    }
+
+    @Test
+    void testConvertMessage_FromProto() {
+        // Arrange
+        io.a2a.grpc.StreamResponse proto = io.a2a.grpc.StreamResponse.newBuilder()
+                .setMsg(io.a2a.grpc.Message.newBuilder()
+                        .setMessageId("msg-123")
+                        .setContextId("context-456")
+                        .setRole(io.a2a.grpc.Role.ROLE_USER)
+                        .addParts(io.a2a.grpc.Part.newBuilder()
+                                .setText("Hello")
+                                .build())
+                        .build())
+                .build();
+
+        // Act
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(Message.class, result);
+        Message message = (Message) result;
+        assertEquals("msg-123", message.getMessageId());
+        assertEquals("context-456", message.getContextId());
+        assertEquals(Message.Role.USER, message.getRole());
+    }
+
+    @Test
+    void testConvertTaskStatusUpdateEvent_ToProto() {
+        // Arrange
+        TaskStatusUpdateEvent event = new TaskStatusUpdateEvent.Builder()
+                .taskId("task-123")
+                .contextId("context-456")
+                .status(new TaskStatus(TaskState.WORKING))
+                .isFinal(false)
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse result = StreamResponseMapper.INSTANCE.toProto(event);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(io.a2a.grpc.StreamResponse.PayloadCase.STATUS_UPDATE, result.getPayloadCase());
+        assertEquals("task-123", result.getStatusUpdate().getTaskId());
+        assertEquals("context-456", result.getStatusUpdate().getContextId());
+        assertEquals(io.a2a.grpc.TaskState.TASK_STATE_WORKING, result.getStatusUpdate().getStatus().getState());
+        assertEquals(false, result.getStatusUpdate().getFinal());
+    }
+
+    @Test
+    void testConvertTaskStatusUpdateEvent_FromProto() {
+        // Arrange
+        io.a2a.grpc.StreamResponse proto = io.a2a.grpc.StreamResponse.newBuilder()
+                .setStatusUpdate(io.a2a.grpc.TaskStatusUpdateEvent.newBuilder()
+                        .setTaskId("task-123")
+                        .setContextId("context-456")
+                        .setStatus(io.a2a.grpc.TaskStatus.newBuilder()
+                                .setState(io.a2a.grpc.TaskState.TASK_STATE_WORKING)
+                                .build())
+                        .setFinal(false)
+                        .build())
+                .build();
+
+        // Act
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(TaskStatusUpdateEvent.class, result);
+        TaskStatusUpdateEvent event = (TaskStatusUpdateEvent) result;
+        assertEquals("task-123", event.getTaskId());
+        assertEquals("context-456", event.getContextId());
+        assertEquals(TaskState.WORKING, event.getStatus().state());
+        assertEquals(false, event.isFinal());
+    }
+
+    @Test
+    void testConvertTaskArtifactUpdateEvent_ToProto() {
+        // Arrange
+        TaskArtifactUpdateEvent event = new TaskArtifactUpdateEvent.Builder()
+                .taskId("task-123")
+                .contextId("context-456")
+                .artifact(new Artifact.Builder()
+                        .artifactId("artifact-1")
+                        .name("result")
+                        .parts(new TextPart("Result text"))
+                        .build())
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse result = StreamResponseMapper.INSTANCE.toProto(event);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(io.a2a.grpc.StreamResponse.PayloadCase.ARTIFACT_UPDATE, result.getPayloadCase());
+        assertEquals("task-123", result.getArtifactUpdate().getTaskId());
+        assertEquals("context-456", result.getArtifactUpdate().getContextId());
+        assertEquals("artifact-1", result.getArtifactUpdate().getArtifact().getArtifactId());
+        assertEquals("result", result.getArtifactUpdate().getArtifact().getName());
+    }
+
+    @Test
+    void testConvertTaskArtifactUpdateEvent_FromProto() {
+        // Arrange
+        io.a2a.grpc.StreamResponse proto = io.a2a.grpc.StreamResponse.newBuilder()
+                .setArtifactUpdate(io.a2a.grpc.TaskArtifactUpdateEvent.newBuilder()
+                        .setTaskId("task-123")
+                        .setContextId("context-456")
+                        .setArtifact(io.a2a.grpc.Artifact.newBuilder()
+                                .setArtifactId("artifact-1")
+                                .setName("result")
+                                .addParts(io.a2a.grpc.Part.newBuilder()
+                                        .setText("Result text")
+                                        .build())
+                                .build())
+                        .build())
+                .build();
+
+        // Act
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(TaskArtifactUpdateEvent.class, result);
+        TaskArtifactUpdateEvent event = (TaskArtifactUpdateEvent) result;
+        assertEquals("task-123", event.getTaskId());
+        assertEquals("context-456", event.getContextId());
+        assertEquals("artifact-1", event.getArtifact().artifactId());
+        assertEquals("result", event.getArtifact().name());
+    }
+
+    @Test
+    void testConvertStreamResponse_FromProto_PayloadNotSet_ThrowsException() {
+        // Arrange
+        io.a2a.grpc.StreamResponse proto = io.a2a.grpc.StreamResponse.newBuilder().build();
+
+        // Act & Assert
+        IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+            StreamResponseMapper.INSTANCE.fromProto(proto);
+        });
+        assertEquals("StreamResponse payload oneof field not set", exception.getMessage());
+    }
+
+    @Test
+    void testConvertStreamResponse_Roundtrip_Task() {
+        // Arrange
+        Task originalTask = new Task.Builder()
+                .id("task-123")
+                .contextId("context-456")
+                .status(new TaskStatus(TaskState.SUBMITTED))
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse proto = StreamResponseMapper.INSTANCE.toProto(originalTask);
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(Task.class, result);
+        Task roundtrippedTask = (Task) result;
+        assertEquals(originalTask.getId(), roundtrippedTask.getId());
+        assertEquals(originalTask.getContextId(), roundtrippedTask.getContextId());
+        assertEquals(originalTask.getStatus().state(), roundtrippedTask.getStatus().state());
+    }
+
+    @Test
+    void testConvertStreamResponse_Roundtrip_Message() {
+        // Arrange
+        Message originalMessage = new Message.Builder()
+                .messageId("msg-123")
+                .contextId("context-456")
+                .role(Message.Role.AGENT)
+                .parts(Collections.singletonList(new TextPart("Response")))
+                .build();
+
+        // Act
+        io.a2a.grpc.StreamResponse proto = StreamResponseMapper.INSTANCE.toProto(originalMessage);
+        StreamingEventKind result = StreamResponseMapper.INSTANCE.fromProto(proto);
+
+        // Assert
+        assertNotNull(result);
+        assertInstanceOf(Message.class, result);
+        Message roundtrippedMessage = (Message) result;
+        assertEquals(originalMessage.getMessageId(), roundtrippedMessage.getMessageId());
+        assertEquals(originalMessage.getContextId(), roundtrippedMessage.getContextId());
+        assertEquals(originalMessage.getRole(), roundtrippedMessage.getRole());
+    }
+}