agentscope-ai / agentscope-ai/agentscope-java
[Feature]: Add stable session entry identity and exact history recall
- Dominant language
- Java
- Stars
- 5.6k
- Forks
- 1.3k
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 77
Description
## Motivation
Harness currently provides `session_search` and `session_history` for discovering prior conversations. The history output is intentionally preview-oriented, which works well for navigation, but there is no stable public contract for expanding one discovered entry back to its exact persisted content.
This becomes important after conversation compaction or tool-result eviction. An agent can discover that a prior turn exists, but cannot reliably request the complete persisted entry by a stable identifier. Product hosts should not need to parse Harness runtime files or maintain a second session/memory index to provide this behavior.
Related work such as #1042, #1523, #1682, and #1695 covers context compression, offloading, or eviction correctness, but does not appear to expose exact per-entry history expansion.
## Current behavior / gap
- `session_history` returns role/message metadata and a bounded preview.
- Persisted session log entries do not expose a stable, physical entry identifier suitable for a follow-up exact-read request.
- There is no read-only Harness tool/API to expand exactly one history entry without replaying or loading the whole session.
- When a tool result has been replaced by an eviction placeholder, session-history consumers do not have a typed, stable contract for optionally retrieving the original persisted result.
- Implementing these features in a product host would duplicate session, memory, workspace-namespace, and recovery ownership outside Harness.
## Proposed public contract
I would like to discuss a phased Harness-owned API:
### Phase 1: stable entry identity and exact expansion
1. Assign or expose a stable `entry_id` (and, if useful, an append sequence) for each append-only session-log entry.
2. Include `entry_id` in `session_search` / `session_history` results.
3. Add a read-only exact expansion operation, for example:
```text
session_history_entry(session_id, entry_id)
```
The exact name and whether this is a separate tool or an option on `session_history` are open for discussion.
Expected properties:
- Returns one complete persisted entry without preview truncation.
- Preserves existing user/session namespace isolation.
- Works after compaction because the source is the append-only session history rather than the compacted model context.
- Works with local and remote/distributed workspace implementations.
- Skips or reports malformed records safely.
- Remains read-only and does not mutate active agent context.
### Phase 2: optional full evicted tool-result recall
If maintainers agree, eviction metadata could preserve a typed reference to the original result artifact. Exact entry expansion could then optionally return the original full tool result, for example through `full_tool_result=true`, while keeping namespace and filesystem access inside Harness.
This phase can be a separate PR because it touches eviction persistence and may require a different API design.
## Compatibility and implementation notes
- Existing preview behavior and tool signatures should remain backward compatible.
- Exact expansion should be opt-in so large historical payloads are not injected accidentally.
- The implementation should use the configured Harness workspace/filesystem abstraction, not direct local filesystem access.
- Recall tools themselves may need exclusion from tool-result eviction to avoid immediately replacing the recalled payload with another placeholder.
- No new external dependency should be required.
## Validation proposal
Tests should cover:
- stable IDs across reload/restart;
- exact expansion before and after compaction;
- same-user cross-session lookup where currently supported;
- cross-user isolation;
- remote/distributed workspace behavior;
- malformed append-log rows;
- interrupted/reactive reads;
- optional restoration of an evicted full tool result (Phase 2).
## Questions
1. Would maintainers prefer a new `session_history_entry` tool, or an exact mode on `session_history`?
2. Should `entry_id` be persisted explicitly, or derived from an immutable append position?
3. Is restoring evicted tool results in scope for the session-history tool, or should it be a separate artifact-read API/tool?
I have a working prototype and tests locally, but would like to align on the public contract and split before opening a PR.
Contributor guide
Assessment
This issue has not been assessed yet.