feat(web): Parallel-backed web search & extract — free Search MCP when keyless, v1 REST when keyed

[NormallyGaussian]

What does this PR do?

Makes Parallel the web search/extract backend with a zero-setup free tier:

• Keyless (no PARALLEL_API_KEY): web_search/web_extract work out of the box via Parallel's free hosted Search MCP (search.parallel.ai/mcp), and parallel becomes the default backend when no other web credentials are configured. Previously a keyless install fell through to a backend it couldn't authenticate.
• Keyed (PARALLEL_API_KEY set): uses the Parallel v1 REST endpoints (client.search / client.extract) — no beta.
• Attribution: on the free path only, results are credited to Parallel and the CLI tool line reads "Parallel search" / "Parallel fetch"; the paid path is unbranded.

The free path uses a small hand-rolled Streamable-HTTP JSON-RPC client to the Search MCP (web_search / web_fetch). No new tool and no MCP server is registered — the existing web_search/web_extract tools are the only ones registered; the MCP is just their wire protocol on the keyless path.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• plugins/web/parallel/provider.py — v1 search/extract; hand-rolled MCP JSON-RPC client (handshake + negotiated MCP-Protocol-Version + id-matched SSE/array parsing) for the keyless web_search/web_fetch path; per-call session ids; free-tier attribution.
• tools/web_tools.py — keyless parallel as the credential-less default in _get_backend() (ahead of ddgs, which is search-only); web_tools_registered() (always on) vs check_web_api_key() (real usability probe) split; explicit per-capability backends honored; free-extract provider/attribution in web_extract_tool.
• agent/display.py — "Parallel search"/"Parallel fetch" verb on the free path only.
• hermes_cli/tools_config.py — web setup prompt gated on actual usability instead of presence of web.backend.
• pyproject.toml, tools/lazy_deps.py, uv.lock — bump parallel-web 0.4.2 → 0.6.0.
• Tests: new tests/plugins/web/test_parallel_keyless_mcp.py + updates to display, web-provider, web-tools-config, and tools-config suites.

How to Test

Live web tools (no model required):

1. Keyless: env -u PARALLEL_API_KEY -u EXA_API_KEY -u FIRECRAWL_API_KEY -u TAVILY_API_KEY uv run --extra dev --extra parallel-web python tests/integration/test_web_tools.py --no-llm → "Using parallel backend"; search + extract pass.
2. Keyed: export PARALLEL_API_KEY=… && uv run --extra dev --extra parallel-web python tests/integration/test_web_tools.py --no-llm.
3. Unit: uv run --extra dev --extra parallel-web pytest -q tests/plugins/web tests/agent/test_display.py tests/tools/test_web_providers.py tests/tools/test_web_tools_config.py tests/hermes_cli/test_tools_config.py.
4. Agent: uv run --extra parallel-web hermes -z "look up the latest news about parallel web systems" -t web → tool line shows 🔍 Parallel search … on the free path.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(web): …)
• My PR contains only changes related to this feature
• I've added tests for my changes
• I've tested on my platform: macOS (Darwin)
• pytest tests/ -q — the web/display/config suites all pass; the full run has pre-existing, unrelated failures in this environment (browser tests require optional deps not installed here)

Documentation & Housekeeping

• Updated docstrings — N/A for README/docs/
• cli-config.yaml.example — N/A (no new config keys; reuses existing web.backend/search_backend/extract_backend and the existing PARALLEL_SEARCH_MODE)
• Cross-platform: pure-Python httpx transport; no platform-specific code
• Tool behavior change is covered (keyless free tier) — can also expand the web_search/web_extract schema descriptions to mention the free tier if preferred

Screenshots / Logs

Keyless live run: Web Backend API Key: Using parallel backend → 3/3 searches valid, extract 2/2 pages. Agent run renders 🔍 Parallel search [query] on the free path and surfaces the Parallel attribution in its answer.

[teknium1]

Thanks for this, Matt — the keyless MCP client is cleanly built and the "broken no-key install" problem it targets is real.

We're going to park this rather than merge it right now, for two reasons:

1. Outbound attribution / telemetry. The keyless path attaches a hermes-agent/1.0.0 User-Agent plus a clientInfo payload on every free-tier call, explicitly so Hermes usage is visible to Parallel (per the in-code comment). That's the exact outbound-attribution pattern we hold under a standing policy: we don't merge new outbound telemetry / usage-attribution until a generic, user-facing opt-in gating mechanism exists (config gate + setup-wizard prompt + a toggle in hermes tools). This is policy, not a code-quality judgment — we made the same call on Firecrawl's integration: tag (#28774). Applying the telemetry label and leaving this open so we can re-land it once that gating lands.

2. Default-backend change. Separately, making Parallel the silent zero-config default for every keyless install (with Parallel branding on the tool line) is a product/default decision rather than a contributor merge — we'd want to own that call independently of the attribution question.

The substantive win here — fixing the no-key fall-through so web tools work out of the box — is something we want. When the opt-in telemetry gating is in place, this is a prime candidate to rebase and re-land with your authorship intact, attribution wired behind the gate. Appreciate the contribution.

[teknium1]

Merged via #43798 — your commit was cherry-picked onto current main with your authorship preserved in git log (rebase-merge). Thanks for an excellent contribution: the hand-rolled Streamable-HTTP client, the registration/usability split, and the explicit-config-wins semantics all survived review intact, and we live-verified the keyless path end-to-end (anonymous search + fetch both work with zero setup). Keyless Parallel is now the default web backend on fresh installs.

One adjustment on top: per project telemetry policy (no third-party usage attribution without explicit user opt-in), the free-MCP clientInfo/User-Agent/session-id prefix was genericized from hermes-agent to a neutral mcp-web-client. The free-tier attribution string in results and the "Parallel search"/"Parallel fetch" CLI labels are unchanged.

[vektorprime]

Get this spam out of Hermes. This organization should be banned for trying to put this product into hermes and other open source software. Moreover, trying to make it a default setting is ridiculous!

[Zambav]

Malicious merge, ban these accounts

[alexferrari88]

Follow-up: #89764 documents the current keyed Parallel v1 regression, and #89766 restores only the authenticated GA/v1 path while crediting the v1 work from this proposal.