feat(parallel): add Parallel as a bundled web_search provider

[NormallyGaussian]

Summary

Note

AI-assisted PR. Prepared with the help of Claude (Opus 4.7). Implementation, audits, and iterative review were driven by Claude with codex review --base origin/main run four times and two general-purpose subagents (repo-conventions audit + Parallel API best-practices audit against Parallel's docs, two rounds each). All findings addressed; final Codex pass returned "no actionable bugs found." The author personally reviewed every change, ran the live integration end-to-end (see Real behavior proof + Evidence), and understands the code being merged.

• Problem: OpenClaw has no bundled web-search provider that uses Parallel, even though Parallel returns LLM-optimized dense excerpts that pair well with the agent loop.
• Solution: Add extensions/parallel/ as a new bundled web_search provider modeled on extensions/exa/. Authenticates via PARALLEL_API_KEY (or plugins.entries.parallel.config.webSearch.apiKey), hits POST https://api.parallel.ai/v1/search, and surfaces ranked excerpts through the generic web_search contract.
• What changed: New plugin package; SDK-driven HTTP/cache/credential resolution (withTrustedWebSearchEndpoint, mergeScopedSearchConfig, buildSearchCacheKey, readCachedSearchPayload/writeCachedSearchPayload, wrapWebContent, resolveSearchTimeoutSeconds, resolveSearchCacheTtlMs, DEFAULT_SEARCH_COUNT); minimal core touch-points for legacy-config migrate, registration contract cases, runtime test allowlists, doctor migration, vitest paths, labeler, and docs nav.
• What did NOT change: No core architectural change. No new SDK surface added. Other web search providers untouched. CHANGELOG.md left to maintainers per CONTRIBUTING.md. No standalone Parallel-only tool (kept scope to the generic web_search provider tool to stay aligned with the Exa pattern and "keep it simple").

Motivation

Parallel is purpose-built for agentic web search: it returns compressed, LLM-optimized excerpts ranked by reasoning utility, not human click-through. That fits OpenClaw's web_search contract well and gives users a high-accuracy provider option alongside Brave/Exa/Firecrawl/Tavily/Perplexity. Parallel best practices (docs.parallel.ai/search/best-practices) were checked against the implementation; see Verification.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Added Parallel as a selectable web_search provider in OpenClaw.
• Real environment tested: Local macOS dev install, openclaw onboarded fresh with pnpm openclaw onboard --flow quickstart --accept-risk --auth-choice skip --skip-channels --skip-skills --skip-daemon --skip-ui --skip-health, gateway via pnpm openclaw gateway run --port 18789 --bind loopback --force, TUI via pnpm openclaw tui, model via a real Anthropic key, search pinned to parallel via pnpm openclaw config set tools.web.search.provider parallel.
• Exact steps or command run after this patch:
  From the repo root:

rm ~/.openclaw/openclaw.json
pnpm build && pnpm openclaw onboard --flow quickstart --accept-risk --auth-choice skip --skip-channels --skip-skills --skip-daemon --skip-ui --skip-health
pnpm openclaw gateway run --port 18789 --bind loopback --force

In another window:

pnpm openclaw tui

• Also ran the live test directly: OPENCLAW_LIVE_TEST=1 node scripts/run-vitest.mjs run extensions/parallel/parallel.live.test.ts
• Evidence after fix: Live test against api.parallel.ai/v1/search returned real ranked results with a sessionId echoed back. TUI agent successfully used web_search against Parallel and surfaced results to the model.
• Observed result after fix: Web search routed to Parallel; results include title, URL, dense excerpts, and Parallel's searchId/sessionId. Confirmed identifying User-Agent: openclaw-parallel/<version> (<platform>) on outbound requests.
• What was not tested: Channel-integration paths (Telegram, Discord, etc.) — pure CLI/TUI loop only. Cloudflare AI Gateway proxy mode not exercised end-to-end (covered by unit tests for the baseUrl override). cacheTtlMinutes-driven TTL expiry not exercised live (relies on the shared SDK helper).
• Before evidence: N/A (new bundled provider).

Root Cause (if applicable)

N/A.

Regression Test Plan (if applicable)

N/A — this is a feature, not a regression fix. Coverage added:

• Unit: extensions/parallel/src/parallel-web-search-provider.test.ts (20 tests covering schema metadata, credential resolution, base URL normalization, count clamping, response normalization, session-id normalization, long-query → objective adaptation, cache-key partitioning by endpoint/count/session, missing-key payload, top-level web search settings honored end-to-end via mocked SDK fetch helper, session-id cache-leak protection).
• Per-plugin registration contract: src/plugins/contracts/plugin-registration.parallel.contract.test.ts.
• Runtime registry: bundled providers list and expected runtime keys in src/plugins/web-search-providers.runtime.test.ts.
• Web-search provider contract list in src/plugins/contracts/providers.contract.test.ts.
• Plugin registration case in src/plugin-sdk/test-helpers/plugin-registration-contract-cases.ts.
• Live: extensions/parallel/parallel.live.test.ts (gated on OPENCLAW_LIVE_TEST=1 + PARALLEL_API_KEY).

User-visible / Behavior Changes

• New web_search provider option: parallel. Configurable via PARALLEL_API_KEY env var or plugins.entries.parallel.config.webSearch.apiKey config.
• Optional plugins.entries.parallel.config.webSearch.baseUrl overrides the Parallel endpoint (e.g., for Cloudflare AI Gateway proxying). OpenClaw appends /v1/search when the URL doesn't already end there.
• Auto-detect picks Parallel at order 75 (after Tavily at 70, before DuckDuckGo at 100) when PARALLEL_API_KEY is the only configured key.
• New docs page: https://docs.openclaw.ai/tools/parallel-search.
• New onboarding step shows Parallel in the pnpm openclaw onboard search-provider picker automatically (dynamic discovery; no static list to update).

Diagram (if applicable)

Before:
[agent] -> web_search -> [brave|exa|firecrawl|...|tavily|duckduckgo]

After:
[agent] -> web_search -> [brave|exa|firecrawl|...|tavily|parallel|duckduckgo]
                                                          ^
                                                  POST api.parallel.ai/v1/search
                                                  (x-api-key, User-Agent identifies plugin)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No — uses existing SDK secret resolution (readConfiguredSecretString, readProviderEnvValue). API key flows through the standard webSearch.apiKey plugin config path (SecretRef-capable like all other web search providers).
• New/changed network calls? Yes — outbound HTTPS to api.parallel.ai (or a user-configured base URL). All calls go through the SDK's guarded withTrustedWebSearchEndpoint helper, which applies the existing OpenClaw network safety policy.
• Command/tool execution surface changed? No.
• Data access scope changed? No.
• Risk + mitigation: A new outbound API host. Mitigation: routed through the existing withTrustedWebSearchEndpoint guard; SSRF/loopback rules unchanged; response excerpts are wrapped via wrapWebContent so they're tagged untrusted before reaching the model.

Repro + Verification

Environment

• OS: macOS (Darwin 24.5.0)
• Runtime/container: Node 22+, local pnpm workspace
• Model/provider: Anthropic (claude-sonnet-4-6) for the TUI smoke; model-agnostic plugin
• Integration/channel (if any): TUI only
• Relevant config (redacted):

  {
    "tools": { "web": { "search": { "provider": "parallel", "enabled": true } } },
    "plugins": { "entries": { "parallel": { "enabled": true } } }
  }

Steps

1. pnpm build
2. export PARALLEL_API_KEY=par-...
3. pnpm openclaw onboard --flow quickstart --accept-risk --auth-choice skip --skip-channels --skip-skills --skip-daemon --skip-ui --skip-health
4. pnpm openclaw config set tools.web.search.provider parallel && pnpm openclaw config set plugins.entries.parallel.enabled true
5. pnpm openclaw gateway run --port 18789 --bind loopback --force (window 1)
6. pnpm openclaw tui (window 2), ask the agent to perform a web search

Expected

• web_search routes to Parallel; response includes provider: "parallel", ranked results with title/url/excerpts, and a sessionId.

Actual

• Matches expected.

Evidence

• Failing test/log before + passing after — 20/20 unit tests + 1 live test green
• Trace/log snippets — ./scripts/clawlog.sh | grep parallel shows outbound api.parallel.ai/v1/search POSTs
• Screenshot/recording — forthcoming as a follow-up comment from the author (live TUI run + clawlog tail)
• Perf numbers — not relevant; Parallel default response time ≈ 1-2s per query, in line with other API-backed providers

Human Verification (required)

• Verified scenarios: Live web_search call via the TUI hits Parallel and surfaces real results to the model; live test (parallel.live.test.ts) hits the real api.parallel.ai/v1/search endpoint and asserts shape; onboard flow shows Parallel automatically in the search-provider picker; base URL override path validated via unit tests; missing-key path validated via unit tests; long-query → objective adaptation validated via unit tests; session-id cache-leak protection validated via unit tests.
• Edge cases checked: Empty API key (graceful structured missing_parallel_api_key payload); invalid base URL (invalid_base_url payload); query length > 200 chars (truncated to 200 in search_queries[0], full text routed as objective); count clamped to 1-40; caller-supplied vs auto-generated session_id (cache key partitioned; only caller-supplied id is preserved across cache hits).
• What you did not verify: Cross-OS behavior beyond macOS; non-CLI/non-TUI channel paths (no relevant changes there); Parallel pricing/quota behavior under sustained load.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Pre-PR review evidence (all green after iteration):

• codex review --base origin/main run four times; final pass: "no actionable bugs found." All earlier P2/P3 findings addressed: top-level web-search settings now honored via mergeScopedSearchConfig; missing-key/invalid-base-url payloads point at the real config paths and the new docs page; default max_results matches OpenClaw's DEFAULT_SEARCH_COUNT (5) instead of Parallel's default (10) so switching providers doesn't silently change result volume; long-query → objective adaptation handles Parallel's 200-char search_queries limit; auto-generated sessionId stripped before caching to prevent cross-task contamination on cache hits.
• General-purpose subagent (repo-conventions audit): two rounds, ship-ready both times.
• General-purpose subagent (Parallel API best-practices audit against https://docs.parallel.ai/search/best-practices and https://docs.parallel.ai/api-reference/search/search): two rounds, all PASS, no blocking findings.

Compatibility / Migration

• Backward compatible? Yes — purely additive. No existing provider behavior changed.
• Config/env changes? Optional: PARALLEL_API_KEY env var or plugins.entries.parallel.config.webSearch.apiKey config. Both auto-detected if present; ignored if absent.
• Migration needed? No. Parallel never had a legacy tools.web.search.parallel.* path, so it's listed in NON_MIGRATED_LEGACY_WEB_SEARCH_PROVIDER_IDS alongside Tavily (no doctor rewrite rule needed).
• Upgrade steps: None.

Risks and Mitigations

• Risk: Plugin adds an outbound network host (api.parallel.ai).
  • Mitigation: Routed through the existing withTrustedWebSearchEndpoint SDK guard. Same network policy as Exa/Brave/Firecrawl/Tavily. No new SSRF surface.
• Risk: Default-count divergence vs. other providers.
  • Mitigation: Always sends advanced_settings.max_results = DEFAULT_SEARCH_COUNT (5) so result volume is consistent across providers. Locked by a unit test.
• Risk: Parallel-generated session_id getting cached and leaking across unrelated tasks.
  • Mitigation: Auto-generated session IDs are stripped before write to the shared cache; only caller-supplied session IDs survive cache hits. Locked by a unit test.

[github-actions]

Dependency Changes Detected

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

• extensions/parallel/package.json
• pnpm-lock.yaml

Maintainer follow-up:

• Review whether the dependency changes are intentional.
• Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
• Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
• Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Low adoption: npm whatsapp-rust-bridge Location: Package overview From: extensions/whatsapp/npm-shrinkwrap.json → npm/baileys@7.0.0-rc13 → npm/whatsapp-rust-bridge@0.5.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/whatsapp-rust-bridge@0.5.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 3, 2026, 2:58 AM ET / 06:58 UTC.

Summary
Review failed before ClawSweeper could summarize the requested change.

PR surface: Source +626, Tests +674, Docs +141, Config +35, Other +6. Total +1482 across 27 files.

Reproducibility: unclear. The review failed before ClawSweeper could establish a reproduction path.

Review metrics: none identified.

Merge readiness
Overall: 🌊 off-meta tidepool
Proof: 🌊 off-meta tidepool
Patch quality: 🌊 off-meta tidepool
Result: rating does not apply to this item.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] No close action taken because the review did not complete.

Maintainer options:

1. Decide the mitigation before merge
   Retry the Codex review after fixing the execution failure.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Review did not complete, so no work-lane recommendation was made.

Review details

Best possible solution:

Retry the Codex review after fixing the execution failure.

Do we have a high-confidence way to reproduce the issue?

Unclear. The review failed before ClawSweeper could establish a reproduction path.

Is this the best way to solve the issue?

Unclear. Retry the review first so ClawSweeper can evaluate the actual issue and fix direction.

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 2c9297339817.

Label changes

Label changes:

• remove P3: Current review triage priority is none.
• remove merge-risk: 🚨 compatibility: Current PR review selected no merge-risk labels.
• remove merge-risk: 🚨 security-boundary: Current PR review selected no merge-risk labels.

Label justifications:

• rating: 🌊 off-meta tidepool: Overall readiness is 🌊 off-meta tidepool; proof is 🌊 off-meta tidepool and patch quality is 🌊 off-meta tidepool.

Evidence reviewed

PR surface:

Source +626, Tests +674, Docs +141, Config +35, Other +6. Total +1482 across 27 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	11	630	4	+626
Tests	7	674	0	+674
Docs	5	145	4	+141
Config	3	35	0	+35
Generated	0	0	0	0
Other	1	6	0	+6
Total	27	1490	8	+1482

What I checked:

• failure reason: timeout.
• codex failure detail: Codex review failed for this PR: spawnSync codex ETIMEDOUT.
• codex stdout: Per-item Codex failure; continuing with the rest of the shard.

Likely related people:

• unknown: Codex failed before it could trace repository history. (role: review did not complete; confidence: low)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

ClawSweeper PR egg

🔥 Warming up: real-behavior proof passed; findings, security review, or rank-up moves are still in progress.

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

• Merged PRs are hatchable.
• Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
• Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

[github-actions]

Dependency Guard

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

• extensions/parallel/package.json
• pnpm-lock.yaml

Maintainer follow-up:

• Review whether the dependency changes are intentional.
• Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
• Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
• Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

[github-actions]

Dependency graph changes are blocked

OpenClaw does not accept dependency graph changes through PRs unless a repository admin or security explicitly authorizes the current head SHA. Dependency updates are generated internally by maintainers so external PRs cannot change the resolved graph.

Detected dependency graph changes:

• pnpm-lock.yaml changed.
• extensions/parallel/package.json changed devDependencies, name, version.

Auto-scrub was not attempted because this PR changes package manifest dependency graph fields:

• extensions/parallel/package.json changed devDependencies, name, version.

Dependency graph changes must be reviewed by security or handled by maintainers internally. Please remove lockfile changes manually if they are not needed.

To remove lockfile changes, restore them from the target branch:

git fetch origin
git checkout 'origin/main' -- 'pnpm-lock.yaml'
git commit -m 'chore: remove dependency lockfile change'
git push

If this PR intentionally needs a dependency graph change, ask a repository admin or member of @openclaw/openclaw-secops to comment:

/allow-dependencies-change

The action will approve the current head SHA (12a2b6961faf7c9dd65131ecdcd23f91ebe22a02) when it reruns. A later push requires a fresh approval.

[NormallyGaussian]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Failed
• Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26867186162
• Updated: 2026-06-03T06:25:29.255Z