Skip to content

feat(websearch): add Perplexity backend #25909

Open
jliounis wants to merge 2 commits into
anomalyco:devfrom
jliounis:add-perplexity-websearch
Open

feat(websearch): add Perplexity backend #25909
jliounis wants to merge 2 commits into
anomalyco:devfrom
jliounis:add-perplexity-websearch

Conversation

@jliounis
Copy link
Copy Markdown

@jliounis jliounis commented May 5, 2026 •
edited
Loading

Issue for this PR

Closes #

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

The websearch tool today calls Exa via the hosted MCP endpoint and is the only backend available. This PR adds the Perplexity Search API as a second, opt-in backend. Exa remains the default. Users who want to use Perplexity explicitly set OPENCODE_ENABLE_PERPLEXITY=1 with a PERPLEXITY_API_KEY (or PPLX_API_KEY).

Why: gating the existing tool behind a single proprietary backend shouldn't be the only option. Letting users pick keeps Exa first-class for people who already pay for it, and gives everyone else a way to plug in a different search provider without rewriting the tool.

How it works:

  • New mcp-perplexity.ts makes a direct REST call to https://api.perplexity.ai/search (Perplexity has no hosted MCP HTTP endpoint, only stdio, so the MCP-style naming is just for symmetry with mcp-exa.ts). Sends Authorization: Bearer $PERPLEXITY_API_KEY and X-Pplx-Integration: opencode/<version> so usage is attributable on our side.
  • websearch.ts chooses the backend at runtime. Selection precedence:
    1. OPENCODE_ENABLE_EXA=1 or provider is opencode -> Exa (default)
    2. OPENCODE_ENABLE_PERPLEXITY=1 with PERPLEXITY_API_KEY (or PPLX_API_KEY) -> Perplexity
    3. Otherwise -> tool not registered (existing behavior)
  • flag.ts adds OPENCODE_ENABLE_PERPLEXITY, which is strictly opt-in — setting just a Perplexity key does not enable it.
  • registry.ts gating: surface the websearch tool when either backend is active, instead of only when Exa is active.
  • providers.mdx adds Perplexity to the LLM provider listing (Agent API is OpenAI-compatible at https://api.perplexity.ai).
  • tools.mdx documents the dual websearch backends and the precedence rules.

Existing Exa users see no behavior change. Users who want Perplexity must explicitly opt in with OPENCODE_ENABLE_PERPLEXITY=1.

This replaces the docs-only PR #24976, which was closed in favor of shipping docs + code together.

How did you verify your code works?

  • bun run typecheck passes for packages/opencode and packages/core.
  • Existing snapshot tests under packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap updated and passing (the livecrawl and type parameter descriptions changed since they're Exa-specific now).
  • Manually exercised mcp-perplexity.call with a real PERPLEXITY_API_KEY against api.perplexity.ai/search and confirmed the response parses, the integration header is sent, and contextMaxCharacters truncation works.
  • Manually verified the Exa path still works when the Perplexity flag is unset (no behavior change).
  • Did NOT add new HTTP-mock unit tests because the existing mcp-exa.ts has no equivalent test pattern in this repo to mirror; happy to add one if a maintainer points to a preferred fixture style.

Screenshots / recordings

N/A (CLI tool, no UI).

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

@jliounis jliounis force-pushed the add-perplexity-websearch branch from 916eb3a to dff2541 Compare May 8, 2026 10:16
@jliounis jliounis changed the title feat(websearch): add Perplexity backend (default), keep Exa as alt feat(websearch): add Perplexity backend (opt-in, keep Exa as default) May 8, 2026
@jliounis
Copy link
Copy Markdown
Author

jliounis commented May 8, 2026

Updated this PR to make Perplexity strictly opt-in instead of default — Exa remains the default backend. Force-pushed dff2541.

Changes vs. the previous revision:

  • flag.ts: OPENCODE_ENABLE_PERPLEXITY now requires OPENCODE_ENABLE_PERPLEXITY=1 to be set explicitly. Setting just PERPLEXITY_API_KEY no longer auto-enables the backend. Removed the OPENCODE_DISABLE_PERPLEXITY escape hatch since it's no longer needed.
  • websearch.ts: backend-selection comment updated; selection logic itself unchanged (it already gated on the flag).
  • tools.mdx: docs flipped — Exa listed as default, Perplexity as opt-in. Updated the "to enable" snippet accordingly.
  • PR title + description updated to reflect the new behavior.

To use Perplexity now:

OPENCODE_ENABLE_PERPLEXITY=1 PERPLEXITY_API_KEY=pplx-... opencode

Existing Exa users see zero behavior change.

@jliounis
feat(websearch): add Perplexity backend (opt-in, keep Exa as default)
837e85e 
Adds a Perplexity Search API backend for the `websearch` tool, opt-in via `OPENCODE_ENABLE_PERPLEXITY=1` with `PERPLEXITY_API_KEY` (or `PPLX_API_KEY`). Exa remains the default backend.
@jliounis jliounis force-pushed the add-perplexity-websearch branch from dff2541 to 837e85e Compare May 8, 2026 10:31
@jliounis
Copy link
Copy Markdown
Author

jliounis commented May 8, 2026

Rebased onto latest dev and resolved conflicts. New head: 837e85ef.

Upstream changed websearch.ts significantly since this branch was first pushed:

  • Extracted webSearchEnabled() helper in registry.ts and added a parallel backend (Parallel Search via @opencode-ai/core flag OPENCODE_ENABLE_PARALLEL).
  • Renamed mcp-exa.ts → mcp-websearch.ts to host both Exa and Parallel call patterns.
  • Introduced selectWebSearchProvider() with an OPENCODE_WEBSEARCH_PROVIDER env override and per-session checksum routing between Exa and Parallel when both are enabled.

I integrated Perplexity into that new architecture rather than fighting it:

  • Added "perplexity" to WebSearchProviderSchema and to selectWebSearchProvider(). Perplexity is never picked automatically when Exa or Parallel is also enabled — it only fires when (a) the user explicitly sets OPENCODE_WEBSEARCH_PROVIDER=perplexity, or (b) Perplexity is the only enabled backend (OPENCODE_ENABLE_PERPLEXITY=1 with a key, and neither Exa nor Parallel enabled). This preserves "Exa stays default" exactly as agreed.
  • Extended webSearchEnabled() to surface the websearch tool when the Perplexity flag is on.
  • Added a perplexity branch to the internal callProvider() dispatcher that routes to McpPerplexity.call (our existing mcp-perplexity.ts).
  • Added "Perplexity Web Search" to webSearchProviderLabel().
  • Updated the parameter snapshot to reflect that livecrawl and type are Exa-only (now also ignored under Parallel).

PR is MERGEABLE again.

@jliounis jliounis changed the title feat(websearch): add Perplexity backend (opt-in, keep Exa as default) feat(websearch): add Perplexity backend May 11, 2026
@github-actions github-actions Bot mentioned this pull request May 28, 2026
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jliounis