feat(tool): add Brave Search as a selectable web_search provider (#294)

[Zheng-Lu]

Summary

Closes #294 (Phase 2 of #291).

Implements the Brave Search API provider behind the typed WebSearchProvider contract established in Phase 1 (#293), making search backends cleanly selectable via AGENTIC_WEB_SEARCH_PROVIDER (environment) or [web_search].provider (configuration file), while keeping default You.com behavior and recorded cassettes byte-identical.

Key Implementation Details

1. Provider Implementation (crates/agentic-server-core/src/tool/web_search/brave.rs):

   • Hits GET {base_url}/res/v1/web/search with result_filter=web,news and X-Subscription-Token.
   • Passes text_decorations=false so the LLM receives clean, unadorned snippet text without raw <strong> HTML tags.
   • Strictly respects transport rules: avoids Accept-Encoding: gzip (core reqwest lacks gzip decompression).
   • Maps freshness accurately: supports both short codes (pd, pw, pm, py) AND date ranges (YYYY-MM-DDtoYYYY-MM-DD).
   • Clamps count to the Brave 20-result limit with tracing::debug!.
   • Post-filters domain allowlists/blocklists client-side using label-boundary suffix matching.
   • Non-retrying 401/403 (names BRAVE_API_KEY without secret leaks) and 429 (surfaces Retry-After or X-RateLimit-Reset).

2. Concurrency & Rate Limiting:

   • Implements AGENTIC_WEB_SEARCH_MAX_CONCURRENT_QUERIES and [web_search].max_concurrent_queries as specified in RFC [RFC] Pluggable Web Search Providers and Typed Result Normalization #291 / Issue [Feature] Add Brave Search as a selectable web_search provider #294.
   • Defaults to serial queries (1 in-flight) for Brave's free tier (~1 QPS limit), but allows operators on paid plans to raise the ceiling.

3. Wire Compatibility & RFC [RFC] Pluggable Web Search Providers and Typed Result Normalization #291 Q5 Resolution:

   • Resolves Q5: surfaces "provider": "brave" in metadata[].
   • Uses #[serde(skip_serializing_if = "WebSearchProviderKind::is_you")] to ensure existing You.com output and recorded Messages cassettes remain 100% byte-identical.

4. Zero Extra Dependencies & Non-Breaking API:

   • Zero added external crates (no strum dependency added; uses standard library FromStr).
   • Keeps WebSearchProviderConfig::new backward-compatible; introduces fluent .with_provider(...) / .with_max_concurrent_queries(...) builders and WebSearchHandler::from_config(...).

5. Testing & Documentation:

   • Dedicated integration test suite: crates/agentic-server-core/tests/web_search_brave_test.rs covering 200 OK (web+news), empty results, domain filtering, 401/403, 429 with Retry-After/X-RateLimit-Reset, batched query serialization, and concurrency overrides.
   • Fully updated README.md, docs/deploying/README.md, docs/deploying/kubernetes.md, CHANGELOG.md, and ARCHITECTURE.md.

Review follow-up: keep provider credentials unpinned in generated configs so provider switches select the matching default API-key variable, preserve HTTP-date Retry-After values verbatim, and split shared provider types/config resolution into focused modules to pass the production file-size checks.

Test Plan

Validation after the review patch:

• After merging fix: preserve and verify image input through Responses #263 and fix(mcp): follow tools/list pagination cursors #311, the integrated tree exactly matches the combined checkout with 1,532 passing workspace tests (9 ignored) and passing launcher contract tests. All pre-commit hooks passed again after baseline reconciliation.

• 60 core tests matching web_search passed.

• 10 Brave integration tests and 25 common/You integration tests passed.

• 6 configuration-resolution tests passed.

• Provider-switch and HTTP-date Retry-After regressions failed before their fixes and passed afterward.

• cargo clippy --all-targets -- -D warnings passed.

• pre-commit run --all-files passed, including formatting and production file-size checks.

New Brave coverage uses local Axum HTTP mocks. No live Brave provider call or new Brave cassette was recorded during review.

[franciscojavierarceo]

patched provider switching in generated configs and HTTP-date Retry-After handling, with regression tests. the provider/configuration tests, Clippy, and pre-commit checks pass locally. Brave HTTP behavior is covered by mocks; no live Brave run was performed.

[franciscojavierarceo]

reconciled the baseline after #263 and #311 merged. the resulting Git tree is identical to the combined checkout that passed all 1,532 workspace tests and launcher tests; all pre-commit hooks also pass on this head.