feat(rpc): add rowid-forward message pagination

[vincentkoc]

Problem

OpenClaw startup catchup currently has to approximate forward progress through messages.history, which is newest-first and capped at 500 rows. Equal timestamps and larger backlogs make a durable cursor ambiguous.

Proposed contract

Add an additive JSON-RPC method, messages.after, with:

• required non-negative since_rowid, exclusive
• optional positive chat_id; omit it to page across all chats
• limit default 100, maximum 500
• optional attachments, convert_attachments, and include_reactions booleans
• stable message.ROWID ASC ordering
• next_rowid as the authoritative physical scan cursor
• has_more computed from the database/page boundary, not from result count

The default page is user-visible message catchup and may coalesce or suppress URL-preview rows while still advancing next_rowid. Callers that need the cursor to cover standalone reaction events set include_reactions: true.

Validation

Cover more than 500 equal-timestamp rows, optional chat filtering over interleaved rows, reactions, attachment payload parity, URL-preview coalescing across page boundaries, empty suppressed pages, and strict parameter validation.

Downstream consumer: openclaw/openclaw#116961

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 2, 2026, 12:41 PM ET / 16:41 UTC.

Summary
This member-authored feature request remains necessary: current main has the internal ROWID-forward database scan, but it does not expose the requested durable messages.after JSON-RPC contract. The linked open pull request already owns implementation, so this should stay open for a maintainer decision on the public cursor contract rather than receive a duplicate repair. Likely related people: Peter Steinberger is the high-confidence routing candidate from the original forward-scan and current RPC history.

Reproducibility: not applicable. as a failing-bug reproduction: this requests a new public RPC capability. Current-main source confirms the proposed capability is absent while the underlying ROWID scan already exists internally.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Maintainer decision needed

Question	Recommendation
Should imsg make messages.after a supported public JSON-RPC contract with durable physical cursor semantics for downstream startup catch-up?	Sponsor the additive RPC contract: Approve a narrowly documented messages.after API and have the linked pull request refreshed against current main with compatibility-focused tests.

Why: The core scan exists, but choosing the externally stable meaning of next_rowid, has_more, suppressed rows, and reaction inclusion is an API product and compatibility decision rather than a mechanical bug repair.

Next step
An open pull request already owns the implementation, and a maintainer must first decide whether to support the proposed public cursor contract.

Review details

Best possible solution:

Adopt one documented, additive cursor contract only if maintainers want imsg to guarantee durable catch-up pagination, then rebase and review the linked implementation with focused boundary tests for cursors, filtering, reactions, and URL-preview suppression.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a failing-bug reproduction: this requests a new public RPC capability. Current-main source confirms the proposed capability is absent while the underlying ROWID scan already exists internally.

Is this the best way to solve the issue?

Unclear until maintainer direction: exposing a durable cursor is the maintainable path only if maintainers intend to support those semantics as a public compatibility commitment; the linked pull request is the appropriate implementation vehicle if sponsored.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A public next_rowid/has_more contract becomes durable downstream API surface, so its behavior for filtered rows, URL-preview coalescing, reactions, and empty emitted pages needs explicit maintainer approval before merge.
• The linked implementation is an open draft with a dirty merge state in the supplied GitHub context, so it needs a refreshed review/rebase after the API direction is confirmed.

Codex review notes: model internal, reasoning high; reviewed against 5bdd2b0b003a.

Label changes

Label justifications:

• P3: This is a bounded additive API proposal rather than a confirmed regression, security problem, or currently broken core workflow.
• impact:other: The missing durable pagination contract materially affects downstream catch-up integration but does not fit the owned data-loss, delivery, session, auth, or availability categories.

Evidence reviewed

What I checked:

• Current RPC surface lacks the requested method: The dispatcher recognizes messages.history but no messages.after method, and the history handler requires chat_id and returns only a messages array. A repository-wide search found no messages.after RPC handler, documentation, or RPC test on current main. (Sources/imsg/RPCServer.swift:169, 5bdd2b0b003a)
• Internal scan establishes the implementation boundary, not the public contract: MessageStore already provides forward ROWID scanning and the query orders rows by m.ROWID ASC; however, its public convenience method skips suppressed empty batches rather than returning the requested authoritative scan cursor and has_more result. (Sources/IMsgCore/MessageStore+Messages.swift:99, 5bdd2b0b003a)
• Existing documented history behavior is materially different: The RPC documentation describes messages.history as requiring chat_id, while watch.subscribe accepts an optional since_rowid; neither documents a paged all-chat catch-up response with next_rowid and has_more. (docs/rpc.md:67, 5bdd2b0b003a)
• Forward-scan provenance: Commit d9bd9c754d50657c5e1b1083d39414ee7ec0e076 introduced MessageStore+Messages.swift, MessageStore+Queries.swift, and MessageWatcher.swift, including the current messagesAfter and ROWID-forward query path. The behavior appears to date to Peter Steinberger’s July 9, 2026 feature work. (Sources/IMsgCore/MessageStore+Messages.swift:90, d9bd9c754d50)
• Release and current-main check: The current main commit contains release v0.13.4, and there is no diff from that release to current main in the core/RPC/documentation files relevant to this request; the requested RPC was not subsequently added to main. (Sources/imsg/RPCServer+Handlers.swift:57, 5bdd2b0b003a)
• Linked implementation remains open: The supplied GitHub context shows an open draft pull request that formally closes this issue and proposes the complete API contract. It is the implementation candidate, not evidence that this issue is resolved. (b61a3c95bcc3)

Likely related people:

• Peter Steinberger: Peter authored the July 9, 2026 commit that added the current ROWID-forward MessageStore path and is the dominant contributor in the inspected message/RPC history; current relevant lines also trace through the v0.13.4 release preparation commit. (role: introduced forward-scan behavior and recent RPC-area contributor; confidence: high; commits: d9bd9c754d50, 1d8b679cc3a3; files: Sources/IMsgCore/MessageStore+Messages.swift, Sources/IMsgCore/MessageStore+Queries.swift, Sources/imsg/RPCServer+Handlers.swift)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.