fix(core): fix list hash stability for equivalent messages

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/formatter/openai/dto/OpenAIReasoningDetail.java

@@ -18,6 +18,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.Objects;
 
 /**
  * OpenAI Reasoning Detail DTO (OpenRouter specific for Gemini).
@@ -90,4 +91,26 @@ public Integer getIndex() {
     public void setIndex(Integer index) {
         this.index = index;
     }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof OpenAIReasoningDetail)) {
+            return false;
+        }
+        OpenAIReasoningDetail that = (OpenAIReasoningDetail) o;
+        return Objects.equals(this.id, that.id)
+                && Objects.equals(this.type, that.type)
+                && Objects.equals(this.data, that.data)
+                && Objects.equals(this.text, that.text)
+                && Objects.equals(this.format, that.format)
+                && Objects.equals(this.index, that.index);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.id, this.type, this.data, this.text, this.format, this.index);
+    }
 }

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

@@ -56,6 +56,23 @@ public Source getSource() {
         return source;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof AudioBlock)) {
+            return false;
+        }
+        AudioBlock that = (AudioBlock) o;
+        return Objects.equals(this.source, that.source);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.source);
+    }
+
     /**
      * Creates a new builder for constructing AudioBlock instances.
      *

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

@@ -75,6 +75,24 @@ public String getData() {
         return data;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof Base64Source)) {
+            return false;
+        }
+        Base64Source that = (Base64Source) o;
+        return Objects.equals(this.mediaType, that.mediaType)
+                && Objects.equals(this.data, that.data);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.mediaType, this.data);
+    }
+
     /**
      * Creates a new builder for constructing Base64Source instances.
      *

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

@@ -97,6 +97,25 @@ public Integer getMaxPixels() {
         return maxPixels;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof ImageBlock)) {
+            return false;
+        }
+        ImageBlock that = (ImageBlock) o;
+        return Objects.equals(this.source, that.source)
+                && Objects.equals(this.minPixels, that.minPixels)
+                && Objects.equals(this.maxPixels, that.maxPixels);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.source, this.minPixels, this.maxPixels);
+    }
+
     /**
      * Creates a new builder for constructing ImageBlock instances.
      *

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

@@ -109,6 +109,29 @@ private Msg(
         this.timestamp = timestamp;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        } else if (!(o instanceof Msg)) {
+            return false;
+        } else {
+            Msg that = (Msg) o;
+            return Objects.equals(this.id, that.id)
+                    && Objects.equals(this.name, that.name)
+                    && this.role == that.role
+                    && Objects.equals(this.content, that.content)
+                    && Objects.equals(this.metadata, that.metadata)
+                    && Objects.equals(this.timestamp, that.timestamp);
+        }
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(
+                this.id, this.name, this.role, this.content, this.metadata, this.timestamp);
+    }
+
     /**
      * Creates a new message builder with a randomly generated ID.
      *

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

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.Objects;
 
 /**
  * Represents plain text content in a message.
@@ -56,6 +57,23 @@ public String toString() {
         return text;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        } else if (!(o instanceof TextBlock)) {
+            return false;
+        } else {
+            TextBlock that = (TextBlock) o;
+            return Objects.equals(this.text, that.text);
+        }
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.text);
+    }
+
     /**
      * Creates a new builder for constructing TextBlock instances.
      *

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

@@ -19,6 +19,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * Represents reasoning or thinking content in a message.
@@ -81,6 +82,24 @@ public Map<String, Object> getMetadata() {
         return metadata;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof ThinkingBlock)) {
+            return false;
+        }
+        ThinkingBlock that = (ThinkingBlock) o;
+        return Objects.equals(this.thinking, that.thinking)
+                && Objects.equals(this.metadata, that.metadata);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.thinking, this.metadata);
+    }
+
     /**
      * Creates a new builder for constructing ThinkingBlock instances.
      *

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

@@ -22,6 +22,7 @@
 import java.beans.Transient;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * Represents the result of a tool execution.
@@ -289,6 +290,26 @@ public ToolResultBlock withIdAndName(String id, String name) {
         return new ToolResultBlock(id, name, this.output, this.metadata);
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof ToolResultBlock)) {
+            return false;
+        }
+        ToolResultBlock that = (ToolResultBlock) o;
+        return Objects.equals(this.id, that.id)
+                && Objects.equals(this.name, that.name)
+                && Objects.equals(this.output, that.output)
+                && Objects.equals(this.metadata, that.metadata);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.id, this.name, this.output, this.metadata);
+    }
+
     /**
      * Creates a new builder for constructing ToolResultBlock instances.
      *

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

@@ -17,9 +17,11 @@
 
 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;
+import java.util.Objects;
 
 /**
  * Represents a tool use request within a message.
@@ -33,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;
@@ -93,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;
     }
 
     /**
@@ -135,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
@@ -144,6 +164,27 @@ public Map<String, Object> getMetadata() {
         return metadata;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof ToolUseBlock)) {
+            return false;
+        }
+        ToolUseBlock that = (ToolUseBlock) o;
+        return Objects.equals(this.id, that.id)
+                && Objects.equals(this.name, that.name)
+                && Objects.equals(this.input, that.input)
+                && Objects.equals(this.content, that.content)
+                && Objects.equals(this.metadata, that.metadata);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.id, this.name, this.input, this.content, this.metadata);
+    }
+
     /**
      * Creates a new builder for constructing a ToolUseBlock.
      *
@@ -211,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