PR #10: reachable freshness filter for /rag/search and /rag/top

[khalidsaidi]

Summary

• add reachableMaxAgeHours to RAG filters and API query schemas for /rag/search and /rag/top
• enforce freshness only when reachable=true in passesFilters using reachableCheckedAt
• echo applied freshness filter in metadata.filters.reachableMaxAgeHours
• expose new query param in agent card endpoint docs
• pass through reachableMaxAgeHours in local + remote MCP tools when reachable=true
• add integration tests for fresh/stale/missing behavior in search/top
• document freshness filter behavior in deployment docs

Validation

• corepack enable
• pnpm -r install
• pnpm -r typecheck
• pnpm -r test
• pnpm -r lint

All checks passed locally.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6b5165bc3b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Fall back to lastReachableAt for freshness filtering

In passesFilters, the new freshness gate only reads enrichment.reachableCheckedAt, so records that still store reachability time under lastReachableAt are treated as missing and excluded whenever reachable=true&reachableMaxAgeHours=... is used. The codebase still treats lastReachableAt as a valid fallback elsewhere (for example, response mapping in apps/api/src/app.ts), so this creates false negatives for older-but-valid indexed data until those rows are rewritten.

Useful? React with 👍 / 👎.