mirror of https://github.com/wu736139669/hapi.git synced 2026-11-07 01:21:37 +00:00

Files

T

AnanovoandGitHub 78472e1c78 docs(web): document session list and search behavior (#1984 )

* docs(web): document session list and search behavior

* chore: retrigger PR checks

* docs(web): clarify searched group pagination

2026-10-28 12:11:27 +08:00

5.0 KiB

Raw Blame History

Session list

HAPI's Web session list combines live session state, project grouping, search, and local display filters. The list is designed to keep sessions that need attention easy to find while still allowing older sessions to be searched.

Ordering and grouping

The Hub/API provides the session list with this baseline order:

Globally pinned sessions.
Project-pinned sessions.
Active sessions.
Among active sessions, sessions with more pending requests first.
updatedAt descending as the recency tie-breaker.

The Web app then groups sessions by machine and project directory. Within a project, pinned sessions come first, followed by active sessions and then inactive sessions; rows with the same status are ordered by updatedAt. Project groups use their pinned/active state and newest member when deciding their position.

The detailed API contract is documented in REST — sessions and SSE — keep-alive noise.

updatedAt is the session activity clock used by the list and date filter. It is different from activeAt: activeAt is the CLI connection keep-alive clock and does not, by itself, move a session in the list. A connected session can therefore be idle; see active is transport liveness, not agent health.

When enabled in Settings → Display, the optional in-progress layout moves active sessions into Working, Pending, Active, and Idle sections. Global and project pins remain distinct from these sections.

Text search

The search field on the Web session list searches session metadata, including:

the displayed title (name, summary, path, or ID fallback);
worktree labels and paths;
summary text;
agent flavor and machine label; and
the session ID.

Plain-text matching is case-insensitive and supports partial substrings. A multi-word query uses AND semantics: every term must match at least one searchable field. Queries containing * or ? use wildcard matching, where * matches any sequence and ? matches one character.

Search results are ranked by relevance rather than by date alone. Title and worktree matches are more prominent than summary, machine, path, or ID-only matches; token-boundary matches and exact/contiguous title phrases receive additional preference. When relevance is tied, updatedAt descending is used as the tie-breaker. This means an older session with a distinctive title can appear above a newer session that only matches a common path segment.

Search preserves the session-list structure: pinned rows remain contiguous and project groups remain visible. Matching project groups open automatically, but the preview limit still applies within an open group. Search does not apply a relevance cutoff; use the group's batch reveal controls to show additional matching rows.

Filters and display settings

Date range filters by the local calendar date of updatedAt. The end date includes the whole local day.
Unread only is a transient view filter. The currently open session stays visible, and the filter is cleared when the page is reloaded.
Machine filters can be applied when more than one machine is present. The selection is remembered locally in the browser and falls back to All when that machine is no longer available.
Active sessions only hides inactive sessions but keeps the selected session visible.
Session preview limit controls how many rows are initially visible within each project group. Sessions with pending requests and the selected session can remain visible; a project can reveal more rows in batches.
Session-list status controls whether rows show the standard or detailed attention/status presentation.

Empty, inactive session stubs without conversation, an agent identity, or an explicit title signal are not shown in the normal sidebar. Duplicate rows representing the same underlying agent session are collapsed, with the live, selected, pinned, or most recent row preferred as appropriate.

Other Web session pickers

The other Web surfaces intentionally use related but different policies:

The /share picker snapshots the session list when it opens so live SSE updates do not reshuffle the rows under the user's finger.

With no query or date range, it shows recent active sessions, sorted by updatedAt and capped by the session preview limit.
With a text query or date range, it searches all matching sessions, including inactive sessions, and keeps updatedAt descending order.
It reuses the session metadata matching fields, but it does not apply the main sidebar's relevance ranking.

`@` session suggestions

Composer @ suggestions only include sessions with conversation content. With an empty query they prefer active and recent sessions; after typing, they use a separate title/ID/active/recency ranking. Names, directories, and machine labels affect matching, but an empty stub is never a mention target.

5.0 KiB Raw Blame History