From 780b6024837c310d4371146b11387fd69d933535 Mon Sep 17 00:00:00 2001 From: WMK666666 <3496319356@qq.com> Date: Tue, 10 Nov 2026 01:11:26 +0800 Subject: [PATCH] fix(compat-0.3): merge artifact metadata when appending a streamed chunk TaskArtifactUpdateEvent#append means the content of an artifact is appended to a previously sent artifact with the same ID. The 0.3 accumulation path only merged the parts, so a chunk carrying its own metadata had that metadata silently dropped, and keys the chunk wanted to override kept the value of the first chunk. The v1.0 path already merges both, since #616 (reported in #615). Mirror that behaviour in Utils_v0_3.appendArtifactToTask so the same stream produces the same artifact through either client. Artifact_v0_3.Builder#metadata rejects null, because it wraps the map in Collections.unmodifiableMap(new HashMap<>(metadata)); the v1.0 builder tolerates null, this one does not. The merged map is therefore only set when at least one of the two artifacts actually carries metadata. Cover both the utility and the client-side accumulation, which had no tests for this path before. --- .../client/ClientTaskManager_v0_3_Test.java | 38 +++++ .../sdk/compat03/util/Utils_v0_3.java | 29 +++- .../sdk/compat03/util/Utils_v0_3_Test.java | 149 ++++++++++++++++++ 3 files changed, 212 insertions(+), 4 deletions(-) create mode 100644 compat-0.3/spec/src/test/java/org/a2aproject/sdk/compat03/util/Utils_v0_3_Test.java diff --git a/compat-0.3/client/base/src/test/java/org/a2aproject/sdk/compat03/client/ClientTaskManager_v0_3_Test.java b/compat-0.3/client/base/src/test/java/org/a2aproject/sdk/compat03/client/ClientTaskManager_v0_3_Test.java index ec6f6eeaf..29c02cfc6 100644 --- a/compat-0.3/client/base/src/test/java/org/a2aproject/sdk/compat03/client/ClientTaskManager_v0_3_Test.java +++ b/compat-0.3/client/base/src/test/java/org/a2aproject/sdk/compat03/client/ClientTaskManager_v0_3_Test.java @@ -4,8 +4,12 @@ import static org.junit.jupiter.api.Assertions.assertTrue; import java.util.List; +import java.util.Map; +import org.a2aproject.sdk.compat03.spec.Artifact_v0_3; import org.a2aproject.sdk.compat03.spec.Message_v0_3; +import org.a2aproject.sdk.compat03.spec.Part_v0_3; +import org.a2aproject.sdk.compat03.spec.TaskArtifactUpdateEvent_v0_3; import org.a2aproject.sdk.compat03.spec.TaskState_v0_3; import org.a2aproject.sdk.compat03.spec.TaskStatusUpdateEvent_v0_3; import org.a2aproject.sdk.compat03.spec.TaskStatus_v0_3; @@ -15,6 +19,40 @@ public class ClientTaskManager_v0_3_Test { + private static Artifact_v0_3 artifact(String text, Map metadata) { + List> parts = List.of(new TextPart_v0_3(text)); + return new Artifact_v0_3.Builder() + .artifactId("artifact-1") + .parts(parts) + .metadata(metadata) + .build(); + } + + @Test + public void testArtifactChunkMetadataIsMergedIntoTheAccumulatedTask() { + ClientTaskManager_v0_3 taskManager = new ClientTaskManager_v0_3(); + + taskManager.saveTaskEvent(new TaskArtifactUpdateEvent_v0_3.Builder() + .taskId("task-123") + .contextId("context-123") + .append(false) + .artifact(artifact("chunk-1", Map.of("source", "ocr"))) + .build()); + + Task_v0_3 task = taskManager.saveTaskEvent(new TaskArtifactUpdateEvent_v0_3.Builder() + .taskId("task-123") + .contextId("context-123") + .append(true) + .artifact(artifact("chunk-2", Map.of("progress", "60%"))) + .build()); + + assertEquals(1, task.artifacts().size()); + assertEquals( + Map.of("source", "ocr", "progress", "60%"), + task.artifacts().get(0).metadata()); + assertEquals(2, task.artifacts().get(0).parts().size()); + } + @Test public void testStatusMessagesMoveToHistoryWhenSuperseded() throws Exception { ClientTaskManager_v0_3 taskManager = new ClientTaskManager_v0_3(); diff --git a/compat-0.3/spec/src/main/java/org/a2aproject/sdk/compat03/util/Utils_v0_3.java b/compat-0.3/spec/src/main/java/org/a2aproject/sdk/compat03/util/Utils_v0_3.java index f12830974..2f563e1bf 100644 --- a/compat-0.3/spec/src/main/java/org/a2aproject/sdk/compat03/util/Utils_v0_3.java +++ b/compat-0.3/spec/src/main/java/org/a2aproject/sdk/compat03/util/Utils_v0_3.java @@ -1,7 +1,9 @@ package org.a2aproject.sdk.compat03.util; import java.util.ArrayList; +import java.util.HashMap; import java.util.List; +import java.util.Map; import org.a2aproject.sdk.compat03.json.JsonProcessingException_v0_3; import org.a2aproject.sdk.compat03.json.JsonUtil_v0_3; @@ -111,10 +113,29 @@ public static Task_v0_3 appendArtifactToTask(Task_v0_3 task, TaskArtifactUpdateE LOGGER.fine(String.format("Appending parts to artifact id %s for task %s", artifactId, taskId)); List> parts = new ArrayList<>(existingArtifact.parts()); parts.addAll(newArtifact.parts()); - Artifact_v0_3 updated = new Artifact_v0_3.Builder(existingArtifact) - .parts(parts) - .build(); - artifacts.set(existingArtifactIndex, updated); + + Artifact_v0_3.Builder builder = + new Artifact_v0_3.Builder(existingArtifact).parts(parts); + + // Merge the chunk's metadata into the existing artifact, mirroring + // org.a2aproject.sdk.spec.util.Utils#appendArtifactToTask. + // Only set it when something is present: Artifact_v0_3.Builder#metadata + // rejects null, unlike the v1.0 builder. + Map mergedMetadata = null; + if (existingArtifact.metadata() != null || newArtifact.metadata() != null) { + mergedMetadata = new HashMap<>(); + if (existingArtifact.metadata() != null) { + mergedMetadata.putAll(existingArtifact.metadata()); + } + if (newArtifact.metadata() != null) { + mergedMetadata.putAll(newArtifact.metadata()); + } + } + if (mergedMetadata != null) { + builder.metadata(mergedMetadata); + } + + artifacts.set(existingArtifactIndex, builder.build()); } else { // We received a chunk to append, but we don't have an existing artifact. // We will ignore this chunk diff --git a/compat-0.3/spec/src/test/java/org/a2aproject/sdk/compat03/util/Utils_v0_3_Test.java b/compat-0.3/spec/src/test/java/org/a2aproject/sdk/compat03/util/Utils_v0_3_Test.java new file mode 100644 index 000000000..10dee7f16 --- /dev/null +++ b/compat-0.3/spec/src/test/java/org/a2aproject/sdk/compat03/util/Utils_v0_3_Test.java @@ -0,0 +1,149 @@ +package org.a2aproject.sdk.compat03.util; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import org.a2aproject.sdk.compat03.spec.Artifact_v0_3; +import org.a2aproject.sdk.compat03.spec.Part_v0_3; +import org.a2aproject.sdk.compat03.spec.TaskArtifactUpdateEvent_v0_3; +import org.a2aproject.sdk.compat03.spec.TaskState_v0_3; +import org.a2aproject.sdk.compat03.spec.TaskStatus_v0_3; +import org.a2aproject.sdk.compat03.spec.Task_v0_3; +import org.a2aproject.sdk.compat03.spec.TextPart_v0_3; +import org.junit.jupiter.api.Test; + +/** + * Tests for {@link Utils_v0_3#appendArtifactToTask(Task_v0_3, TaskArtifactUpdateEvent_v0_3, String)}, + * focused on how the metadata of a streamed chunk is carried over to the accumulated artifact. + */ +class Utils_v0_3_Test { + + private static final String TASK_ID = "task-1"; + private static final String CONTEXT_ID = "context-1"; + private static final String ARTIFACT_ID = "artifact-1"; + + private static Task_v0_3 emptyTask() { + return new Task_v0_3.Builder() + .id(TASK_ID) + .contextId(CONTEXT_ID) + .status(new TaskStatus_v0_3(TaskState_v0_3.WORKING)) + .build(); + } + + private static Artifact_v0_3 artifact(String text, Map metadata) { + List> parts = List.of(new TextPart_v0_3(text)); + Artifact_v0_3.Builder builder = + new Artifact_v0_3.Builder().artifactId(ARTIFACT_ID).parts(parts); + if (metadata != null) { + builder.metadata(metadata); + } + return builder.build(); + } + + private static TaskArtifactUpdateEvent_v0_3 event(boolean append, Artifact_v0_3 artifact) { + return new TaskArtifactUpdateEvent_v0_3(TASK_ID, artifact, CONTEXT_ID, append, false, null); + } + + private static Artifact_v0_3 onlyArtifact(Task_v0_3 task) { + assertEquals(1, task.artifacts().size()); + return task.artifacts().get(0); + } + + @Test + void appendChunkMergesItsMetadataIntoTheExistingArtifact() { + Task_v0_3 task = emptyTask(); + task = Utils_v0_3.appendArtifactToTask( + task, + event(false, artifact("chunk-1", Map.of("source", "ocr", "page", 1))), + TASK_ID); + task = Utils_v0_3.appendArtifactToTask( + task, + event(true, artifact("chunk-2", Map.of("page", 2, "progress", "60%"))), + TASK_ID); + + Artifact_v0_3 merged = onlyArtifact(task); + Map metadata = merged.metadata(); + + assertNotNull(metadata, "metadata must not be dropped when appending a chunk"); + assertEquals("ocr", metadata.get("source"), "keys only present on the first chunk must survive"); + assertEquals(2, metadata.get("page"), "keys set by the chunk must win over the earlier value"); + assertEquals("60%", metadata.get("progress"), "keys only present on the chunk must be added"); + assertEquals(2, merged.parts().size(), "the chunk's parts must still be appended"); + } + + @Test + void appendChunkWithoutMetadataKeepsTheExistingMetadata() { + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), event(false, artifact("chunk-1", Map.of("source", "ocr"))), TASK_ID); + task = Utils_v0_3.appendArtifactToTask(task, event(true, artifact("chunk-2", null)), TASK_ID); + + Artifact_v0_3 merged = onlyArtifact(task); + assertEquals(Map.of("source", "ocr"), merged.metadata()); + assertEquals(2, merged.parts().size()); + } + + @Test + void appendChunkCarriesMetadataWhenTheExistingArtifactHasNone() { + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), event(false, artifact("chunk-1", null)), TASK_ID); + task = Utils_v0_3.appendArtifactToTask( + task, event(true, artifact("chunk-2", Map.of("progress", "50%"))), TASK_ID); + + Artifact_v0_3 merged = onlyArtifact(task); + assertEquals(Map.of("progress", "50%"), merged.metadata()); + assertEquals(2, merged.parts().size()); + } + + @Test + void appendChunkLeavesTheExistingMetadataUntouchedWhenNeitherSideHasAny() { + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), event(false, artifact("chunk-1", null)), TASK_ID); + task = Utils_v0_3.appendArtifactToTask(task, event(true, artifact("chunk-2", null)), TASK_ID); + + Artifact_v0_3 merged = onlyArtifact(task); + assertNull(merged.metadata()); + assertEquals(2, merged.parts().size()); + } + + @Test + void appendChunkDoesNotMutateTheMetadataMapOfTheReceivedChunk() { + Map firstChunkMetadata = new HashMap<>(Map.of("source", "ocr")); + Map secondChunkMetadata = new HashMap<>(Map.of("progress", "60%")); + + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), event(false, artifact("chunk-1", firstChunkMetadata)), TASK_ID); + task = Utils_v0_3.appendArtifactToTask( + task, event(true, artifact("chunk-2", secondChunkMetadata)), TASK_ID); + + assertEquals(Map.of("source", "ocr"), firstChunkMetadata); + assertEquals(Map.of("progress", "60%"), secondChunkMetadata); + } + + @Test + void replacementChunkReplacesTheArtifactInsteadOfMergingIt() { + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), + event(false, artifact("chunk-1", Map.of("source", "ocr", "page", 1))), + TASK_ID); + task = Utils_v0_3.appendArtifactToTask( + task, event(false, artifact("chunk-2", Map.of("page", 9))), TASK_ID); + + Artifact_v0_3 replaced = onlyArtifact(task); + assertEquals(Map.of("page", 9), replaced.metadata()); + assertEquals(1, replaced.parts().size()); + } + + @Test + void appendChunkForUnknownArtifactIsIgnored() { + Task_v0_3 task = Utils_v0_3.appendArtifactToTask( + emptyTask(), event(true, artifact("chunk-1", Map.of("progress", "60%"))), TASK_ID); + + assertTrue(task.artifacts().isEmpty()); + } +}