Trim tool call payloads for paginated session loads

[MinhoJJang]

Thinking Path

/api/session?messages=1&msg_limit=N is the fast path used when switching sessions. It already sends only a message window, but legacy sessions can still include the full session-level tool_calls list. For long tool-heavy conversations, that means a small message response can still carry a large amount of historical tool-call data the browser cannot render in the current window.

The response contract already exposes _messages_offset, so the server can use the same message coordinate space to keep only tool calls whose assistant_msg_idx lands inside the returned window. Full transcript loads keep the existing behavior.

What Changed

• Filter session-level tool_calls to the returned message window when /api/session is loaded with pagination.
• Preserve full tool_calls behavior for non-paginated full transcript loads.
• Keep the existing behavior that omits session-level tool_calls when returned messages already include per-message tool metadata.
• Add regression coverage for tail-window loads, full loads, and msg_before pagination.
• Add an Unreleased changelog entry.

Why It Matters

This keeps session switching payloads proportional to the visible message window. It reduces JSON serialization, transfer size, browser parse work, and render bookkeeping for long sessions with many tool calls, without changing the persisted session format.

A local synthetic benchmark with 2,000 messages, 1,000 legacy session-level tool calls, 1 KiB snippets, and msg_limit=10 reduced the /api/session JSON payload from 1,111,267 bytes to 6,487 bytes. Handler + JSON serialization median time dropped from 8.599 ms to 2.436 ms across 150 runs.

Verification

• /tmp/hermes-webui-pr-venv/bin/python -m py_compile api/routes.py
• /tmp/hermes-webui-pr-venv/bin/python -m pytest tests/test_session_tail_payload.py -q --timeout=60
• /tmp/hermes-webui-pr-venv/bin/python -m pytest tests/test_parallel_session_switch.py -q --timeout=60
• /tmp/hermes-webui-pr-venv/bin/python -m pytest tests/test_webui_state_db_reconciliation.py -q --timeout=60
• GIT_CONFIG_GLOBAL=/tmp/hermes-webui-test-gitconfig /tmp/hermes-webui-pr-venv/bin/python -m pytest tests/ -v --timeout=60

Full-suite result: 6430 passed, 76 skipped, 3 xpassed, 8 subtests passed in 172.26s.

Risks / Follow-ups

Session-level tool calls without assistant_msg_idx are omitted from paginated responses because they cannot be placed into a truncated message window. Full transcript loads still return them.

This does not make the frontend initial message limit configurable; that can stay separate.

Model Used

OpenAI GPT-5.5 via Codex, with local shell-based repository inspection and test execution.

[nesquena-hermes]

Merged in Release DI / v0.51.137 (stage-batch19, batch with PRs #2913 #2915 #2923 #2933 #2937 #2940).

Thanks @MinhoJJang! 🚢