perf(session-search): adapt discovery result hydration

[blunkjamie-dev]

What does this PR do?

Reduces routine session_search discovery payloads without changing FTS ranking, lineage deduplication, cron demotion, or scroll/read behavior.

Discovery currently hydrates bookends plus a ±5-message window for every matched session. On a real 51,969-message database, SQLite lookup and complete tool execution were already fast (adaptive p50 up to 72 ms in the final query set), while a three-result response commonly carried 24–34 KB and broad ten-result searches had exceeded 130 KB. The bottleneck is returned context, not the index.

This PR adds adaptive discovery hydration:

• the highest-ranked result keeps the prior full bookends + anchored window;
• lower-ranked results keep the same structural keys, metadata, snippet, navigation identifiers, and exact flagged anchor message, but omit bookend/window expansion;
• detail="full" restores the prior all-results-full response;
• top-level and per-result detail fields make the returned shape explicit.

This intentionally stays complementary to three narrower fixes already under review:

• fix(context): bound session recall payloads #55640 bounds and filters the separately hydrated exact-title path;
• fix(agent): forward profile param in session_search handler calls #60819 forwards cross-profile profile arguments through the optimized agent handlers;
• fix(session-search): cap discovery payloads #79219 adds a 12K hard persistence fallback for worst-case serialized results.

This PR avoids routine over-hydration before serialization while preserving the best-ranked context inline. It does not duplicate those exact-title, cross-profile, or hard-cap patches.

Related Issue

Related PRs: #55640, #60819, #79219

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

• tools/session_search_tool.py
  • adds discovery-only detail={adaptive,full} schema and handler wiring;
  • defaults to a full top result plus compact lower-ranked results;
  • preserves exact anchor messages and all navigation/ranking metadata;
  • documents adaptive/full semantics.
• agent/agent_runtime_helpers.py, agent/tool_executor.py
  • forward detail through both optimized agent-loop dispatch paths.
• tests/tools/test_session_search.py
  • covers schema/default behavior and explicit full compatibility;
  • proves adaptive/full ranking and anchor identity;
  • enforces a synthetic payload-reduction budget.
• tests/run_agent/test_token_persistence_non_cli.py
  • verifies detail="full" reaches the tool through direct and sequential execution.
• website/docs/user-guide/sessions.md
  • documents four shapes and the adaptive/full discovery contract.

How to Test

uv sync --locked --extra dev
uv run pytest tests/tools/test_session_search.py -q
uv run pytest tests/run_agent/test_token_persistence_non_cli.py tests/tools/test_session_search.py -q
uv run ruff check agent/agent_runtime_helpers.py agent/tool_executor.py tools/session_search_tool.py tests/run_agent/test_token_persistence_non_cli.py tests/tools/test_session_search.py
npx -y npm@11.17.0 --prefix website run build:fast
git diff --check

Verified on Windows 10:

• session-search suite: 42 passed;
• focused suite plus both agent-loop dispatch regressions: 45 passed;
• Ruff: passed;
• Docusaurus English production build: passed (only the pre-existing /docs/llms*.txt home-page link warnings);
• git diff --check: passed;
• real read-only DB benchmark, six representative queries (Hermes, restart, proof, memory, project, Buzz):
  • identical (session_id, match_message_id) ranking in adaptive/full modes;
  • median serialized-payload reduction: 49.4%;
  • adaptive p50 execution latency: 29–72 ms.

I also attempted the full tests/tools suite. The locked dev extra initially lacked the optional Slack aiohttp dependency; after adding the locked Slack extra only to the disposable worktree venv, that broad suite exceeded ten minutes and surfaced numerous unrelated optional-integration failures. I am therefore not claiming the repository-wide suite passes locally; the load-bearing focused gates above are green.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched open/closed PRs and issues for duplicates
• My PR contains only changes related to this feature
• I've run pytest tests/ -q and all tests pass — focused gates pass; broad-suite limitation documented above
• I've added tests for my changes
• I've tested on Windows 10

Documentation & Housekeeping

• Relevant docstrings/tool documentation updated
• cli-config.yaml.example: N/A (no config key)
• CONTRIBUTING.md / AGENTS.md: N/A (no workflow change)
• Cross-platform impact considered: pure Python/JSON response shaping
• Tool description and schema updated

[teknium1]

Thanks for this fix! It was salvaged into #86764 (cherry-picked onto current main with your authorship preserved in the commit history) and is now merged. Closing since the work has landed.