feat(gateway): add /sessions search by GodsBoy · Pull Request #57595 · NousResearch/hermes-agent

GodsBoy · 2026-07-03T08:00:31Z

What does this PR do?

Gateway users can now run /sessions search <query> from messaging surfaces to find resumable sessions without leaving the chat. Ordinary search uses persisted gateway origin filters plus the existing caller-visible resume guard, so results stay scoped to the relevant chat, user, and session boundary instead of enumerating another user's sessions. Explicit admins can still use /sessions all search <query> to search the broader non-tool session set and see source labels.

The search path is not limited to the short recent /sessions or /resume list. It pages matching sessions from the session DB, returns numbered rows, and stores the latest numbered result list for that gateway chat. After a search, /resume <number> or /sessions <number> resumes that numbered result through the existing authorization and session-switch flow. Bare /resume still lists recent titled sessions and refreshes the numbered picks for that chat.

The gateway search also handles legacy rows found in real gateway history:

DM rows that predate full chat-origin persistence and have a blank chat_id.
WhatsApp DM rows where older sessions stored the lid/chat identifier as user_id, while current events use a phone JID plus lid chat id.
Threaded group/topic rows where older same-user sessions have blank chat/thread fields.
Compressed continuations where the latest tip has blank origin fields but a compression ancestor proves the same source and owner.
Punctuation-normalized title/id queries, so an94 can match AN-94.
Ranked content fallback for gateway search, so relevant older sessions whose title does not contain the typed shorthand, for example cod, can surface above weak title matches like Codex.

Related Issue

Related: #17193
Related: #49038

No separate feature-request issue was opened because no exact issue or PR exists for gateway /sessions search <query>, and this PR carries the proposal plus implementation. The related links remain context only: #17193 is broader cross-session management, and #49038 is a Telegram inline picker. The duplicate pass also reviewed #47535; that PR changes dashboard /api/sessions/search role scope, not gateway slash-command session search.

Type of Change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Security fix
Documentation update
Tests (adding or improving test coverage)
Refactor (no behavior change)
New skill (bundled or hub)

Changes Made

Added typed /sessions argument parsing for list flags, resume targets, and search or find queries.
Added title/id filtering through the shared listing helper and SessionDB.list_sessions_rich, including compression-chain title/id matches so projected live continuations are searchable.
Added punctuation-normalized title/id matching for queries such as an94 matching AN-94.
Added ranked message-content fallback for gateway search, with title/id matches and user/assistant content hits ranked ahead of generic transcript mentions.
Added persisted gateway-origin filters for rich session listings, so ordinary gateway search can look past recent rows while staying relevant to the current chat/user boundary.
Added legacy gateway fallbacks for same-user DM rows with blank chat_id, WhatsApp JID/lid owner changes, same-user threaded topic rows with blank chat/thread fields, and compressed continuation rows whose ancestry proves ownership.
Wired gateway /sessions search <query> with missing-query usage feedback, existing caller visibility filtering, existing admin cross-origin handling, and /sessions all search <query> support for explicit admins.
Stored the latest numbered session list per gateway chat so /resume <number> and /sessions <number> can resume a result from the latest /sessions list or /sessions search output.
Updated gateway list guidance to show both direct resume and numbered resume options.
Added helper, gateway, and state regression tests for title matches, id matches, punctuation-normalized matches, ranked content matches, missing queries, old visible matches behind hidden same-source matches, numbered search-result resume, WhatsApp legacy lid rows, compressed legacy rows, legacy same-user topic rows, cross-user scoping, admin all-search scope, projected compression-tip titles, and persisted origin filters.

How to Test

python3 -m pytest tests/hermes_cli/test_session_listing.py tests/gateway/test_resume_command.py tests/test_hermes_state.py -q (380 passed)
python3 -m ruff check gateway/slash_commands.py hermes_cli/session_listing.py hermes_state.py tests/gateway/test_resume_command.py tests/hermes_cli/test_session_listing.py tests/test_hermes_state.py
git diff --check

Live VPS verification on the PR commit:

/sessions in WhatsApp DM lists named sessions and shows the search footer.
/sessions search winton in WhatsApp DM returns Winton Email Sheet Update #3 as result 1, and /resume 1 switches to that session.
/sessions search cod in the Telegram topic returns AN-94 Prestige Barrel Build #2 as result 1, and /resume 1 switches to that session.
/sessions search an94 in the Telegram topic also returns AN-94 Prestige Barrel Build #2 as result 1, and /resume 1 switches to that session.

