Skip to content

feat(messages): add since parameter to get_messages API and MCP tool#154

Open
tlongwell-block wants to merge 1 commit intomainfrom
feat/messages-since-param
Open

feat(messages): add since parameter to get_messages API and MCP tool#154
tlongwell-block wants to merge 1 commit intomainfrom
feat/messages-since-param

Conversation

@tlongwell-block
Copy link
Collaborator

Summary

Adds forward pagination to the channel messages endpoint, enabling agents to poll for new messages since a given timestamp. Mirrors the existing before parameter pattern.

Motivation

Agent orchestration in Sprout requires polling for new messages. Without since, agents must re-read the entire recent message window on every poll and diff against what they've already seen. With since, the polling loop becomes clean and stateless:

get_messages(channel_id, since=last_seen_timestamp) → only new messages

This is the per-channel equivalent of get_feed's existing since parameter.

Changes

File Change
sprout-db/src/thread.rs Add since_cursor param to get_channel_messages_top_level; AND e.created_at > $N clause; conditional ORDER BY (ASC when since-only)
sprout-db/src/lib.rs Passthrough wrapper update
sprout-relay/src/api/messages.rs Add since: Option<i64> to ListMessagesParams; parse and pass to DB
sprout-mcp/src/server.rs Add since: Option<i64> to GetMessagesParams; update tool description; add to query builder

No schema changes. No new indexes. The existing idx_events_channel_created covers both directions.

Behavior

  • since without before: returns messages created strictly after the timestamp, ordered oldest-first (ASC) for chronological consumption
  • before without since: existing behavior, newest-first (DESC)
  • Both since and before: bounded window, newest-first (DESC)
  • Neither: existing behavior, newest-first

Naming

Uses since to match:

  • NIP-01 subscription filter convention (since/until)
  • Sprout's existing get_feed tool (since parameter)
  • The subscriptions table (filter_since/filter_until columns)

Review

Codex CLI review: 9/10, APPROVE

  • SQL injection: safe — all values are bound parameters
  • Bind order: correct — placeholder numbering matches runtime bind sequence
  • ORDER BY: correct — ASC only when since-only, DESC otherwise
  • Edge cases: both/neither/negative/zero all handled
  • Docs: aligned across DB, REST, and MCP layers

Residual note from reviewer: invalid out-of-range timestamps are silently treated as None (pre-existing pattern from before, not introduced here).

Adds forward pagination to the channel messages endpoint, enabling agents
to poll for new messages since a given timestamp. Mirrors the existing
`before` parameter pattern.

When `since` is provided without `before`, results are ordered
oldest-first (ASC) for chronological consumption. When both are provided
or only `before`, ordering remains newest-first (DESC).

Changes:
- sprout-db: add since_cursor param to get_channel_messages_top_level
- sprout-relay: add since query param to GET /api/channels/:id/messages
- sprout-mcp: add since field to GetMessagesParams, update tool description

Naming follows NIP-01 convention (since/until) and matches the existing
get_feed tool's since parameter. No schema changes or new indexes needed.

Codex CLI review: 7/10, SQL injection safe, bind order correct, ORDER BY
logic correct. One pre-existing pattern noted (invalid timestamps silently
ignored, consistent with existing before behavior).
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.

2 participants