feat: harden spec immutability

[Sh1bari]

Spec cleanup: immutable records and copy semantics

Build fails after actions/checkout was bumped from v6 to v7 in PR #948:
#948

[gemini-code-assist]

Code Review

This pull request introduces defensive copying and immutability for collection fields across several record classes and builders in the org.a2aproject.sdk.spec package using List.copyOf and Map.copyOf. The review feedback suggests further refining these changes by replacing @Nullable Boolean with a primitive boolean in MessageSendConfiguration and utilizing explicit canonical constructors in CancelTaskParams to avoid redundant null checks on record accessors when non-null default values are guaranteed.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[kabir]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive copying of collections and maps across various specification records (such as AgentCard, AgentSkill, Artifact, and others) to ensure immutability, along with comprehensive unit tests to verify this behavior. The review feedback correctly points out a critical issue: using Map.copyOf on arbitrary metadata or parameter maps will throw a NullPointerException if any values are null, which is common in JSON-based protocols. It is recommended to use Collections.unmodifiableMap(new HashMap<>(...)) instead to safely preserve immutability while supporting null values.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Sh1bari]

i will fix it

[Sh1bari]

or no what do you think? @kabir

[kabir]

@Sh1bari I see this in the javadoc for Map.copyOf so it might have a point

However, my local Claude instance says that there are other occurrences of Map.copyOIf in Message, Task, TextPart, FilePart and DataPart which are not touched by this PR. But I think you can update the ones you changed, and I can do the rest at some point if it becomes an issue

[Sh1bari]

@kabir done

[kabir]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces defensive copying and immutability enhancements across various record classes in the SDK specification (such as AgentCard, AgentCapabilities, and CancelTaskParams) to prevent external mutation of internal collections and maps. It also adds a comprehensive suite of unit tests to verify these immutability behaviors. The review feedback highlights potential NullPointerException risks in CancelTaskParams when metadata is null, recommending graceful handling by defaulting to empty maps in both the compact constructor and the builder.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[kabir]

@jmesnil Can you please take a look?

[jmesnil]

is this test related to the spec hardening?

[Sh1bari]

No, this test was accidentally deleted in feat: Implement MainEventBus architecture for event queue processing (#611). I just rollback it

[jmesnil]

the helper methods looks good except for the 2 method names that are a bit misleading.

[jmesnil]

@Sh1bari Helper methods look good, thanks

[Sh1bari]

Great, I’ll update the PR within an hour.

[Sh1bari]

@jmesnil Done

[Sh1bari]

ITK image build is broken.
1.912 Reading state information...
1.915 Package curl is not available, but is referred to by another package.
1.915 This may mean that the package is missing, has been obsoleted, or
1.915 is only available from another source
1.915
1.917 E: Version '7.88.1-10+deb12u14' for 'curl' was not found

[kabir]

@Sh1bari yeah, I think the ITK looks broken, and not related to this

[kabir]

Hi @Sh1bari I opened Sh1bari#2 against your repo with fixes suggested by Claude

[Sh1bari]

@kabir merged, maybe it makes sense to add a checkstyle to follow conventions and automatically format the code? Or am I missing something?

[kabir]

@Sh1bari Checkstyle could be good, we use that in https://github.com/wildfly/wildfly but haven't got around to setting that up here.

Last year or so I worked on another project which I can't find now, where we used some other formatter which I can't remember (since I can't find the repository!). I think that wrapped the Google Code Formatter, but I found it a bit too opinionated and intrusive