fix(agui): add metadata field to AguiMessage for HITL confirm results

[Blue-Berrys]

Summary

• Add optional metadata to AguiMessage (JSON-compatible, backward compatible).
• Map metadata bidirectionally in AguiMessageConverter so agentscope_confirm_results can reach Msg.metadata.
• Add converter regression tests for HITL confirm metadata.

Closes #1726

Description

AG-UI messages previously had no metadata channel, so frontends could not attach HITL ConfirmResults under agentscope_confirm_results. This blocked permission confirmation over AG-UI.

Checklist

• Code has been formatted with mvn spotless:apply
• Targeted tests pass (AguiMessageConverterTest, 26 tests)
• Related documentation has been updated (N/A)
• Code is ready for review

Testing

JAVA_HOME=/path/to/jdk21 mvn \
  -pl agentscope-extensions/agentscope-extensions-protocol/agentscope-extensions-agui -am \
  -Dspotless.check.skip=true \
  -Dtest=AguiMessageConverterTest,AguiModelTest \
  -Dsurefire.failIfNoSpecifiedTests=false \
  test

[CLAassistant]

All committers have signed the CLA.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[oss-maintainer]

Review — Approved ✅

This addresses the critical HITL confirmation gap in the AG-UI adapter (#2437, #1726).

Code analysis:

• Adding metadata as an optional Map<String, Object> field to AguiMessage is the right approach — it's the natural place for HITL confirm results without disrupting the existing message model.
• Backward compatibility is well handled: existing 5-arg constructor delegates to the new 6-arg one with null metadata. All static factory methods updated.
• Immutable map wrapping (Collections.unmodifiableMap(new LinkedHashMap<>(...))) is correct.
• @JsonInclude(JsonInclude.Include.NON_EMPTY) ensures metadata doesn't pollute serialized output when absent.
• equals()/hashCode()/toString() all properly updated.

Converter:

• Bidirectional metadata transfer in toMsg() and toAguiMessage() is clean and null-safe.

Tests:

• Roundtrip tests for metadata in both directions + empty metadata edge case. Good coverage.

This is the missing bridge for RequireUserConfirmEvent mentioned in #2437. Well done.

LGTM. Please sign the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 67.92453% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...cope/harness/agent/memory/session/SessionTree.java	53.84%	10 Missing and 2 partials ⚠️
...ava/io/agentscope/core/agui/model/AguiMessage.java	80.00%	0 Missing and 3 partials ⚠️
...cope/core/agui/converter/AguiMessageConverter.java	71.42%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!