hermes-agent/website/docs/user-guide
kshitijk4poor 2a352f96ee fix(x_search): surface degraded results + validate dates
The xAI Responses API for x_search returns 200 OK with a
synthesized fluff answer in two failure modes that callers currently
cannot distinguish from a real, citation-backed result:

1. Any narrowing filter (allowed_x_handles, excluded_x_handles,
   from_date, to_date) was active, but the X index returned no
   matching posts. The model then answers from training data.
2. The date range is malformed, inverted, or pure-future (e.g.
   from_date=2030-01-01). The API call burns quota and Grok
   responds with a generic answer.

Mitigations, both client-side:

* Validate from_date / to_date before the HTTP call:
  - Strict YYYY-MM-DD.
  - from_date <= to_date when both set.
  - from_date <= today UTC (no posts in a window that hasn't
    started). to_date in the future remains allowed so callers
    can request 'from yesterday to tomorrow'.

* Add 'degraded' + 'degraded_reason' to successful responses.
  degraded=True iff any narrowing filter was active AND both the
  top-level 'citations' array and inline 'url_citation'
  annotations came back empty. A broad query with no filters that
  returns no citations is *not* flagged degraded — that case is
  just an unsourced answer, not a filter miss.

Tests cover all four validation paths plus six degraded-flag
scenarios (each filter type, inline vs top-level citation
recovery, broad query baseline). All existing tests continue to
pass; the additions are purely additive on the success-path
response shape.

Discovered while testing the x_search toolset end-to-end:
queries scoped to @Teknium1 returned confident-sounding generic
text about Nous Research with zero citations, and from_date in
2030 produced sassy non-answers. Both are now detectable by the
caller.
2026-05-21 02:38:45 +05:30
..
features fix(x_search): surface degraded results + validate dates 2026-05-21 02:38:45 +05:30
messaging docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
skills docs: align kanban readiness docs and smoke tests 2026-05-18 21:07:03 -07:00
_category_.json feat: add documentation website (Docusaurus) 2026-03-05 05:24:55 -08:00
checkpoints-and-rollback.md feat(checkpoints): v2 single-store rewrite with real pruning + disk guardrails (#20709) 2026-05-06 05:44:35 -07:00
cli.md docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
configuration.md feat: auto-launch Chromium-family browser for CDP 2026-05-19 22:34:05 -07:00
configuring-models.md docs(session_search): update all docs for the single-shape rewrite (#27840) 2026-05-18 00:36:17 -07:00
docker.md docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
git-worktrees.md docs: restructure site navigation — promote features and platforms to top-level (#4116) 2026-03-30 18:39:51 -07:00
profile-distributions.md docs(profiles): full user guide for profile distributions (#22017) 2026-05-08 11:13:45 -07:00
profiles.md feat(kanban): orchestrator-driven auto-decomposition on triage (#27572) 2026-05-17 13:54:12 -07:00
security.md docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
sessions.md docs(sessions): state.db is canonical for gateway messages 2026-05-20 13:00:57 -07:00
tui.md docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
windows-native.md docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) 2026-05-18 23:55:25 -07:00
windows-wsl-quickstart.md docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) 2026-05-09 13:19:51 -07:00