fix(core): stabilize ToolUseBlock hashCode for Gemini thoughtSignature

Author: Weilong-Qin

agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiMessageConverter.java

@@ -122,13 +122,22 @@ public List<Content> convertMessages(List<Msg> msgs) {
                     // Build Part with FunctionCall and optional thought signature
                     Part.Builder partBuilder = Part.builder().functionCall(functionCall);
 
-                    // Check for thought signature in metadata
+                    // Check for thought signature in metadata (always stored as Base64 String,
+                    // see ToolUseBlock#normalizeMetadata)
                     Map<String, Object> metadata = tub.getMetadata();
                     if (metadata != null
                             && metadata.containsKey(ToolUseBlock.METADATA_THOUGHT_SIGNATURE)) {
                         Object signature = metadata.get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE);
-                        if (signature instanceof byte[]) {
-                            partBuilder.thoughtSignature((byte[]) signature);
+                        if (signature instanceof String encodedSignature
+                                && !encodedSignature.isEmpty()) {
+                            try {
+                                partBuilder.thoughtSignature(
+                                        Base64.getDecoder().decode(encodedSignature));
+                            } catch (IllegalArgumentException e) {
+                                log.warn(
+                                        "Invalid Base64 thought signature in ToolUseBlock metadata,"
+                                                + " skipping");
+                            }
                         }
                     }
 

agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiResponseParser.java

@@ -32,6 +32,7 @@
 import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
+import java.util.Base64;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -199,7 +200,9 @@ protected void parseToolCall(
             Map<String, Object> metadata = null;
             if (thoughtSignature != null) {
                 metadata = new HashMap<>();
-                metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, thoughtSignature);
+                metadata.put(
+                        ToolUseBlock.METADATA_THOUGHT_SIGNATURE,
+                        Base64.getEncoder().encodeToString(thoughtSignature));
             }
 
             blocks.add(

agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.Base64;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
@@ -34,7 +35,7 @@
  */
 public final class ToolUseBlock extends ContentBlock {
 
-    /** Metadata key for Gemini thought signature (byte[] value). */
+    /** Metadata key for provider thought signatures (String value). */
     public static final String METADATA_THOUGHT_SIGNATURE = "thoughtSignature";
 
     private final String id;
@@ -94,7 +95,25 @@ public ToolUseBlock(
         this.metadata =
                 metadata == null
                         ? Collections.emptyMap()
-                        : Collections.unmodifiableMap(new HashMap<>(metadata));
+                        : Collections.unmodifiableMap(normalizeMetadata(metadata));
+    }
+
+    /**
+     * Normalizes metadata values to ensure stable {@link #equals(Object)} and {@link #hashCode()}
+     * across serialization round-trips.
+     *
+     * <p>Specifically, a {@code byte[]} stored under {@link #METADATA_THOUGHT_SIGNATURE} is
+     * converted to a Base64-encoded {@code String}, because {@code byte[]} relies on identity
+     * equality and would otherwise cause two semantically equal blocks to hash differently after
+     * deserialization.
+     */
+    private static Map<String, Object> normalizeMetadata(Map<String, Object> metadata) {
+        Map<String, Object> copy = new HashMap<>(metadata);
+        Object signature = copy.get(METADATA_THOUGHT_SIGNATURE);
+        if (signature instanceof byte[] bytes) {
+            copy.put(METADATA_THOUGHT_SIGNATURE, Base64.getEncoder().encodeToString(bytes));
+        }
+        return copy;
     }
 
     /**
@@ -136,7 +155,7 @@ public String getContent() {
     /**
      * Gets the provider-specific metadata.
      *
-     * <p>For Gemini, this may contain the thought signature under the key
+     * <p>For Gemini, this may contain a Base64-encoded thought signature under the key
      * {@link #METADATA_THOUGHT_SIGNATURE}.
      *
      * @return The metadata map, or an empty map if not set
@@ -233,7 +252,7 @@ public Builder content(String content) {
          * Sets the provider-specific metadata.
          *
          * <p>For Gemini, use {@link ToolUseBlock#METADATA_THOUGHT_SIGNATURE} as the key
-         * to store thought signatures.
+         * to store Base64-encoded thought signatures.
          *
          * @param metadata The metadata map
          * @return This builder for chaining

agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulatorTest.java

@@ -15,13 +15,13 @@
  */
 package io.agentscope.core.agent.accumulator;
 
-import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 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 io.agentscope.core.message.ToolUseBlock;
+import java.util.Base64;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -46,7 +46,7 @@ void setUp() {
     @DisplayName("Should accumulate metadata from tool call chunks")
     void testAccumulateMetadata() {
         // First chunk with thoughtSignature
-        byte[] signature = "test-thought-signature".getBytes();
+        String signature = Base64.getEncoder().encodeToString("test-thought-signature".getBytes());
         Map<String, Object> metadata = new HashMap<>();
         metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, signature);
 
@@ -77,9 +77,8 @@ void testAccumulateMetadata() {
         // Verify metadata is preserved
         assertNotNull(toolCall.getMetadata());
         assertTrue(toolCall.getMetadata().containsKey(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
-        assertArrayEquals(
-                signature,
-                (byte[]) toolCall.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
+        assertEquals(
+                signature, toolCall.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
     }
 
     @Test
@@ -107,7 +106,7 @@ void testAccumulateWithoutMetadata() {
     @DisplayName("Should handle parallel tool calls with different metadata")
     void testParallelToolCallsWithMetadata() {
         // First tool call with metadata
-        byte[] sig1 = "sig-1".getBytes();
+        String sig1 = Base64.getEncoder().encodeToString("sig-1".getBytes());
         Map<String, Object> metadata1 = new HashMap<>();
         metadata1.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, sig1);
 
@@ -139,6 +138,7 @@ void testParallelToolCallsWithMetadata() {
                 result.stream().filter(t -> "call_a".equals(t.getId())).findFirst().orElse(null);
         assertNotNull(resultA);
         assertTrue(resultA.getMetadata().containsKey(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
+        assertEquals(sig1, resultA.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
 
         // Second call should not have metadata
         ToolUseBlock resultB =

agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMessageConverterTest.java

@@ -18,6 +18,7 @@
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -770,8 +771,9 @@ void testConvertToolUseBlockWithThoughtSignature() {
         input.put("query", "test");
 
         byte[] thoughtSignature = "test-signature".getBytes();
+        String encodedSignature = Base64.getEncoder().encodeToString(thoughtSignature);
         Map<String, Object> metadata = new HashMap<>();
-        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, thoughtSignature);
+        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, encodedSignature);
 
         ToolUseBlock toolUseBlock =
                 ToolUseBlock.builder()
@@ -804,6 +806,43 @@ void testConvertToolUseBlockWithThoughtSignature() {
         assertArrayEquals(thoughtSignature, part.thoughtSignature().get());
     }
 
+    @Test
+    @DisplayName("Should normalize legacy byte[] thoughtSignature metadata to Base64 String")
+    void testConvertToolUseBlockWithLegacyByteArrayThoughtSignature() {
+        Map<String, Object> input = new HashMap<>();
+        input.put("query", "test");
+
+        byte[] thoughtSignature = "legacy-signature".getBytes();
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, thoughtSignature);
+
+        ToolUseBlock toolUseBlock =
+                ToolUseBlock.builder()
+                        .id("call_with_legacy_sig")
+                        .name("search")
+                        .input(input)
+                        .metadata(metadata)
+                        .build();
+
+        // Constructor normalizes byte[] to Base64 String so equals/hashCode stay stable
+        Object stored = toolUseBlock.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE);
+        assertInstanceOf(String.class, stored);
+        assertEquals(Base64.getEncoder().encodeToString(thoughtSignature), stored);
+
+        Msg msg =
+                Msg.builder()
+                        .name("assistant")
+                        .content(List.of(toolUseBlock))
+                        .role(MsgRole.ASSISTANT)
+                        .build();
+
+        List<Content> result = converter.convertMessages(List.of(msg));
+
+        Part part = result.get(0).parts().get().get(0);
+        assertTrue(part.thoughtSignature().isPresent());
+        assertArrayEquals(thoughtSignature, part.thoughtSignature().get());
+    }
+
     @Test
     @DisplayName("Should convert ToolUseBlock without thoughtSignature")
     void testConvertToolUseBlockWithoutThoughtSignature() {
@@ -842,8 +881,9 @@ void testThoughtSignatureRoundTrip() {
         input.put("location", "Tokyo");
 
         byte[] signature = "gemini3-thought-sig-abc123".getBytes();
+        String encodedSignature = Base64.getEncoder().encodeToString(signature);
         Map<String, Object> metadata = new HashMap<>();
-        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, signature);
+        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, encodedSignature);
 
         // Simulate assistant message with tool call (as would be constructed from parsed response)
         ToolUseBlock toolUseBlock =

agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiResponseParserTest.java

@@ -15,7 +15,6 @@
  */
 package io.agentscope.core.formatter.gemini;
 
-import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -34,6 +33,7 @@
 import io.agentscope.core.model.ChatResponse;
 import io.agentscope.core.model.ChatUsage;
 import java.time.Instant;
+import java.util.Base64;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -353,9 +353,9 @@ void testParseToolCallWithThoughtSignature() {
         // Verify thought signature is stored in metadata
         assertNotNull(toolUse.getMetadata());
         assertTrue(toolUse.getMetadata().containsKey(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
-        byte[] extractedSig =
-                (byte[]) toolUse.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE);
-        assertArrayEquals(thoughtSignature, extractedSig);
+        String extractedSig =
+                (String) toolUse.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE);
+        assertEquals(Base64.getEncoder().encodeToString(thoughtSignature), extractedSig);
     }
 
     @Test
@@ -432,6 +432,9 @@ void testParseParallelFunctionCallsWithThoughtSignature() {
         ToolUseBlock toolUse1 = (ToolUseBlock) chatResponse.getContent().get(0);
         assertEquals("call-1", toolUse1.getId());
         assertTrue(toolUse1.getMetadata().containsKey(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
+        assertEquals(
+                Base64.getEncoder().encodeToString(thoughtSignature),
+                toolUse1.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE));
 
         // Second tool call should not have signature
         ToolUseBlock toolUse2 = (ToolUseBlock) chatResponse.getContent().get(1);

agentscope-core/src/test/java/io/agentscope/core/message/ToolUseBlockTest.java

@@ -17,11 +17,14 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.Base64;
+import java.util.HashMap;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
 
@@ -185,6 +188,69 @@ void testRoundTripSerialization() throws JsonProcessingException {
         assertEquals(original.getMetadata(), deserialized.getMetadata());
     }
 
+    @Test
+    void testThoughtSignatureStringRoundTripKeepsValueHashCode() throws JsonProcessingException {
+        ToolUseBlock original =
+                ToolUseBlock.builder()
+                        .id("tool-gemini")
+                        .name("search")
+                        .input(Map.of("query", "agent"))
+                        .metadata(Map.of(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, "dGVzdA=="))
+                        .build();
+
+        String json = objectMapper.writeValueAsString(original);
+        ToolUseBlock deserialized = objectMapper.readValue(json, ToolUseBlock.class);
+
+        assertEquals(original, deserialized);
+        assertEquals(original.hashCode(), deserialized.hashCode());
+    }
+
+    @Test
+    void testConstructorNormalizesByteArrayThoughtSignatureToBase64String() {
+        byte[] rawSignature = "raw-thought-signature".getBytes();
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, rawSignature);
+
+        ToolUseBlock block =
+                ToolUseBlock.builder()
+                        .id("tool-bytes")
+                        .name("search")
+                        .input(Map.of("query", "agent"))
+                        .metadata(metadata)
+                        .build();
+
+        Object stored = block.getMetadata().get(ToolUseBlock.METADATA_THOUGHT_SIGNATURE);
+        assertInstanceOf(String.class, stored);
+        assertEquals(Base64.getEncoder().encodeToString(rawSignature), stored);
+    }
+
+    @Test
+    void testByteArrayAndBase64StringMetadataProduceEqualBlocks() {
+        byte[] rawSignature = "same-signature".getBytes();
+        String encoded = Base64.getEncoder().encodeToString(rawSignature);
+
+        Map<String, Object> bytesMetadata = new HashMap<>();
+        bytesMetadata.put(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, rawSignature);
+        ToolUseBlock fromBytes =
+                ToolUseBlock.builder()
+                        .id("tool-id")
+                        .name("search")
+                        .input(Map.of("query", "agent"))
+                        .metadata(bytesMetadata)
+                        .build();
+
+        ToolUseBlock fromString =
+                ToolUseBlock.builder()
+                        .id("tool-id")
+                        .name("search")
+                        .input(Map.of("query", "agent"))
+                        .metadata(Map.of(ToolUseBlock.METADATA_THOUGHT_SIGNATURE, encoded))
+                        .build();
+
+        assertEquals(fromString, fromBytes);
+        assertEquals(fromString.hashCode(), fromBytes.hashCode());
+    }
+
     @Test
     void testInputMapIsUnmodifiable() {
         Map<String, Object> inputMap = Map.of("key1", "value1", "key2", "value2");