#14788: feat: Add DuckDuckGo search provider with Tor support

## Summary Add DuckDuckGo as a 4th search provider for the `web_search` tool, with built-in Tor proxy support. ## Motivation **Problem:** Brave Search requires a paid API key ($5-15/month), which creates a barrier for users who want basic web search functionality. **Solution:** DuckDuckGo search via the `ddgs` CLI provides: - ✅ No API key required - ✅ Free and unlimited - ✅ Privacy-first (built-in Tor support) - ✅ Zero-cost alternative to Brave ## Changes ### Code Changes 1. **`src/agents/tools/web-search.ts`**: - Added `"duckduckgo"` to `SEARCH_PROVIDERS` - Implemented `findDdgsCli()` to locate CLI in common paths - Implemented `runDuckDuckGoSearch()` using official `ddgs` CLI - Added Tor proxy support with `"tor"` convenience alias - Maintains same caching and output format as other providers 2. **`src/config/zod-schema.agent-runtime.ts`**: - Added `"duckduckgo"` to provider enum - Added `duckduckgo` config schema with validation - Supports: `proxy`, `region`, `safesearch`, `timelimit` ### User-Facing Changes **Installation:** ```bash # Option 1: pipx (recommended) pipx install ddgs # Option 2: pip --user pip3 install --user ddgs # Option 3: system-wide sudo pip3 install ddgs ``` **Configuration:** ```yaml tools: web: search: provider: duckduckgo duckduckgo: proxy: tor # Optional: "tor" or full proxy URL region: wt-wt # Optional: region code safesearch: moderate # Optional: on, moderate, off timelimit: m # Optional: d, w, m, y ``` **Tor Setup (optional):** ```bash sudo apt install tor sudo systemctl start tor ``` ## Testing Tested on Ubuntu with: - ✅ Regular search (no proxy) - ✅ Tor proxy search (`proxy: "tor"`) - ✅ Custom SOCKS5 proxy - ✅ All config options (region, safesearch, timelimit) - ✅ Caching behavior - ✅ Error handling (CLI not found, timeout, etc.) **Performance:** - Without proxy: 1-3 seconds - With Tor proxy: 3-8 seconds - Caching: <10ms (cache hit) ## Benefits | Feature | DuckDuckGo | Brave | |---------|------------|-------| | **Cost** | Free | $5-15/month | | **API Key** | ❌ Not required | ✅ Required | | **Privacy** | ✅ Tor built-in | ⚠️ Manual setup | | **Setup** | `pip install ddgs` | Register + API key | ## Implementation Notes - Uses official `ddgs` CLI (not a custom script) - Auto-detects CLI in: `~/.local/bin`, `~/.openclaw/.venv/bin`, `/usr/local/bin`, `/usr/bin` - Calls `ddgs text -q "query" -o /tmp/output.json` - Maps output format: `{title, href, body}` → `{title, url, description}` - Same error handling and timeout patterns as other providers ## Breaking Changes None. This is a new provider that doesn't affect existing configurations. ## Documentation Updates Needed - [ ] Add DuckDuckGo section to web search docs - [ ] Add installation guide for `ddgs` CLI - [ ] Add Tor proxy setup guide - [ ] Add example configurations ## Checklist - [x] Code follows project style guidelines - [x] TypeScript types are properly defined - [x] Zod schema validation added - [x] Linter passes (0 warnings, 0 errors) - [x] Build succeeds - [x] Tested with real searches - [x] Commit messages follow conventional commits - [ ] Documentation updated (separate PR if accepted) ## Related Issues Addresses potential feature request for cost-free search option. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds a new `duckduckgo` provider to the `web_search` agent tool, implemented via the `ddgs` CLI with optional proxy/Tor support, and wires the new provider/config into the agent runtime Zod schema. It also broadens config support for additional TTS providers (chatterbox/piper/kokoro) and adds a Whisper media-understanding provider, registering it alongside existing media providers. <h3>Confidence Score: 3/5</h3> - Mergeable after addressing a tmp-file clobbering/collision issue in the DuckDuckGo provider. - The core provider wiring and schemas look consistent, but the DuckDuckGo implementation currently writes CLI output to a predictable /tmp filename, which is a real security and correctness issue on multi-user/concurrent deployments. - src/agents/tools/web-search.ts <!-- greptile_other_comments_section --> <!-- /greptile_comment -->