refactor(agui): redesign event dispatching with strategy pattern and deferred queue

[jujn]

Description:
Closes #1347, #1222 and #1382

This PR implements the architectural refactoring proposed in Issue 1347, bringing a strategy-based dispatcher to the AG-UI adapter and natively supporting AG-UI custom events.

Code Changes & Architecture

1. Refactored AguiAgentAdapter: Replaced the massive if-else block with a BlockEventConverter strategy interface. The adapter now acts as a clean router (O(1) dispatching based on Block class).
2. Introduced StreamContext: Replaced the heavy Set-based state tracking with a lightweight context. It uses a Deferred Queue mechanism (delaying End events until termination or interruption), completely resolving lifecycle mismatch bugs and tail-end data loss.
3. Added BlockEventConverter Implementations: Logic for TextBlock, ThinkingBlock, ToolUseBlock, and ToolResultBlock are now beautifully isolated in their own classes.

Introducing CustomBlock

To fully support the AG-UI CUSTOM event protocol without hacky workarounds, this PR introduces CustomBlock into the agentscope-core\message package.

• Architectural Note: While placing CustomBlock in the core-message package introduces a slight coupling with frontend concepts, AG-UI has effectively become one of the three foundational interaction protocols for modern Agents. A generic CustomBlock (containing just name and value) is agnostic enough to serve as a universal side-channel for Agent-to-UI communications (e.g., real-time tool execution progress, workflow status changes). Strongly recommend this inclusion for developer experience.
• Implemented CustomBlockConverter: Translates CustomBlock into stateless AG-UI Custom events dynamically.

Resolves

• Fixes [Feature]: [功能建议] AGUI 中支持长时间运行的工具实时反馈执行情况 #1222 (Developers can now easily emit CustomBlock.of("tool_progress", "50%") from long-running tools, perfectly resolving the real-time feedback issue without polluting the Reasoning blocks).

Testing

• Added testRunWithCustomEventForToolProgress in AguiAgentAdapterTest to verify that stateless custom events do not interfere with the lifecycle of main streaming blocks (Text/Tool).
• All existing unit tests pass smoothly, proving backward compatibility.

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

[Copilot]

Pull request overview

This PR refactors the AG-UI adapter’s streaming event conversion to use a strategy-based dispatch model with a dedicated StreamContext that supports deferred “end” events, and extends the core message model with a CustomBlock to enable emitting AG-UI CUSTOM events.

Changes:

• Refactors AguiAgentAdapter to dispatch ContentBlock conversion via BlockEventConverter strategies and manage lifecycle/end-event ordering via StreamContext.
• Adds block converters for text, thinking/reasoning, tool use/results, and custom blocks under adapter.strategy.
• Introduces CustomBlock as a new ContentBlock subtype and wires it into Jackson polymorphic serialization; updates AG-UI adapter tests for revised lifecycle behavior.

Reviewed changes

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

Show a summary per file

File	Description
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java	Refactors the adapter to strategy-based block conversion and deferred end-event flushing.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/StreamContext.java	Adds a context object to track active lifecycles and queue/flush deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/BlockEventConverter.java	Introduces the strategy interface for block→event conversion.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/TextBlockConverter.java	Implements text block conversion with lifecycle tracking and deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ThinkingBlockConverter.java	Implements reasoning conversion (when enabled) with lifecycle tracking and deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ToolUseBlockConverter.java	Implements tool call start/args conversion and interrupts active text/reasoning lifecycles.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ToolResultBlockConverter.java	Implements tool result conversion and ensures tool call closure semantics.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/CustomBlockConverter.java	Implements CustomBlock→AG-UI CUSTOM event emission.
agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java	Updates test expectations for the new lifecycle/event ordering behavior.
agentscope-core/src/main/java/io/agentscope/core/message/CustomBlock.java	Adds a new ContentBlock subtype for custom extension payloads.
agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java	Registers CustomBlock in the sealed hierarchy and Jackson subtype mapping.

[codecov]

Codecov Report

❌ Patch coverage is 81.98198% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...n/java/io/agentscope/core/message/CustomBlock.java	0.00%	13 Missing ⚠️
...gui/adapter/strategy/ToolResultBlockConverter.java	76.47%	2 Missing and 6 partials ⚠️
...io/agentscope/core/agui/adapter/StreamContext.java	93.05%	2 Missing and 3 partials ⚠️
.../agui/adapter/strategy/ThinkingBlockConverter.java	78.26%	1 Missing and 4 partials ⚠️
...e/agui/adapter/strategy/ToolUseBlockConverter.java	83.33%	1 Missing and 3 partials ⚠️
...core/agui/adapter/strategy/TextBlockConverter.java	86.36%	0 Missing and 3 partials ⚠️
...agentscope/core/agui/adapter/AguiAgentAdapter.java	93.10%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!