Duplicate checks run for this PR:

gh search issues --repo NousResearch/hermes-agent '"/sessions search"' --json number,title,state,url --limit 20
gh search prs --repo NousResearch/hermes-agent '"/sessions search"' --json number,title,state,url --limit 20
gh issue view 17193 --repo NousResearch/hermes-agent --json number,title,state,url,body,updatedAt
gh pr view 49038 --repo NousResearch/hermes-agent --json number,title,state,url,body,updatedAt,files
gh pr view 47535 --repo NousResearch/hermes-agent --json number,title,state,url,body,files

No exact duplicate gateway slash-command issue or PR was found.

Checklist

Code

I've read the Contributing Guide
My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
I searched for existing PRs to make sure this isn't a duplicate
My PR contains only changes related to this feature (no unrelated commits)
I've run pytest tests/ -q and all tests pass. Not run locally; targeted pytest, ruff, and diff whitespace checks passed.
I've added tests for my changes (required for bug fixes, strongly encouraged for features)
I've tested on my platform: Ubuntu 24.04.4 LTS, x86_64

Documentation & Housekeeping

I've updated relevant documentation (README, docs/, docstrings) - implementation plan added under docs/plans/
I've updated cli-config.yaml.example if I added/changed config keys - N/A, no config keys added
I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows - N/A, no architecture/workflow change
I've considered cross-platform impact (Windows, macOS) per the compatibility guide - N/A, no platform-specific code
I've updated tool descriptions/schemas if I changed tool behavior - N/A, no model tool changed

For New Skills

N/A

Screenshots / Logs

Screenshot.Video.2026-07-03_12-28-39.mp4

@GodsBoy

Gateway users can now search resumable sessions from messaging surfaces: /sessions search <query> (alias: find) matches titles and session ids — including every title/id in a row's forward compression chain, so a compressed-away title still surfaces its live tip — plus a punctuation-normalized variant so 'an94' matches 'AN-94'. Implemented by generalizing the existing id_query chain-filter in SessionDB.list_sessions_rich into a combined SQL-level filter (search stays ORDER BY last-active + LIMIT at SQL level), threading a search_query through the shared query_session_listing helper, and teaching parse_session_listing_args to split off a search query. Search results pass through the existing _resume_row_visible guard unchanged: origin scoping, admin-only 'all', and the fail-closed legacy-row posture from the July 1 hardening are preserved exactly. Over-fetch (50) before the visibility cut so origin-invisible matches can't starve the page. Salvages the feature direction of PR #57595 by @GodsBoy with a minimal implementation that keeps the resume authorization surface untouched.

teknium1 · 2026-07-03T22:20:02Z

Merged via #57595

@GodsBoy

Gateway users can now search resumable sessions from messaging surfaces: /sessions search <query> (alias: find) matches titles and session ids — including every title/id in a row's forward compression chain, so a compressed-away title still surfaces its live tip — plus a punctuation-normalized variant so 'an94' matches 'AN-94'. Implemented by generalizing the existing id_query chain-filter in SessionDB.list_sessions_rich into a combined SQL-level filter (search stays ORDER BY last-active + LIMIT at SQL level), threading a search_query through the shared query_session_listing helper, and teaching parse_session_listing_args to split off a search query. Search results pass through the existing _resume_row_visible guard unchanged: origin scoping, admin-only 'all', and the fail-closed legacy-row posture from the July 1 hardening are preserved exactly. Over-fetch (50) before the visibility cut so origin-invisible matches can't starve the page. Salvages the feature direction of PR NousResearch#57595 by @GodsBoy with a minimal implementation that keeps the resume authorization surface untouched.

@GodsBoy

Gateway users can now search resumable sessions from messaging surfaces: /sessions search <query> (alias: find) matches titles and session ids — including every title/id in a row's forward compression chain, so a compressed-away title still surfaces its live tip — plus a punctuation-normalized variant so 'an94' matches 'AN-94'. Implemented by generalizing the existing id_query chain-filter in SessionDB.list_sessions_rich into a combined SQL-level filter (search stays ORDER BY last-active + LIMIT at SQL level), threading a search_query through the shared query_session_listing helper, and teaching parse_session_listing_args to split off a search query. Search results pass through the existing _resume_row_visible guard unchanged: origin scoping, admin-only 'all', and the fail-closed legacy-row posture from the July 1 hardening are preserved exactly. Over-fetch (50) before the visibility cut so origin-invisible matches can't starve the page. Salvages the feature direction of PR NousResearch#57595 by @GodsBoy with a minimal implementation that keeps the resume authorization surface untouched.

