feat(web_search): SearXNG-backed web_search tool + Docker sidecar

[jkyberneees]

Summary

Gives the agent local-first web search with no cloud search API and no keys — the same zero-setup ethos as the bundled transcribe (whisper) and vision (MiniCPM-V) tools. A new native web_search tool queries a self-hosted SearXNG metasearch instance over the internal Docker network and returns ranked results the agent then fetches with browser / http_batch.

What's included

Native web_search tool (cmd/odek/web_search_tool.go)

• Queries the SearXNG JSON API → ranked results (title, url, snippet, engine) + direct answers, capped by max_results.
• Output wrapped as untrusted content (SERP snippets can carry injection payloads).
• Gated as network_egress (prompt in restricted, allow in godmode), consistent with browser/http_batch.
• No SSRF surface: accepts only a query string; the backend URL is fixed config. A CheckRedirect guard re-classifies redirect hops so a compromised/misconfigured SearXNG can't 3xx toward internal/metadata endpoints.
• Resilient to the compose cold-start race: retries only on ECONNREFUSED (the precise "up but not listening" signal).
• Registered only when web_search.base_url is set, so plain installs without a SearXNG instance don't see a dead tool.

Config (internal/config)

• WebSearchConfig{BaseURL, Categories, Language, MaxResults, Timeout} threaded end-to-end, mirroring VisionConfig.
• The builtinTools per-tool config params were bundled into a toolConfig struct to stop positional-parameter churn as tools are added.

Docker

• searxng sidecar (pinned 2026.6.8-f3fab143b), co-starting with every profile, internal-only (no host port), depends_on wired.
• docker/searxng/settings.yml enables the JSON API and disables the anti-bot limiter → no Redis/Valkey needed.
• SEARXNG_SECRET in .env.example; both bundled configs set web_search.base_url.

Security

• Results are nonce-wrapped <untrusted_content>; web_search:<query> added to the SECURITY.md untrusted table.
• Egress-gated; redirect-guarded (SSRF); query-only input means no agent-controlled URL.
• SearXNG secret_key is overridden at app load from SEARXNG_SECRET (env override verified against SearXNG source); the placeholder is the canonical ultrasecretkey so an unset secret triggers SearXNG's own warning.

Tests

Hermetic httptest SearXNG mock — happy path, max_results override vs config cap, untrusted wrapping, JSON-disabled 403, unreachable + cold-start retry, redirect-to-internal blocked, policy denial, heterogeneous/malformed answers (must not lose results), empty query, schema; plus resolveWebSearch defaults/merge. Full suite green under -race; go vet/gofmt clean; docker compose config validates.

Docs

README (new "🌐 Local Web Search" feature blurb), CHEATSHEET (config reference + standalone non-Docker recipe), SECURITY, CONFIG, TELEGRAM, docker/README, DOCKER_COMPOSE_USER_GUIDE.

Review trail

This branch was put through a high-effort /code-review and a full vprotocol v5.2.7 verification; both rounds of confirmed findings were fixed in-branch (answers parsing, SSRF redirect guard, secret-warning visibility, cold-start resilience, answer-decode robustness, doc consistency). vprotocol verdict: HumanReviewRequired (η 0.445; single-model author of code+tests+review → correlated, ρ 0.24). An independent human review is the protocol-mandated next step, with two focus areas:

• The SearXNG integration has not been run end-to-end against a live container — all tests use a mock. A docker compose up smoke test is recommended before merge.
• No formal spec; behavior was verified against SearXNG source rather than a contract.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	a1a1ad1	Commit Preview URL Branch Preview URL	Jun 10 2026, 09:35 AM

[jkyberneees]

vprotocol v5.2.7 — Verification Certificate

PR: #24 feat/searxng-web-search · head a1a1ad1 · 27 files · +806 LOC (~646 Go)
Generator: Claude Opus 4.8 (claude-opus-4-8) · Class: GeneratedCode (code + tests, single model/session)
Pipeline: single-model (B=C=D=E) — monoculture fallback, ρ at full strength

This certificate was produced against this exact head SHA before PR creation; per §0.4 (certificates bind to (PR, head_sha)) it is reproduced verbatim — no re-run, no new commits since verification.

