fix(state): bound persisted session context

[guslegend0510]

Summary

• Add maxPersistedContextMessages to limit the number of recent conversation messages stored in persisted agent_state snapshots.
• Keep the live runtime context unchanged while trimming only the persistence snapshot.
• Add deleteSessionState(...) APIs so applications can explicitly remove persisted session data and local state caches.
• Expose the new configuration and cleanup APIs through HarnessAgent.
• Add English and Chinese documentation for standalone AgentStateStore and DistributedStore usage.

The default remains unlimited for backward compatibility. Setting maxPersistedContextMessages to 0 persists non-conversation agent state without storing conversation messages.

Testing

• mvn -pl agentscope-core -Dtest=ReActAgentPerSessionStateTest test
• mvn -pl agentscope-harness -am -Dtest=HarnessAgentTest -Dsurefire.failIfNoSpecifiedTests=false test
• mvn -pl agentscope-core test

Full core test result: 2,213 tests passed, 0 failures, 0 errors, 9 skipped.

Fixes #2173

[codecov]

Codecov Report

❌ Patch coverage is 72.91667% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/src/main/java/io/agentscope/core/ReActAgent.java	78.04%	7 Missing and 2 partials ⚠️
...java/io/agentscope/harness/agent/HarnessAgent.java	42.85%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR adds two features to ReActAgent:

1. maxPersistedContextMessages — limits the number of recent conversation messages stored in persisted agent_state snapshots, preventing unbounded storage growth for long sessions. Trimming only affects the persistence snapshot, not the live runtime context.
2. deleteSessionState(...) — public API allowing applications to explicitly delete persisted session data and clean local caches.

Changes are well-scoped, code style consistent with project conventions, tests cover core paths and edge cases (negative limit rejection, auto-persistence trimming, post-delete cache eviction), and documentation is provided in both English and Chinese. The PR directly addresses issue #2173.

[AgentScopeJavaBot]

🤖 AI Review

This PR adds two features to ReActAgent:

1. maxPersistedContextMessages — limits the number of recent conversation messages stored in persisted agent_state snapshots, preventing unbounded storage growth for long sessions. Trimming only affects the persistence snapshot, not the live runtime context.
2. deleteSessionState(...) — public API allowing applications to explicitly delete persisted session data and clean local caches.

Changes are well-scoped, code style consistent with project conventions, tests cover core paths and edge cases (negative limit rejection, auto-persistence trimming, post-delete cache eviction), and documentation is provided in both English and Chinese. The PR directly addresses issue #2173.

[oss-maintainer]

Summary

Adds maxPersistedContextMessages to limit conversation messages stored in persisted agent_state snapshots, while keeping live runtime context unchanged. Also adds deleteSessionState APIs for explicit cleanup.

Findings

• [Info] Trimming only persistence snapshot, not live context. Correct separation.
• [Info] Default unlimited for backward compatibility. Good.
• [Info] Setting to 0 persists non-conversation state without messages. Useful for stateless agents.
• [Info] deleteSessionState APIs exposed through HarnessAgent. Good.
• [Info] Documentation added for standalone AgentStateStore and DistributedStore usage. Good.
• [Info] 2213 tests passed. Excellent.

Verdict

Important fix for Redis/Postgres state bloat. LGTM.

---

Automated review by github-manager