@GodsBoy

Gateway users can now search resumable sessions from messaging surfaces: /sessions search <query> (alias: find) matches titles and session ids — including every title/id in a row's forward compression chain, so a compressed-away title still surfaces its live tip — plus a punctuation-normalized variant so 'an94' matches 'AN-94'. Implemented by generalizing the existing id_query chain-filter in SessionDB.list_sessions_rich into a combined SQL-level filter (search stays ORDER BY last-active + LIMIT at SQL level), threading a search_query through the shared query_session_listing helper, and teaching parse_session_listing_args to split off a search query. Search results pass through the existing _resume_row_visible guard unchanged: origin scoping, admin-only 'all', and the fail-closed legacy-row posture from the July 1 hardening are preserved exactly. Over-fetch (50) before the visibility cut so origin-invisible matches can't starve the page. Salvages the feature direction of PR NousResearch#57595 by @GodsBoy with a minimal implementation that keeps the resume authorization surface untouched.

@GodsBoy

Gateway users can now search resumable sessions from messaging surfaces: /sessions search <query> (alias: find) matches titles and session ids — including every title/id in a row's forward compression chain, so a compressed-away title still surfaces its live tip — plus a punctuation-normalized variant so 'an94' matches 'AN-94'. Implemented by generalizing the existing id_query chain-filter in SessionDB.list_sessions_rich into a combined SQL-level filter (search stays ORDER BY last-active + LIMIT at SQL level), threading a search_query through the shared query_session_listing helper, and teaching parse_session_listing_args to split off a search query. Search results pass through the existing _resume_row_visible guard unchanged: origin scoping, admin-only 'all', and the fail-closed legacy-row posture from the July 1 hardening are preserved exactly. Over-fetch (50) before the visibility cut so origin-invisible matches can't starve the page. Salvages the feature direction of PR NousResearch#57595 by @GodsBoy with a minimal implementation that keeps the resume authorization surface untouched.

alt-glitch added type/feature New feature or request comp/gateway Gateway runner, session dispatch, delivery comp/cli CLI entry point, hermes_cli/, setup wizard P3 Low — cosmetic, nice to have labels Jul 3, 2026

GodsBoy force-pushed the feat/gateway-sessions-search branch 5 times, most recently from c217f08 to a6b2c00 Compare July 3, 2026 10:09

feat(gateway): add sessions search

34aaaea

GodsBoy force-pushed the feat/gateway-sessions-search branch from a6b2c00 to 34aaaea Compare July 3, 2026 10:14

teknium1 mentioned this pull request Jul 3, 2026

feat(gateway): add /sessions search <query> #57685

Merged

teknium1 closed this Jul 3, 2026

github-actions Bot mentioned this pull request Jul 3, 2026

🦞 OpenClaw 生态日报 2026-07-04 huajiao1998/big_model_radar#15

Open

This was referenced Jul 7, 2026

Gateway /resume <number> ignores /sessions search result numbering #60136

Open

fix(gateway): resume numbered session search results #60138

Open

GottZ mentioned this pull request Jul 25, 2026

Bug: deleting sessions can leave visible 0-message placeholder rows #56733

Open

GottZ mentioned this pull request Aug 3, 2026

fix(gateway): mark current session in listings #68556

Open

andrexibiza mentioned this pull request Aug 6, 2026

WhatsApp Feature Parity & Alignment Campaign — meta-issue #79890

Open

Skywind5487 mentioned this pull request Aug 8, 2026

Align session title FTS with message external-content rebuild architecture Skywind5487/hermes-agent#12

Closed

Navigation Menu

Uh oh!

feat(gateway): add /sessions search - #57595

feat(gateway): add /sessions search#57595
GodsBoy wants to merge 1 commit into
NousResearch:mainfrom
GodsBoy:feat/gateway-sessions-search

GodsBoy commented Jul 3, 2026 •

edited

Loading

Uh oh!

teknium1 commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

GodsBoy commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Related Issue

Type of Change

Changes Made

How to Test

Checklist

Code

Documentation & Housekeeping

For New Skills

Screenshots / Logs

Uh oh!

teknium1 commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GodsBoy commented Jul 3, 2026 •

edited

Loading