feat(core): add session context clear API

[zouyx]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Closes #2496.

Adds a public clearContext API to ReActAgent and HarnessAgent, allowing callers to clear a session's model-visible conversation context without creating a new session.

Changes included:

• Clears the conversation message buffer and compaction summary for a specified (userId, sessionId).
• Persists the cleared state immediately when an AgentStateStore is configured.
• Preserves the existing session ID and non-conversation state, including permissions, tool state, tasks, and Plan Mode state.
• Supports both RuntimeContext and explicit (userId, sessionId) overloads.
• Adds tests for session isolation, persistence, and RuntimeContext targeting.
• Updates the English and Chinese Context documentation.

clearContext does not cancel an in-flight call. It should be invoked after the active request completes; the next call will use the cleared conversation context.

Checklist

• Code formatting checked with Spotless
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated
• Code is ready for review

Validation

• mvn -pl agentscope-core -Dtest=ReActAgentPerSessionStateTest test
• mvn -pl agentscope-harness -am -DskipTests compile

[gemini-code-assist]

Caution

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

[Copilot]

Pull request overview

This PR introduces a public clearContext API to clear a session’s model-visible conversation state (messages + compaction summary) while preserving the existing (userId, sessionId) and other non-conversation state, and documents the new behavior in both English and Chinese.

Changes:

• Add clearContext(RuntimeContext) and clearContext(userId, sessionId) to ReActAgent, persisting immediately when an AgentStateStore is configured.
• Expose the same API on HarnessAgent via delegation.
• Document the new API in v2 English/Chinese docs and add per-session tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java	Adds the core clearContext API and persists via AgentStateStore when present.
agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java	Adds clearContext passthrough methods for harness users.
agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentPerSessionStateTest.java	Adds tests for isolation, persistence, and RuntimeContext targeting of clearContext.
docs/v2/en/docs/building-blocks/context.md	Documents how to clear conversation context without starting a new session.
docs/v2/zh/docs/building-blocks/context.md	Chinese documentation for the new clearContext API and usage guidance.

Comments suppressed due to low confidence (1)

agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentPerSessionStateTest.java:139

• This test intends to verify that clearContext persists immediately, but InMemoryAgentStateStore.save(...) stores AgentState by reference (no deep copy). Since the test saves sessA before clearing, mutating the cached AgentState will also mutate the already-saved instance, so the "reborn" agent can observe the cleared state even if clearContext forgets to call saveAgentState. Add an explicit assertion that a store save happens during clearContext (e.g., by wrapping the store and counting saves), or use a store implementation that round-trips through serialization (e.g. JsonFileAgentStateStore).

        Toolkit toolkit = new Toolkit();
        toolkit.createToolGroup("default-active", "Enabled during agent construction");
        ReActAgent agent =
                ReActAgent.builder()
                        .name("asst")
                        .sysPrompt("hi")
                        .model(new NoopModel())
                        .toolkit(toolkit)
                        .stateStore(store)
                        .build();

        assertTrue(
                agent.getAgentState("u1", "legacy-empty")
                        .getToolContext()

[zouyx]

I think it doesn't matter.
Because in ReActAgent.clearContext method will be compatible this case.

[codecov]

Codecov Report

❌ Patch coverage is 89.47368% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/src/main/java/io/agentscope/core/ReActAgent.java	89.47%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[jujn]

同一个 (userId, sessionId) 可能被多个 Agent 实例访问。PR 承诺“只清 conversation，保留 non-conversation state”。
但 getAgentState(...) 返回的是当前实例自己的缓存对象。如果这个缓存已经落后于 store 里的最新状态，后面的 saveAgentState(...) 会把这个“旧对象”整份写回去，就可能把别人已经更新过的非对话状态一起回滚掉。

[zouyx]

调整了一下

[jujn]

可以先用 loadOrCreateAgentStateForSlot(...) 取最新状态嘛？（当前实例缓存可能是旧的）