Module web_search 

WebSearch tool: query -> ranked web results (title, url, snippet).

Two providers, selected in vtcode.toml via [tools.web_search] provider:

• duckduckgo (default): keyless HTML scraping of https://html.duckduckgo.com/html/. Best-effort; may be rate-limited.
• youcom: the You.com Search API (https://ydc-index.io/v1/search), opt-in, requires the YDC_API_KEY environment variable.

Safety/rate-limit guard rails (shared by both providers):

• A cooldown between consecutive network requests (default 3s) prevents hammering DDG and triggering anti-bot challenges.
• A short result cache (default 5min TTL) means repeated identical queries are answered from memory without any network call.
• A session-wide cap (default 12 requests) ensures the tool cannot leak past DDG’s soft quotas even with varied queries.

All three are configurable via WebSearchConfig and turned off in tests.

Structs

SearchResult

WebSearchTool

WebSearch tool. Stateless over the network (DDG) but tracks per-instance cooldown, request cap, and short-lived result cache to avoid hammering DDG’s HTML endpoint and triggering anti-bot challenges.

Functions

parse_duckduckgo_html

Extract ranked results from a DuckDuckGo HTML body. Pure function so it can be exercised in unit tests against a local fixture (no live network).