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

[Weilong-Qin]

AgentScope-Java Version

1.0.13-SNAPSHOT

Description

Fixes #1357
ListHashUtil.computeHash was using each list item’s hashCode() directly.
As a result, two separately constructed but semantically identical message lists could produce different hash values. It leads to unnecessary full rewrites in session persistence paths.
To fix it, hash each item based on its JSON serialization.

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Fixes unstable list hashing used by session persistence by switching ListHashUtil.computeHash from element hashCode() to hashing a JSON-serialized representation of sampled elements, aiming to prevent unnecessary full rewrites when lists are logically equivalent.

Changes:

• Update ListHashUtil.computeHash to derive each sampled element hash from JsonUtils.getJsonCodec().toJson(item).
• Add a unit test asserting that two separately constructed but equivalent List<Msg> instances produce the same hash.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
agentscope-core/src/main/java/io/agentscope/core/session/ListHashUtil.java	Switch per-item hashing from hashCode() to JSON-serialization-based hashing for better stability across equivalent objects.
agentscope-extensions/agentscope-extensions-session-mysql/src/test/java/io/agentscope/core/session/mysql/MysqlSessionTest.java	Add regression test to validate stable hashing for equivalent message lists.

[codecov]

Codecov Report

❌ Patch coverage is 75.39683% with 31 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...re/formatter/openai/dto/OpenAIReasoningDetail.java	58.33%	0 Missing and 5 partials ⚠️
.../java/io/agentscope/core/message/ToolUseBlock.java	72.22%	0 Missing and 5 partials ⚠️
...in/java/io/agentscope/core/message/VideoBlock.java	58.33%	0 Missing and 5 partials ⚠️
.../core/formatter/gemini/GeminiMessageConverter.java	42.85%	2 Missing and 2 partials ⚠️
.../src/main/java/io/agentscope/core/message/Msg.java	72.72%	0 Missing and 3 partials ⚠️
...va/io/agentscope/core/message/ToolResultBlock.java	70.00%	0 Missing and 3 partials ⚠️
...in/java/io/agentscope/core/message/ImageBlock.java	77.77%	0 Missing and 2 partials ⚠️
.../main/java/io/agentscope/core/model/ChatUsage.java	75.00%	0 Missing and 2 partials ⚠️
.../java/io/agentscope/core/message/Base64Source.java	87.50%	0 Missing and 1 partial ⚠️
...java/io/agentscope/core/message/ThinkingBlock.java	87.50%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[luowanghaoyun]

Per-item toJson in computeHash can be expensive (allocations + serialization) on frequent saves. Would it make sense to switch to a cheaper stable fingerprint (e.g. value-based hashCode on persisted State types, or a small dedicated fingerprint API) instead of JSON here?

[Weilong-Qin]

Per-item toJson in computeHash can be expensive (allocations + serialization) on frequent saves. Would it make sense to switch to a cheaper stable fingerprint (e.g. value-based hashCode on persisted State types, or a small dedicated fingerprint API) instead of JSON here?

OK, I will try to override the hashCode and equals methods based on attribute values for the relevant implementation classes.

[LearningGp]

ToolUseBlock.metadata stores Gemini's byte[] thoughtSignature via METADATA_THOUGHT_SIGNATURE. However, Map.equals() delegates to the elements' equals() methods, and in Java, byte[].equals() and byte[].hashCode() rely on reference equality (identity-based).

As a result, Gemini-generated messages containing tool calls will still produce different hashes after being deserialized or reconstructed. Therefore, the original bug remains unfixed in the Gemini execution path.

[Weilong-Qin]

Thanks.

I updated METADATA_THOUGHT_SIGNATURE to follow the OpenAI path and store a Base64-encoded String instead of a byte[]. This keeps the internal representation stable and allows Map.equals to compare values correctly.

ToolUseBlock now normalizes any byte[] under that key into a Base64 String, GeminiResponseParser stores the signature in that format, and GeminiMessageConverter decodes it back to byte[] only when calling the Gemini API.

Does this approach look reasonable?

[LearningGp]

LGTM

[LearningGp]

[AgentScopeJavaBot]

🤖 AI Review

This PR adds value-based equals()/hashCode() to Msg, most ContentBlock subtypes (TextBlock, ImageBlock, AudioBlock, VideoBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock), their dependency types (Base64Source, URLSource, ChatUsage, OpenAIReasoningDetail), and normalizes ToolUseBlock metadata to convert legacy byte[] thought signatures to Base64 strings for stable serialization round-trips. It also fixes the Gemini formatter and response parser to align with the new Base64 representation, and includes a small bug fix in ToolCallParam.Builder's copy constructor (context -> runtimeContext). The changes are well-tested with comprehensive unit tests covering value equality, round-trip serialization, and hash stability scenarios. The overall approach of providing value-based equality at the message/block layer to stabilize ListHashUtil.computeHash() is sound and solves the root cause correctly.

(inline comments could not be attached — line numbers fell outside PR hunks. See archived report.)