Pre-scan (§0)

Added lines scanned for injection markers / verdict tokens / new exec sinks: clean. The untrusted→agent path (SERP results) is nonce-wrapped via wrapUntrusted; the new egress path is NetworkEgress-gated and redirect-guarded. Axis 2.8 → pass.

Nine Axes

Axis	Verdict	Notes
2.1 Semantic Correctness	✅ pass	Explicit error/fallback paths; tolerant answer decode
2.2 Behavioral Contract	⚠️ warn	No independent spec; verified against SearXNG source (answer model, env override, settings schema)
2.3 Security Surface	✅ pass	Query-only input (no SSRF surface); redirect guard; results untrusted-wrapped; secret via app-load env override
2.4 Structural Integrity	✅ pass	toolConfig struct halts call-site churn; mirrors httpBatch/vision
2.5 Behavioral Exploration	✅ pass	Cold-start retry (ECONNREFUSED only), heterogeneous answers, 403/unreachable/denied covered
2.6 Dependency Integrity	✅ pass	SearXNG image pinned (compose + recipe consistent); stdlib-only Go deps
2.7 Generator Provenance	⚠️ warn	Code + tests + review: same model/session → correlated (gates ρ)
2.8 Adversarial Surface	✅ pass	Redirect re-classification blocks SSRF (tested); pre-scan clean
2.9 Documentation Coverage	✅ pass	README blurb, CHEATSHEET config + standalone recipe, SECURITY, docker/README, compose guide

η Derivation

Signal	Weight	Value
m (mutation kill)	0.34	0.67 (10 tool tests + robustness regression; no mutation runner, estimated)
o (oracle agreement)	0.24	0.35 (no independent Agent-C contract)
b (branch coverage)	0.14	0.73 (changed-line; tool error branches covered)
f (fuzz survival)	0.09	0.90 (no crashes; estimated)
s (SAST clean)	0.04	1.00 (go vet clean)
t (static depth)	0.10	1.00 (typed; compiler+vet clean)
d (doc coverage)	0.05	1.00

η_raw = 0.685 · ρ = 0.24 (family +0.10, version +0.05, spec_independence +0.05, AST ~0.02, shared-mutants ~0.02)
η = clamp(0.685 − 0.24, 0, 1) = 0.445

Verdict: HumanReviewRequired

η 0.445 < 0.80 and ρ 0.24 ∈ (0.20, 0.30]. Single-model authorship of code + tests + review cannot self-certify higher. ΔDebt ≈ 0.5 h (Low) · LOC 806 < 1,500 (standard pipeline).

Auto-repairs applied (in-branch, commit a1a1ad1)

• F1 (robustness): typed answers decode coupled the results parse to the answers shape — a non-string answer would fail the whole json.Unmarshal and drop all results. Restored immunity via per-element tolerant decode; added TestWebSearch_HeterogeneousAnswersDoNotLoseResults.
• F2 (consistency): pinned the CHEATSHEET standalone recipe image tag to match compose.
• F3 (docs): added "run from the repo root" to the standalone recipe.

(Earlier rounds in commit 4ba8c3e fixed: answer-object parsing, SSRF redirect guard, secret-warning visibility, cold-start retry.)

Refuted

• Redirect hop-count "11 vs 10" — identical to httpBatchTool's accepted guard; bounded; no security effect.
• Retry nil-deref / body-leak / no-timeout-retry — speculative / impossible in current code (httpResp nil on transport error, returned before the defer) / intentional.
• :ro mount + chown — non-fatal per the SearXNG entrypoint (set -u, not -e); file stays readable.
• settings.yml invalid keys — all 8 verified present in the SearXNG default schema.

Open items for the human reviewer

• Not yet run end-to-end against a live SearXNG container — all tests use a mock. A docker compose up smoke test is recommended before merge.
• Axis 2.7: code, tests, and verification share one author — independently spot-check the mock assumptions against a real instance.
• Axis 2.2: no formal spec; behavior verified against SearXNG source rather than a contract.

Generated by vprotocol v5.2.7 (single-model pipeline; ρ at full strength per §0.1 monoculture fallback).