#22626: feat(search): add support for SearXNG as a search provider

# PR Summary: Add SearXNG as a Web Search Provider ## Overview **Problem:** Users who want privacy-focused or self-hosted web search had no option besides Brave (requires API key), Perplexity (requires API key), or Grok (requires xAI API key). **Why it matters:** Self-hosted search enables privacy-conscious deployments, air-gapped environments, and zero-cost search without external API dependencies or rate limits. **What changed:** Added `searxng` as a fourth `web_search` provider option. When `tools.web.search.provider` is set to `"searxng"`, the tool queries a user-configured SearXNG instance via its JSON API. No API key required. **What did NOT change:** Default behavior (Brave remains default), existing provider implementations, Firecrawl path, `web_fetch` tool, or other tools. ## Change Type (select all) - [ ] Bug fix - [x] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [x] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [x] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## User-visible / Behavior Changes **New config:** `tools.web.search.searxng.baseUrl` (string, optional). **Default:** `http://127.0.0.1:8080`. When `tools.web.search.provider` is set to `"searxng"`, `web_search` queries the configured SearXNG instance instead of Brave/Perplexity/Grok. No API key required. **Config option and doc added:** Documentation at [`docs/tools/web.md`](docs/tools/web.md) includes setup instructions, Docker networking guide, and SearXNG `settings.yml` configuration for JSON format. ## Security Impact (required) - **New permissions/capabilities?** Yes — ability to query arbitrary SearXNG instances (user-configured endpoint). - **Secrets/tokens handling changed?** No — SearXNG requires no API key. - **New/changed network calls?** Yes — HTTP POST to user-configured SearXNG base URL. - **Command/tool execution surface changed?** No. - **Data access scope changed?** No. - **Risk + mitigation:** Risk: User could misconfigure baseUrl to point to malicious endpoint. Mitigation: User controls config; self-hosted SearXNG is a trusted-component pattern. ## Configuration Example ```json5 { tools: { web: { search: { enabled: true, provider: "searxng", searxng: { baseUrl: "http://127.0.0.1:8080", }, }, }, }, } ``` --- ## Repro + Verification ### Environment - **OS:** any - **Runtime/container:** Node 22+ - **Model/provider:** N/A - **Integration/channel:** N/A - **Relevant config (redacted):** `tools.web.search.provider: "searxng"`, `tools.web.search.searxng.baseUrl: "http://127.0.0.1:8080"` ### Steps 1. Run `pnpm test -- src/agents/tools/web-search.e2e.test.ts` 2. Confirm `resolveSearXngBaseUrl` tests pass (default, custom URL, whitespace trimming) 3. Confirm existing Brave/Perplexity/Grok tests still pass ### Expected All web-search e2e tests pass; `resolveSearXngBaseUrl({})` returns `"http://127.0.0.1:8080"`; custom baseUrl is respected. ### Actual All web-search e2e tests pass; `resolveSearXngBaseUrl({})` returns `"http://127.0.0.1:8080"`; custom baseUrl is respected. --- ## Evidence - [x] **Failing test/log before + passing after:** New test suite added in `web-search.e2e.test.ts` for `resolveSearXngBaseUrl`; all tests pass. - [ ] **Trace/log snippets:** (attach if relevant) - [ ] **Screenshot/recording:** N/A - [ ] **Perf numbers:** N/A ## Human Verification (required) - **Verified scenarios:** Config resolution (default baseUrl, explicit custom baseUrl, whitespace trimming); provider selection logic branches to `searxng` path. - **Edge cases checked:** Missing/undefined config defaults to `http://127.0.0.1:8080`; type/schema include new `searxng` key. - **What you did not verify:** Live search against a running SearXNG instance (tests use unit-level config resolution). ## Compatibility / Migration - **Backward compatible?** Yes - **Config/env changes?** Yes — new optional key `tools.web.search.searxng.baseUrl` and provider value `"searxng"`. - **Migration needed?** No - **If yes, exact upgrade steps:** N/A ## Failure Recovery (if this breaks) - **How to disable/revert:** Set `tools.web.search.provider` to `"brave"` (or remove the key); or revert the PR. - **Files/config to restore:** Revert changes in `src/agents/tools/web-search.ts`, `src/config/types.tools.ts`, `src/config/zod-schema.agent-runtime.ts`, `docs/tools/web.md`, and test file. - **Known bad symptoms:** If SearXNG searches fail when configured, check that `baseUrl` is correct and SearXNG instance has JSON format enabled in `settings.yml`. <!-- greptile_comment --> <h3>Greptile Summary</h3> Added SearXNG as a self-hosted search provider option for the web_search tool. This implementation allows users to run their own privacy-focused metasearch engine without requiring API keys. The changes include configuration schema updates, provider logic, API integration, comprehensive documentation with Docker networking examples, and test coverage for the new configuration resolver. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The implementation follows established patterns from other providers (Brave, Perplexity, Grok), includes proper error handling, test coverage, and comprehensive documentation. The code validates URLs using the URL constructor, properly handles missing configuration with sensible defaults, and correctly integrates with the existing caching and content-wrapping infrastructure. - No files require special attention _{Last reviewed commit: e1f929d} <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->