openclaw - 💡(How to fix) Fix [UX] WebChat: add paginated scrollback / load older messages

Summary

WebChat / Control UI needs paginated scrollback for long, tool-heavy sessions. Today the chat view can only show a bounded recent window, so after 40-60 tool calls the user can no longer scroll back to important earlier user/assistant context.

This should be solved as a paging UX, not by simply increasing the default history payload.

Current release behavior

Observed against the v2026.5.19-beta.2 release tree:

• ui/src/ui/controllers/chat.ts requests chat.history with limit: 100 and maxChars: 4_000.
• ui/src/ui/chat/history-limits.ts and ui/src/ui/chat/build-chat-items.ts apply another renderer-side cap of 100 visible history messages or a 240k render character budget.
• When history is hidden, the UI emits a passive notice like Showing last 100 messages (N hidden). There is no way to load the hidden messages.
• Live tool messages are rendered as individual chat items when tool calls are shown, so a normal tool-heavy run can consume most of the scrollback window.
• The gateway already has a cursor-capable HTTP/SSE history surface at /sessions/:sessionKey/history?limit=&cursor= that returns messages/items, hasMore, and nextCursor, with tests covering cursor pagination.

Relevant source paths:

• ui/src/ui/controllers/chat.ts
• ui/src/ui/chat/history-limits.ts
• ui/src/ui/chat/build-chat-items.ts
• src/gateway/sessions-history-http.ts
• src/gateway/session-history-state.ts

Recommended path

Use the existing cursor history endpoint for WebChat scrollback and keep the current WebSocket path for live chat/run events.

Suggested first implementation:

1. Initial load still fetches a bounded recent page, but stores hasMore and nextCursor.
2. The top of the chat thread shows an actionable Load older messages control, or an intersection-observer sentinel if maintainers want lazy loading.
3. Loading an older page prepends messages, dedupes by stable transcript metadata such as __openclaw.seq/message id, and preserves the scroll anchor.
4. The current passive Showing last ... hidden notice becomes an actionable paging affordance.
5. Tool calls remain accessible, but the default display should not let tool cards dominate scrollback. This can be coordinated with #47386.
6. If showToolCalls=false, the loader should avoid underfilling pages with mostly hidden tool rows. Either the API should support display-mode filtering, or the client should overscan enough to fill a user-visible page.

Adversarial analysis

• Just raise chat.history limit / maxChars: easy, but it increases payload and render cost, still has no way to navigate older history, and does not address tool-heavy sessions reliably.
• Fetch the full transcript and virtualize it: powerful, but too broad for a first PR; it increases privacy/performance risk and overlaps with the transcript browser request in #77637.
• Only hide or collapse tool calls: improves visual noise but does not load older messages, and risks hiding audit/debug detail rather than making it navigable.
• Use existing paginated history endpoint: best first path. It matches the current server contract, contains payload size, and gives users an explicit way back through the conversation.

Acceptance criteria

• A WebChat user can reach messages older than the latest 100 without changing config or reloading the page.
• A transcript with at least 250 messages and 60+ tool messages can load earlier user/assistant turns from the UI.
• Scroll position is stable when older messages are prepended.
• Refreshing a selected session restores the first page and retains the ability to page older history.
• Existing live streaming/tool event behavior is not replaced by polling.
• Focused tests cover history page merge/dedupe and the visible load-older affordance.

Related issues

• #83344 covers a bug where tool-heavy transcript tails can make refreshed WebChat history appear missing.
• #51549 covers refresh losing browser-local queue/draft state.
• #47386 covers aggregate/collapsible tool-output summary mode.
• #77637 covers a broader transcript browser.
• #81583 covers cross-session full-text search.