Show Agent Sessions should respect agent session relationships

[franksong2702]

Summary

Show Agent Sessions currently merges Hermes Agent / CLI / Gateway rows from state.db into the WebUI sidebar as flat session entries.

That works for simple sessions, but Hermes Agent session rows can have different relationship semantics:

• empty/unimportable rows that have a sessions record but no messages
• compression continuation chains, where one long user conversation is split into multiple session segments linked by parent_session_id
• subagent delegation children, where a parent task intentionally spawns child sessions that should remain visible as a tree

Today the WebUI bridge does not distinguish these cases. It treats every non-webui row as a standalone conversation, which can make the sidebar confusing or broken when Show Agent Sessions is enabled.

Observed example

With Show Agent Sessions enabled, a Weixin conversation produced many sidebar entries like:

• Magazine Style PPT Skill #91
• Magazine Style PPT Skill #88
• Magazine Style PPT Skill #76

Inspecting the local Hermes Agent state.db showed this was not simply duplicate data. These rows form a continuation chain through parent_session_id:

Magazine Style PPT Skill
  -> Magazine Style PPT Skill #2
  -> ...
  -> Magazine Style PPT Skill #92 / #94

Many intermediate rows have end_reason = 'compression'. From the user's point of view this is one ongoing messaging conversation, but the WebUI sidebar exposes the backend compression segments as separate sessions.

There were also some empty rows with no message records. Those appear in the sidebar but cannot be imported, causing Session not found in CLI store when clicked.

Why this is not Weixin-specific

This surfaced with Weixin because that is where I could reproduce it locally, but the underlying model is shared by Hermes Agent:

• hermes_state.py stores parent_session_id and explicitly supports compression-triggered session splitting.
• gateway.session.build_session_key() is the shared gateway session key mechanism used by platforms such as Telegram, Weixin, Discord, Matrix, etc.
• Hermes Agent's own SessionDB.list_sessions_rich() defaults to include_children=False and project_compression_tips=True, which treats compression continuations as one logical conversation projected to the latest tip.

The WebUI bridge currently bypasses that logical projection and directly queries raw sessions rows.

Current WebUI paths affected

Two WebUI paths need to stay in sync:

1. /api/sessions via api.models.get_cli_sessions()

   • currently reads raw non-webui rows from state.db
   • applies LIMIT 200 before any logical conversation projection

2. Gateway SSE watcher via api.gateway_watcher._get_agent_sessions_from_db()

   • also reads raw non-webui rows
   • can reintroduce the same flattened list during live refresh even if /api/sessions is fixed separately

Related issues / PRs

• Related to Real-time bidirectional sync between Gateway sessions and WebUI #272: gateway sessions became visible through Show Agent Sessions; this issue is about the relationship semantics of those displayed sessions, not bidirectional gateway sync.
• Related to feat(sessions): subagent session tree — show subagent hierarchy in sidebar #494: subagent sessions also use parent/child relationships, but they should be displayed as a delegation tree rather than collapsed. This issue should not accidentally implement or close feat(sessions): subagent session tree — show subagent hierarchy in sidebar #494.
• Related historical work: feat: subagent session trees, unified tool cards, streaming fixes, UI polish #75 attempted broader subagent/session tree UI work but was closed unmerged; docs: add community feature ideas from PR #75 to roadmap #79 moved some ideas into the roadmap; Sprint 23: Agentic transparency — token costs, subagent cards, skill picker, linked files #51 shipped some agentic transparency pieces but not sidebar relationship handling.

Proposed implementation plan

I think this should be split into two PRs for this issue.

PR 1: Hide empty/unimportable agent session rows

Scope:

• Filter out agent sessions that have no readable message rows.
• Prevent broken sidebar entries that fail during /api/session/import_cli.
• Keep this narrow: do not collapse parent_session_id chains yet.

Expected behavior:

• A sessions row with source != 'webui' but zero messages rows should not appear in the sidebar.
• Existing valid agent sessions should continue to appear.

Suggested tests:

• Add a regression test where a non-webui session row exists with no messages and verify /api/sessions does not return it.

This PR should reference this issue but should not close it.

PR 2: Collapse compression continuation chains into logical conversations

Scope:

• Use parent_session_id and end_reason = 'compression' to identify continuation chains.
• Display one sidebar item per logical compression chain, projected to the latest non-empty tip.
• Apply the same projection in both:
  • api.models.get_cli_sessions()
  • api.gateway_watcher._get_agent_sessions_from_db()
• Apply the final list limit after filtering/collapsing, not before.
• Keep import/open behavior pointed at the latest real session id; do not create a fake merged WebUI session.

Expected behavior:

• A long Weixin/Telegram/Cron/CLI conversation split by context compression should show as one logical sidebar entry.
• Clicking the entry imports/opens the latest real continuation segment.
• Empty intermediate continuation rows are skipped.
• Independent sessions remain independent.

Suggested tests:

• A compression chain with multiple non-empty children returns only the latest non-empty tip.
• A chain with empty intermediate nodes still resolves to the latest non-empty usable node.
• Unrelated sessions are not collapsed together.
• The gateway watcher emits the same logical session shape as /api/sessions.

This PR can close this issue if the issue scope remains limited to empty rows + compression continuation projection.

Explicit non-goals for this issue

• Do not implement the subagent sidebar tree from feat(sessions): subagent session tree — show subagent hierarchy in sidebar #494 here.
• Do not merge all historical messages from a compression chain into one synthetic WebUI session.
• Do not implement WebUI -> Gateway bidirectional messaging from Real-time bidirectional sync between Gateway sessions and WebUI #272 Phase 2.
• Do not redesign the whole sidebar IA.

Product principle

Show Agent Sessions should expose useful agent conversations, not raw backend storage rows.

Different parent_session_id relationships need different UI treatment:

• empty rows: hide
• compression continuation: collapse into one logical conversation
• subagent delegation: show as a tree, tracked separately by feat(sessions): subagent session tree — show subagent hierarchy in sidebar #494

Suggested triage metadata

suggested metadata:

• Labels: bug, cli-parity, gateway, ux
• Milestone: Milestone 1 — Core quality & parity

[nesquena-hermes]

Well-structured issue — the problem is clearly defined, the affected code paths are named, and the proposed split into two PRs is the right call.

A few notes on the implementation plan:

PR 1 — Filter empty/unimportable rows:
The filter at /api/sessions is straightforward. One thing to confirm: the gateway watcher (_get_agent_sessions_from_db()) and /api/sessions (get_cli_sessions()) share the same filtering logic or are at minimum kept in sync. If PR 1 only fixes one path, live session refresh could re-introduce the empty rows during polling even after the initial page load filtered them. Suggest adding a shared helper function that both paths call, so they can't drift.

LIMIT 200 placement:
The note about applying the limit after filtering/collapsing (not before) is important and easy to miss. If LIMIT 200 is applied at the SQL layer before Python-side compression chain collapsing, a user with 200+ raw rows (which is realistic for a long-running agent with compression) will get a silently truncated logical conversation list. PR 2 should move the limit to post-collapse, or apply a higher SQL limit (e.g. 2000) and cap after projection.

PR 2 — Compression chain collapsing:
The projection approach (resolve to the latest non-empty tip) mirrors what SessionDB.list_sessions_rich(include_children=False, project_compression_tips=True) already does. If that method is accessible from the WebUI server process (same DB file, not a remote API), it may be worth calling it directly rather than re-implementing the projection logic in Python. That would keep the projection logic in one place and reduce divergence risk.

parent_session_id NULL handling:
Confirm that sessions with parent_session_id = NULL (standalone, not part of any chain) are correctly passed through the projection unchanged, and that end_reason is not accidentally used to filter non-compression rows (e.g. end_reason = 'user_cancelled' or similar should not be treated as a chain boundary).

Test coverage:
The suggested tests in the issue are good baselines. Adding one more: a chain where the latest tip is also empty (all segments empty) — the correct behavior is probably to hide the entire chain rather than return an empty importable entry.

Suggested labels/milestone look right. This is a real quality issue for anyone using Show Agent Sessions with a platform-connected agent.

[franksong2702]

Quick scope update after the PR split:

• Hide empty agent sessions from sidebar #1009 covers the empty/unimportable-row failure mode.
• Collapse agent session compression chains #1012 covers compression continuation-chain projection.
• Clarify source-aware UX for Show agent sessions #1013 tracks the broader source-aware UX/product question for Show agent sessions.

So I would keep this issue focused on technical correctness: agent sessions should appear as importable logical conversations rather than raw backend rows. The separate UX discussion can decide whether all sources should continue to flat-merge into the main sidebar, or whether CLI / Messaging / Cron should be grouped or filtered differently.

[nesquena-hermes]

Thanks for scoping this into PRs 1009/1012/1013, @franksong2702 — clean decomposition.

Agreed on the scope split. This parent issue can now serve as the tracking anchor. Once #1009 (empty row filter) and #1012 (compression chain) both land, we can close this one.

Two things worth flagging for the implementors:

1. The session type tagging (CLI vs cron vs messaging) discussed in Clarify source-aware UX for Show agent sessions #1013 should be a shared contract — don't hard-code type detection in each PR separately.
2. For the subagent tree view (feat(sessions): subagent session tree — show subagent hierarchy in sidebar #494), the parent_session_id linkage will need to survive the empty-row filter — make sure the filter doesn't strip session records that are referenced as parents of non-empty children.

Tagging M2. Will close this once #1009 and #1012 are merged.

[nesquena-hermes]

Closing as fully shipped — all three sub-issues landed

Per my earlier comment on this thread:

Tagging M2. Will close this once #1009 and #1012 are merged.

All three sub-issues that came out of the scope split are now closed:

#	Title	Closed
#1009	Hide empty agent sessions from sidebar	2026-04-25
#1012	Collapse agent session compression chains	2026-04-26
#1013	Clarify source-aware UX for Show agent sessions	2026-05-03

The relationship-aware behavior in Show Agent Sessions is live on master:

• Empty-row filter: _hide_from_default_sidebar() in api/models.py filters records with no messages from the sidebar.
• Compression chain collapse: api/agent_sessions.py::_is_continuation_session() collapses parent/child rows along parent_session_id continuation chains, AND now refuses to collapse cross-source pairs (parent.source != child.source) per PR fix: keep cross-source continuations separate in sidebar #1602 (v0.50.292).
• Type tagging: shared contract for CLI vs cron vs messaging session classification (the cross-implementation drift concern flagged in my review of Clarify source-aware UX for Show agent sessions #1013).

The parent_session_id linkage you flagged for the subagent tree (#494) survives the empty-row filter, and #494's depth-1 expand/collapse is also now live in static/sessions.js. So the architectural foundation that this umbrella set up is reusable.

Thanks @franksong2702 for the clean scope split and the implementation work across the three PRs. Closing as fully resolved.