fix(agent): evict persistence-backed session caches

[vowor]

AgentScope-Java Version

2.0.1-SNAPSHOT

Summary

• evict persistence-backed per-session state and permission-engine cache entries when each call terminates
• make cleanup exact-scope and concurrency-safe across success, error, and cancellation paths
• add explicit session/user eviction APIs and clear caches when the agent closes
• preserve the existing authoritative in-memory behavior when no state store is configured

Root cause

When an AgentStateStore was configured, every session was loaded into stateCache and permissionEngineCache, but completed calls never removed those entries. Long-running multi-user services therefore retained one cache entry per observed session indefinitely. Cleanup also could not safely rely on shared agent fields because concurrent calls may have advanced them to a different session.

Implementation

AgentBase now exposes a terminal callback tied to the exact call scope returned by beforeAgentExecution. ReActAgent uses that scope to conditionally remove only the state and permission-engine instances owned by the completed call. Conditional map removal prevents an older call from evicting a newer replacement for the same slot.

The new evictSession and evictUser methods provide explicit host-controlled cleanup, while close() clears both caches. Persistence is not deleted; subsequent access reloads state from the configured store.

Verification

• full 82-module Maven reactor passed with no failures: mvn test (local macOS runner used headless AWT and a preloaded Mockito agent)
• agentscope-core: 2,222 tests passed, 9 skipped
• focused lifecycle/cache suite: 13 tests passed
• Spotless checks passed
• new production lines and branches are covered by the added tests

Fixes #2261

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[oss-maintainer]

LGTM. Changes look good.

---

Automated review by github-manager-bot

[oss-maintainer]

⚠️ Merge conflict detected

This PR has conflicts with the base branch and cannot be merged. Please rebase or merge the base branch into your branch and resolve the conflicts:

git fetch origin
git checkout agent/fix-state-cache-eviction
git rebase origin/main
# resolve conflicts, then:
git push --force-with-lease

This is a one-time reminder. Feel free to @mention me for a re-review after conflicts are resolved.

---

Automated notification by github-manager-bot

[vowor]

@oss-maintainer The merge conflict has been resolved, and the CI formatting issue has also been fixed. Could you please re-review the PR when you have a chance? Thanks!