opencode
opencode copied to clipboard
feat(session): add ts_before and breakpoint params to Session.messages API
Summary
Adds two optional parameters to Session.messages() API for loading messages older than the initial 100-message window:
-
ts_before: Unix timestamp - returns messages created before this point -
breakpoint: Boolean - when true, stops at the first compaction summary
Problem
Multiple open issues request the ability to access message history beyond the initial 100-message limit:
- Resolves #6137 - Cannot scroll to beginning of long conversations
- Resolves #4918 - Feature request: pagination for messages & sessions
- Resolves #7380 - Old messages disappear
- Related #6548 - Pagination work
Current Session.messages() only supports a limit parameter, which returns the N most recent messages. There is no way to retrieve older messages.
Solution
This PR adds the foundational server-side API enhancement required by all proposed solutions. The implementation is minimal (8 lines of core logic) and non-breaking:
Core changes:
-
packages/opencode/src/session/index.ts- Add params toSession.messages()schema and iteration logic -
packages/opencode/src/server/routes/session.ts- Expose params in HTTP API
Why this approach:
- Timestamp-based anchoring uses immutable reference points, eliminating state management complexity and race conditions that offset-based pagination would introduce
- Breakpoint support enables "load conversation history" (stop at compaction) vs "load full session" (ignore compactions) use cases
- Zero breaking changes - all parameters optional, existing functionality unchanged
- Prerequisite for all solutions - whether TUI, web client, or SDK consumers implement history loading, they all need this server capability
Usage
# Get messages before a timestamp
GET /session/{id}/message?ts_before=1768609939954
# Get messages before timestamp, stopping at first compaction
GET /session/{id}/message?ts_before=1768609939954&breakpoint=true
# Combine with limit
GET /session/{id}/message?ts_before=1768609939954&limit=50
Testing
Verified against sessions with 170+ messages and multiple compactions:
-
ts_beforecorrectly filters to messages older than timestamp -
breakpoint=truestops at first compaction part - Combined parameters work together
- Existing behavior unchanged when params omitted