From 3bafbf66dd69f53e885c7a5b432f59805e0f4fee Mon Sep 17 00:00:00 2001
From: Tyler Longwell <tlongwell@squareup.com>
Date: Sat, 21 Mar 2026 14:45:48 -0400
Subject: [PATCH] feat(messages): add `since` parameter to get_messages API and
 MCP tool

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).
---
 crates/sprout-db/src/lib.rs             |  2 ++
 crates/sprout-db/src/thread.rs          | 28 +++++++++++++++++++++----
 crates/sprout-mcp/src/server.rs         | 14 +++++++++++--
 crates/sprout-relay/src/api/messages.rs | 23 +++++++++++++++++---
 4 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/crates/sprout-db/src/lib.rs b/crates/sprout-db/src/lib.rs
index ca01f76f..052dc204 100644
--- a/crates/sprout-db/src/lib.rs
+++ b/crates/sprout-db/src/lib.rs
@@ -604,6 +604,7 @@ impl Db {
         channel_id: Uuid,
         limit: u32,
         before_cursor: Option<DateTime<Utc>>,
+        since_cursor: Option<DateTime<Utc>>,
         kind_filter: Option<&[u32]>,
     ) -> Result<Vec<thread::TopLevelMessage>> {
         thread::get_channel_messages_top_level(
@@ -611,6 +612,7 @@ impl Db {
             channel_id,
             limit,
             before_cursor,
+            since_cursor,
             kind_filter,
         )
         .await
diff --git a/crates/sprout-db/src/thread.rs b/crates/sprout-db/src/thread.rs
index decde54e..cec99c06 100644
--- a/crates/sprout-db/src/thread.rs
+++ b/crates/sprout-db/src/thread.rs
@@ -480,14 +480,19 @@ pub async fn get_thread_summary(pool: &PgPool, event_id: &[u8]) -> Result<Option
 /// - At depth 0 (root messages), OR
 /// - At depth 1 with `broadcast = true` (replies surfaced to the channel)
 ///
-/// Results are ordered newest-first for a standard channel view.
-/// `before_cursor` enables keyset pagination (pass the `created_at` of the
-/// last item from the previous page).
+/// Default ordering is newest-first (DESC). When `since_cursor` is provided
+/// without `before_cursor`, ordering flips to oldest-first (ASC) for
+/// chronological polling.
+///
+/// `before_cursor` enables backward keyset pagination (pass the `created_at`
+/// of the last item from the previous page). `since_cursor` enables forward
+/// polling (returns only messages created after the given timestamp).
 pub async fn get_channel_messages_top_level(
     pool: &PgPool,
     channel_id: Uuid,
     limit: u32,
     before_cursor: Option<DateTime<Utc>>,
+    since_cursor: Option<DateTime<Utc>>,
     kind_filter: Option<&[u32]>,
 ) -> Result<Vec<TopLevelMessage>> {
     let mut param_idx = 2u32; // $1 is channel_id
@@ -520,6 +525,11 @@ pub async fn get_channel_messages_top_level(
         param_idx += 1;
     }
 
+    if since_cursor.is_some() {
+        sql.push_str(&format!(" AND e.created_at > ${param_idx}"));
+        param_idx += 1;
+    }
+
     if let Some(kinds) = kind_filter {
         if !kinds.is_empty() {
             let list = kinds
@@ -531,13 +541,23 @@ pub async fn get_channel_messages_top_level(
         }
     }
 
-    sql.push_str(&format!(" ORDER BY e.created_at DESC LIMIT ${param_idx}"));
+    let order = if since_cursor.is_some() && before_cursor.is_none() {
+        "ASC"
+    } else {
+        "DESC"
+    };
+    sql.push_str(&format!(
+        " ORDER BY e.created_at {order} LIMIT ${param_idx}"
+    ));
 
     let mut q = sqlx::query(&sql).bind(channel_id);
 
     if let Some(cursor) = before_cursor {
         q = q.bind(cursor);
     }
+    if let Some(cursor) = since_cursor {
+        q = q.bind(cursor);
+    }
     q = q.bind(limit as i32);
 
     let rows = q.fetch_all(pool).await?;
diff --git a/crates/sprout-mcp/src/server.rs b/crates/sprout-mcp/src/server.rs
index f70078db..15890b1f 100644
--- a/crates/sprout-mcp/src/server.rs
+++ b/crates/sprout-mcp/src/server.rs
@@ -152,6 +152,11 @@ pub struct GetMessagesParams {
     /// Unix timestamp cursor for pagination. Returns messages before this time.
     #[serde(default)]
     pub before: Option<i64>,
+    /// Unix timestamp cursor. Returns messages created strictly after this time.
+    /// When used without `before`, results are ordered oldest-first (chronological).
+    /// Useful for polling: pass the timestamp of the last seen message to get only newer ones.
+    #[serde(default)]
+    pub since: Option<i64>,
     /// Comma-separated event kind numbers to filter by (e.g. "45001" for forum posts,
     /// "45002" for votes). When omitted, all kinds are returned.
     #[serde(default)]
@@ -1000,8 +1005,10 @@ Default kind is 9 (stream message)."
     /// Get recent messages from a Sprout channel.
     #[tool(
         name = "get_messages",
-        description = "Fetch recent top-level messages from a Sprout channel. Use `before` for pagination \
-(Unix timestamp). Use `kinds` to filter by event type (e.g. \"45001\" for forum posts, \
+        description = "Fetch recent top-level messages from a Sprout channel. Use `before` for backward \
+pagination and `since` for forward pagination (both Unix timestamps). When `since` is \
+provided without `before`, results are ordered oldest-first — useful for polling new \
+messages. Use `kinds` to filter by event type (e.g. \"45001\" for forum posts, \
 \"45002\" for votes). Thread summaries are included automatically. Threaded replies \
 are not returned — use `get_thread` to fetch the full reply tree for a specific message."
     )]
@@ -1024,6 +1031,9 @@ are not returned — use `get_thread` to fetch the full reply tree for a specifi
         if let Some(before) = p.before {
             query_parts.push(format!("before={before}"));
         }
+        if let Some(since) = p.since {
+            query_parts.push(format!("since={since}"));
+        }
         if let Some(ref kinds) = p.kinds {
             query_parts.push(format!("kinds={}", percent_encode(kinds)));
         }
diff --git a/crates/sprout-relay/src/api/messages.rs b/crates/sprout-relay/src/api/messages.rs
index af042d28..3a8e07db 100644
--- a/crates/sprout-relay/src/api/messages.rs
+++ b/crates/sprout-relay/src/api/messages.rs
@@ -10,7 +10,7 @@
 //!   - `state.db.insert_thread_metadata(...)` → thread::insert_thread_metadata
 //!   - `state.db.get_thread_replies(root_id, depth_limit, limit, cursor)` → thread::get_thread_replies
 //!   - `state.db.get_thread_summary(event_id)` → thread::get_thread_summary
-//!   - `state.db.get_channel_messages_top_level(channel_id, limit, before, kind_filter)` → thread::get_channel_messages_top_level
+//!   - `state.db.get_channel_messages_top_level(channel_id, limit, before, since, kind_filter)` → thread::get_channel_messages_top_level
 //!   - `state.db.get_thread_metadata_by_event(event_id)` → thread::get_thread_metadata_by_event
 //!   - `state.db.get_event_by_id(id_bytes)` → event::get_event_by_id  (already exists)
 //!   - `state.db.insert_event(event, channel_id)` → event::insert_event  (already exists)
@@ -949,6 +949,10 @@ pub struct ListMessagesParams {
     /// Pagination cursor — Unix timestamp (seconds). Returns messages created
     /// strictly before this time.
     pub before: Option<i64>,
+    /// Pagination cursor — Unix timestamp (seconds). Returns messages created
+    /// strictly after this time. Results are ordered oldest-first when `since`
+    /// is provided without `before`.
+    pub since: Option<i64>,
     /// Legacy parameter (thread summaries are now always included). Kept for backward compatibility.
     #[serde(default)]
     pub with_threads: bool,
@@ -957,7 +961,10 @@ pub struct ListMessagesParams {
     pub kinds: Option<String>,
 }
 
-/// List top-level messages in a channel (newest first).
+/// List top-level messages in a channel.
+///
+/// Default ordering is newest-first (DESC). When `since` is provided without
+/// `before`, ordering flips to oldest-first (ASC) for chronological polling.
 ///
 /// Returns root messages and broadcast replies. Thread summaries (reply counts,
 /// participant pubkeys) are always included. Thread replies themselves are excluded —
@@ -985,6 +992,10 @@ pub async fn list_messages(
         .before
         .and_then(|ts| chrono::DateTime::from_timestamp(ts, 0));
 
+    let since_cursor: Option<chrono::DateTime<Utc>> = params
+        .since
+        .and_then(|ts| chrono::DateTime::from_timestamp(ts, 0));
+
     let kind_filter: Option<Vec<u32>> = params
         .kinds
         .as_deref()
@@ -1003,7 +1014,13 @@ pub async fn list_messages(
 
     let mut messages = state
         .db
-        .get_channel_messages_top_level(channel_id, limit, before_cursor, kind_filter.as_deref())
+        .get_channel_messages_top_level(
+            channel_id,
+            limit,
+            before_cursor,
+            since_cursor,
+            kind_filter.as_deref(),
+        )
         .await
         .map_err(|e| internal_error(&format!("db error: {e}")))?;