feat(core): support reasoning and cached tokens in ChatUsage

[jujn]

Description

Close #1264

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 extends ChatUsage to expose advanced token metrics (reasoning and cached tokens) across model parsers, aggregators, and related tests to support improved cost/observability analysis (closes #1264).

Changes:

• Added optional reasoningTokens and cachedTokens fields to ChatUsage (constructor, builder, getters).
• Updated OpenAI/Gemini/DashScope/Anthropic response parsers and streaming/aggregation code to populate the new fields.
• Expanded unit tests to validate parsing and aggregation of the new token metrics.

Reviewed changes

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

Show a summary per file

File	Description
agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/tracing/telemetry/StreamChatResponseAggregator.java	Aggregates streaming ChatUsage including reasoning/cached token totals.
agentscope-core/src/main/java/io/agentscope/core/model/ChatUsage.java	Adds optional reasoningTokens/cachedTokens to the usage model (API + builder).
agentscope-core/src/main/java/io/agentscope/core/message/Msg.java	Updates getChatUsage() Javadoc example to include advanced token fields.
agentscope-core/src/main/java/io/agentscope/core/message/MessageMetadataKeys.java	Updates metadata key documentation to mention advanced token metrics.
agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIResponseParser.java	Extracts OpenAI nested cached_tokens / reasoning_tokens into ChatUsage.
agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiResponseParser.java	Adds Gemini reasoning/cached token extraction and stores it into ChatUsage.
agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/dto/DashScopeUsage.java	Extends DashScope DTO to include reasoning_tokens / cached_tokens.
agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeResponseParser.java	Maps new DashScope DTO usage fields into ChatUsage.
agentscope-core/src/main/java/io/agentscope/core/formatter/anthropic/AnthropicResponseParser.java	Extracts Anthropic cache read tokens into ChatUsage.cachedTokens.
agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java	Propagates reasoning/cached tokens into accumulated usage metadata.
agentscope-core/src/main/java/io/agentscope/core/agent/StructuredOutputHook.java	Aggregates reasoning/cached tokens across intermediate structured-output messages.
agentscope-core/src/test/java/io/agentscope/core/message/MsgTest.java	Adds test ensuring Msg.getChatUsage() preserves advanced token fields.
agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIResponseParserTest.java	Adds OpenAI parsing test for reasoning/cached tokens.
agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiResponseParserTest.java	Adds Gemini parsing test covering reasoning/cached token handling.
agentscope-core/src/test/java/io/agentscope/core/formatter/dashscope/DashScopeResponseParserTest.java	Adds DashScope parsing test for reasoning/cached tokens.
agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicResponseParserTest.java	Adds Anthropic parsing test for cached tokens (reasoning unsupported).
agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java	Updates accumulator tests to include reasoning/cached tokens.
agentscope-core/src/test/java/io/agentscope/core/agent/StructuredOutputHookTest.java	Adds aggregation test ensuring advanced tokens are summed correctly.
agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentTest.java	Updates test to validate ChatUsage advanced tokens propagate through agent flow.

Comments suppressed due to low confidence (1)

agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiResponseParser.java:105

• In Gemini usage parsing, outputTokens is computed as candidatesTokenCount - thoughtsTokenCount, meaning ChatUsage.outputTokens excludes reasoning while ChatUsage.reasoningTokens is set separately. Other parsers (e.g., OpenAIResponseParser) set outputTokens to the full completion tokens and treat reasoningTokens as a breakdown. This inconsistency makes ChatUsage hard to compare across providers and can make getTotalTokens() misleading for Gemini. Consider aligning semantics (e.g., keep outputTokens as total completion tokens and use reasoningTokens only as a breakdown, or apply the same exclusion rule everywhere and update docs/tests accordingly).

                int thinkingTokens = reasoningTokens != null ? reasoningTokens : 0;

                // Output tokens exclude thinking tokens (following DashScope behavior)
                // In Gemini, candidatesTokenCount includes thinking, so we subtract it
                int outputTokens = totalOutputTokens - thinkingTokens;

[codecov]

Codecov Report

❌ Patch coverage is 75.94937% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...racing/telemetry/StreamChatResponseAggregator.java	0.00%	10 Missing ⚠️
...pe/core/formatter/openai/OpenAIResponseParser.java	70.00%	4 Missing and 2 partials ⚠️
...scope/core/agent/accumulator/ReasoningContext.java	83.33%	0 Missing and 2 partials ⚠️
...pe/core/formatter/gemini/GeminiResponseParser.java	80.00%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!