fix(core): report the tool return value on ToolResultEndEvent

[King52HerTz]

Problem

ToolEmitter documents that "the emitted chunks do NOT affect what the LLM receives - only the tool method's return value is sent to the LLM." The event stream disagrees. Once a tool has emitted chunks its id lands in chunkedToolIds, emitToolResultDelta then skips the return value, and ToolResultEndEvent carries no result either — so a consumer rebuilding the tool message from the stream sees the concatenated progress text.

For AG-UI that means TOOL_CALL_RESULT holds progress text while the model received the return value:

• a client resending full history without server-side memory feeds progress text back as the tool result, contradicting the emitter contract;
• anything emitted only for the UI (a one-time code, say) leaks into model-visible history;
• a client showing the operation's outcome shows the wrong thing.

Reproduced from the issue with the reporter's scenario in AguiAgentAdapterV2Test.

Change

ToolResultEndEvent gains finalResultText, populated by ReActAgent from the tool result's text blocks, and AguiStreamContext.endToolResult prefers it over the accumulated delta buffer. Progress chunks still stream as deltas, so UIs that want them can render them — the difference is that the closed result is now the value the model saw.

Why a field and not metadata. My first attempt put this under AgentEvent.getMetadata(). That map passes the tool result's own metadata through unchanged, and ReActAgentNewLoopE2ETest.toolResultMetadataPropagatesToEvents asserts it by exact equality — injecting a framework key there breaks it. That test failed on the first draft, so the value now travels on a dedicated field and the metadata map is untouched.

The @JsonCreator gained an optional finalResultText property; payloads without it deserialize to null, and the two existing constructors delegate unchanged. When no return value is reported the previous buffer behaviour is preserved, so other producers are unaffected.

Scope

Results with no text blocks yield null and fall back to the delta buffer rather than reporting an empty result.

Testing

Two cases added: progress deltas plus a reported return value yields the return value; a bare ToolResultEndEvent still yields the buffered deltas.

mvn test -pl :agentscope-core,:agentscope-harness,:agentscope-extensions-agui -am
# core 2492 / harness 509 / agui 1062 tests, 0 failures

Partially addresses #3312

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/src/main/java/io/agentscope/core/ReActAgent.java	90.00%	1 Missing ⚠️
...a/io/agentscope/core/event/ToolResultEndEvent.java	85.71%	1 Missing ⚠️
.../core/agui/adapter/strategy/AguiStreamContext.java	95.83%	0 Missing and 1 partial ⚠️
...tscope/builder/web/managed/SessionEventMapper.java	96.15%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[King52HerTz]

All three warnings are addressed in 0e94997, along with both [Info] points. One limitation is called out at the bottom rather than papered over.

1. ReActAgent.java:3525 — null conflated two states.

finalToolResultText now reports the join of the text blocks whenever the result carries content blocks — including when that join is empty — and returns null only when there is nothing to report from. So an image-only or blank return value no longer reads as "the producer reported nothing" and no longer falls back to the delta buffer, which is the case you identified as re-opening the leak. ToolResultEndEvent.getFinalResultText()'s contract is written down: "" is a reported value, null is the absence of one.

2. AguiStreamContext.java:311 — authoritative text dropped non-text blocks.

appendToolResultData now records each serialised block alongside the buffer, and endToolResult re-appends those blocks after the authoritative text instead of discarding them. The fallback path is unchanged byte-for-byte, including the arrival-order rendering pinned by testToolResultTextAndDataDeltasAreJoinedInArrivalOrder ("hel\nstructuredlo"). Two new cases cover the multimodal shape: text + image with a reported return value, and image-only with "".

3. ToolResultEndEvent.java:40 — the two first-party consumers disagreed.

service-dataplane's SessionEventMapper applies the same rule through ToolResultBuffer.applyFinalResultText(...): the return value replaces the accumulated text, non-text fragments are re-appended in the way that module already glued them, null keeps the previous buffered output untouched, and the shared 64K payload cap still decides truncation so truncated / originalSize describe what was actually persisted.

[Info] — JSON round trip. Three cases in AgentEventStreamTest exercise the polymorphic decode that RemoteEventCodec and session persistence use: the property survives, "" decodes as "" rather than null, and a payload written before the field existed decodes to null.

[Info] — population path untested. Two ReActAgentNewLoopE2ETest cases run a real loop with a tool that emits one progress chunk and then returns a value; the first asserts the progress chunk actually reached the stream before asserting the result excludes it, so the test cannot pass by the tool never emitting.

One limit I did not resolve. A streaming tool that emits progress as image/data blocks will still have those blocks appear in the result. ToolResultDataDeltaEvent is shared by the result-delta path (emitToolResultDelta) and the chunk-callback path, and nothing on the wire distinguishes them, so the adapter cannot tell "result part" from "progress part" today. Between dropping every multimodal result and keeping the pre-PR behaviour for that one shape, I kept the latter. If you would rather distinguish them at the source, the natural seam is a marker on the chunk-path events — which is a larger change than this PR and I did not want to fold it in silently.

Evidence. Four mutations each fail exactly the tests that guard them: reverting the empty-vs-null rule → 1; never populating the field → 2; dropping the re-append in the AG-UI adapter → 2; reverting the dataplane rule → 2. Full reactor mvn test green and spotless:check green locally.

[jujn]

从可维护性角度来说，我们是否可以新增一个ToolProgressEvent事件传递工具进度
（ToolResult*DeltaEvent本就只应传递工具结果）：

ToolResultStartEvent
ToolProgressEvent          // ToolEmitter 的 progress
ToolProgressEvent
ToolResultTextDeltaEvent   // 只表示最终结果
ToolResultDataDeltaEvent   // 只表示最终结果
ToolResultEndEvent