Skip to content

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

ariane-emory and others added 30 commits January 15, 2026 01:04
Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
Co-authored-by: rekram1-node <[email protected]>
@ryanwyler ryanwyler force-pushed the feature/load-additional-session-messages branch from e086d9d to e55fcdf Compare January 17, 2026 00:44
@ryanwyler ryanwyler force-pushed the feature/load-additional-session-messages branch from e55fcdf to 85a0f58 Compare January 17, 2026 03:58
…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.
@ryanwyler ryanwyler force-pushed the feature/load-additional-session-messages branch from 85a0f58 to a44b069 Compare January 17, 2026 04:00
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.