Skip to content

Comments

feat(session): add ts_before and breakpoint params to Session.messages API#5

Open
ryanwyler wants to merge 3 commits intodevfrom
feature/load-additional-session-messages
Open

feat(session): add ts_before and breakpoint params to Session.messages API#5
ryanwyler wants to merge 3 commits intodevfrom
feature/load-additional-session-messages

Conversation

@ryanwyler
Copy link

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:

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 to Session.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_before correctly filters to messages older than timestamp
  • breakpoint=true stops at first compaction part
  • Combined parameters work together
  • Existing behavior unchanged when params omitted

@ryanwyler ryanwyler force-pushed the feature/load-additional-session-messages branch 3 times, most recently from 85a0f58 to a44b069 Compare January 17, 2026 04:00
…s API

Add optional parameters to Session.messages() for loading older messages:
- ts_before: filter to messages created before this timestamp
- breakpoint: stop at first compaction summary when true

This is a foundational API enhancement that enables clients to implement
pagination and history loading without breaking existing functionality.
Adds TUI integration for loading older messages in sessions with 100+ messages.

Implementation:
- loadConversationHistory(): Loads messages up to next compaction summary
- loadFullSessionHistory(): Loads entire remaining session history

UI Integration:
- Displays 'Load more messages' when 100+ messages present
- Two clickable options for conversation vs full history
- Toast notifications show count of messages loaded
- Uses synthetic message pattern for clean positioning

Depends on the ts_before and breakpoint API parameters added in the previous commit.
@ryanwyler ryanwyler force-pushed the feature/load-additional-session-messages branch from a44b069 to 8c332f9 Compare February 7, 2026 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant