hermes - 💡(How to fix) Fix Expose canonical user-visible session classification for dashboards [1 participants]

Context

Hermes Web UI needs a stable way to show the main Chat session list as human/user-visible conversations only, while hiding agent-spawned sessions such as delegated subagents, tool/internal runs, and compression continuations.

Web UI can infer part of this from state.db, but that inference is brittle because Hermes Agent creates the sessions and owns the semantics.

Current useful behavior already exists in SessionDB.list_sessions_rich():

• child sessions are hidden by default
• subagent children are hidden
• compression continuations are hidden/projected to the latest continuation tip
• branch sessions remain visible

The problem is that Web UI cannot consume this as a stable backend contract. It currently has to read state.db and reimplement similar lineage heuristics in TypeScript.

Current behavior

• Session rows already carry useful fields such as source, user_id, parent_session_id, started_at, ended_at, and end_reason.
• list_sessions_rich(include_children=False) has Agent-side visibility logic for children, branches, and compression continuations.
• External dashboards do not have a canonical session summary/read model that says whether a session should be visible in the normal human Chat list.
• There does not appear to be an explicit persisted initiated_by / is_human_initiated / visible_in_main_chat field that all session creation paths set.

Expected behavior

Dashboards should be able to request or receive a canonical Agent-side classification for session visibility, instead of reconstructing it from DB details.

For a normal human-facing Chat list:

• show human-initiated/root conversations
• show explicit branch sessions
• represent compression chains as one logical conversation, preferably projected to the current continuation/tip
• hide delegated/subagent sessions
• hide tool/internal sessions
• avoid requiring dashboards to infer delegation from parent_session_id + timing + parent end_reason

Proposed boundary

Either expose a canonical Agent-side read model for dashboards/session browsers, or add explicit session-origin metadata so external UIs do not need to guess.

Possible API shape:

GET /v1/sessions?visibility=user_visible
GET /v1/sessions?visibility=all

or an equivalent gateway/CLI/export contract that Web UI can consume.

Useful fields on each summary could include:

{
  id: string
  source: string
  parent_session_id?: string | null
  root_session_id?: string
  effective_session_id?: string
  conversation_id?: string
  session_kind?: 'human' | 'branch' | 'compression_continuation' | 'delegation' | 'tool' | 'cron' | 'api' | 'internal'
  visible_in_main_chat?: boolean
}

The exact names are not important. The important part is that Hermes Agent owns the classification.

Why this belongs in Hermes Agent

Hermes Agent creates the sessions and knows why they were created. Web UI can only inspect persisted side effects.

Without an Agent-side contract, every dashboard/client has to duplicate session-lineage logic and will drift from CLI/TUI/gateway behavior.

Evidence checked

Relevant Agent-side files/logic inspected locally:

• hermes_state.py
  • sessions schema includes source, user_id, parent_session_id, started_at, ended_at, end_reason, token/cost fields, etc.
  • create_session(...) accepts source, user_id, and parent_session_id, but no obvious explicit human-initiation/session-kind field.
  • get_compression_tip(...) distinguishes compression continuations via parent end_reason='compression' and timing.
  • list_sessions_rich(...) default include_children=False filters child/subagent/compression sessions while preserving branch sessions.
• tests/test_hermes_state.py
  • coverage already asserts branch sessions are visible, subagent sessions are hidden, and compression children are hidden/projected.

Related Web UI need:

• main Chat session list should be toggleable to show only human-initiated sessions
• the setting belongs in display preferences
• Web UI should consume an Agent-owned contract instead of adding another divergent DB heuristic