[RaviTharuma]

Closes #1288

Summary

• Adds a new Perplexity Web (Session) provider that routes through Perplexity's internal SSE API using a Pro/Max subscription session cookie
• Enables access to GPT-5.4, Claude Sonnet/Opus 4.6, Gemini 3.1 Pro, Nemotron via Perplexity without separate API costs
• Full OpenAI chat completions format compliance with streaming, thinking/reasoning, and session continuity
• 22 unit tests, all passing

New executor: open-sse/executors/perplexity-web.ts

Complete PerplexityWebExecutor that:

• Translates OpenAI messages[] → Perplexity's internal query_str + params SSE format
• Parses Perplexity's blocks-based SSE events (markdown chunks, plan steps, web results)
• Translates back to OpenAI chat.completion / chat.completion.chunk format
• Tracks backend_uuid for multi-turn session continuity
• Strips citations [1][2], grok tags, XML declarations, script tags from responses
• Handles auth errors (expired cookies), rate limits, and connection failures

7 models mapped to Perplexity internal preferences

OmniRoute Model	Internal Preference	Mode
pplx-auto	pplx_pro	concise
pplx-sonar	experimental	copilot
pplx-gpt	gpt54	copilot
pplx-gemini	gemini31pro_high	copilot
pplx-sonnet	claude46sonnet	copilot
pplx-opus	claude46opus	copilot
pplx-nemotron	nv_nemotron_3_super	copilot

Thinking variants (via thinking: true)

Model	Thinking Preference
pplx-gpt	gpt54_thinking
pplx-sonnet	claude46sonnetthinking
pplx-opus	claude46opusthinking

Auth

Users paste their __Secure-next-auth.session-token cookie value as the API key. JWT tokens from the macOS desktop app are also supported via the access token field.

Files changed

• Created: open-sse/executors/perplexity-web.ts (832 lines)
• Modified: open-sse/executors/index.ts (+4 lines — import, register, export)
• Modified: open-sse/config/providerRegistry.ts (+19 lines — provider + models)
• Modified: src/shared/constants/providers.ts (+10 lines — UI metadata)
• Created: tests/unit/perplexity-web.test.mjs (22 tests — all passing)

Test results

✔ PerplexityWebExecutor is registered in executor index
✔ PerplexityWebExecutor alias resolves to same type
✔ PerplexityWebExecutor sets correct provider name
✔ Non-streaming: simple text response
✔ Non-streaming: strips citations from response
✔ Streaming: produces valid SSE chunks
✔ Streaming: thinking content emitted as reasoning_content
✔ Error: 401 returns auth error message
✔ Error: 429 returns rate limit message
✔ Error: fetch failure returns 502
✔ Error: empty messages returns 400
✔ Error: missing messages returns 400
✔ Non-streaming: Perplexity stream error returns 502
✔ Message parsing: system + user + assistant history
✔ Message parsing: developer role treated as system
✔ Auth: cookie-based auth sends Cookie header
✔ Auth: JWT auth sends Authorization Bearer header
✔ Model mapping: pplx-gpt sends correct internal preference
✔ Model mapping: thinking mode uses thinking variant
✔ Provider registry: perplexity-web is registered with correct models
✔ Non-streaming: falls back to text field when no blocks
✔ Request: posts to correct Perplexity SSE endpoint
ℹ tests 22 | pass 22 | fail 0 | duration_ms 862

References

Integrated best practices from:

• pplx-proxy — OpenAI format, model mappings, session continuity
• pi-perplexity — TypeScript SSE client
• perplexity-web-wrapper — Cookie auth, search modes
• plexcode — Perplexity TUI patterns

[gemini-code-assist]

Code Review

This pull request introduces the PerplexityWebExecutor, enabling integration with Perplexity's internal SSE API using session cookies or JWTs. The implementation includes model mapping for various Perplexity models, session continuity support via a backend UUID cache, and comprehensive unit tests. Feedback focuses on preventing JSON corruption during truncation, optimizing cache eviction logic, ensuring consistent streaming updates when a response is marked as done, and avoiding aggressive whitespace stripping that could mangle markdown formatting.

[gemini-code-assist]

Aggressively stripping multiple spaces and newlines in cleanResponse will mangle structural formatting such as code block indentation, tables, and markdown lists. This is particularly problematic because this function is used to process the assistant's response before storing it in the session history, meaning subsequent turns in the conversation will receive corrupted context. You should avoid stripping whitespace that might be structural.

  if (strip) {
    t = t.trim();
  }

[RaviTharuma]

Fixed — removed MULTI_SPACE and MULTI_NL replacements from cleanResponse(). Now only trims leading/trailing whitespace, preserving all markdown formatting (code blocks, tables, indentation). Good catch, this would have mangled code-heavy responses.

[gemini-code-assist]

Truncating a JSON string using slice(-96000) is dangerous as it will almost certainly result in an invalid JSON payload (e.g., missing the opening braces and initial keys), causing the upstream request to fail. If a size limit is required by the Perplexity API, you should truncate the history array or the instructions string within the obj before calling JSON.stringify.

Suggested change

	return json.length > 96000 ? json.slice(-96000) : json;
	return json;

[RaviTharuma]

Fixed — replaced json.slice(-96000) with a loop that removes oldest history entries from obj.history before serializing. This guarantees valid JSON output regardless of payload size.

[gemini-code-assist]

The cache eviction logic performs a linear scan $O(N)$ to find the oldest entry. Since JavaScript Map objects preserve insertion order, the first entry returned by the iterator is naturally the oldest one added or updated. You can simplify this to a constant time operation.

  if (sessionCache.size > SESSION_MAX_ENTRIES) {
    const oldestKey = sessionCache.keys().next().value;
    if (oldestKey) sessionCache.delete(oldestKey);
  }

[RaviTharuma]

Fixed — now uses sessionCache.keys().next().value for O(1) eviction. Good point about Map insertion order, much cleaner.

[gemini-code-assist]

When mb.progress === "DONE", the code updates fullAnswer but does not yield a chunk. If the final part of the assistant's response is only contained in this 'DONE' block, it won't be emitted to the stream until the generator finishes at the very end of the loop. This can cause the UI to appear stalled or 'jump' at the end. You should ensure that the final content is yielded as a delta even when the progress is 'DONE'.

[RaviTharuma]

Fixed — the DONE branch now compares against seenLen and yields a delta chunk if there's unseen content. This prevents the UI stall/jump at end of response.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fe7fb13598

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Emit final markdown delta before closing stream

When Perplexity sends a markdown block only in a progress: "DONE" event, this branch updates fullAnswer but never yields a delta chunk. buildStreamingResponse() only forwards chunk.delta, so streaming clients can receive an empty assistant message (or miss the final tail) even though a complete answer was received upstream.

Useful? React with 👍 / 👎.

[RaviTharuma]

Fixed — same fix as above. The DONE block now always yields any remaining unseen content as a final delta before the stream closes.

[chatgpt-codex-connector]

Preserve upstream header overrides in executor

chatCore passes upstreamExtraHeaders into executor calls, but this execute signature drops that field and no merge is performed before fetch. That makes Perplexity Web ignore configured model-level/custom upstream headers (including intentional overrides), diverging from the behavior in other specialized executors that call mergeUpstreamExtraHeaders.

Useful? React with 👍 / 👎.

[RaviTharuma]

Fixed — execute() now destructures upstreamExtraHeaders from the input and calls mergeUpstreamExtraHeaders(headers, upstreamExtraHeaders) before fetch, consistent with all other specialized executors.

[chatgpt-codex-connector]

Apply global fetch timeout in custom execute path

This custom fetch path does not apply FETCH_TIMEOUT_MS (via AbortSignal.timeout + merged signal) like BaseExecutor does. If the upstream connection stalls without returning headers/body, requests can hang indefinitely until client-side cancellation, which can tie up server resources and bypass expected timeout handling.

Useful? React with 👍 / 👎.

[RaviTharuma]

Fixed — now imports FETCH_TIMEOUT_MS from config/constants and applies it via AbortSignal.timeout() + mergeAbortSignals(), matching the BaseExecutor pattern exactly. No more hanging connections.

[diegosouzapw]

Valeu pela excelente contribuição! 🎉 A integração do Perplexity via SSE é genial e o controle de cookie session/backend_uuid está impecável. A feature foi integrada à branch release/v3.6.6 e fará parte do próximo lançamento. Só precisamos converter o teste para .test.ts para manter os requerimentos atuais. Muito obrigado!

[RaviTharuma]

Thanks for the review and for merging! 🎉

All feedback has been addressed in commit 7b2b542:

Maintainer request

• ✅ Test file renamed from .test.mjs → .test.ts

Gemini Code Assist (HIGH)

• ✅ cleanResponse whitespace: Removed MULTI_SPACE and MULTI_NL replacements — now only trims leading/trailing whitespace, preserving markdown formatting (code blocks, tables, lists)
• ✅ JSON truncation: Replaced json.slice(-96000) with a loop that removes oldest history entries from obj.history before serializing — always produces valid JSON

Gemini Code Assist (MEDIUM)

• ✅ Cache eviction: Now uses sessionCache.keys().next().value for O(1) eviction via Map insertion order
• ✅ DONE block delta: progress === "DONE" branch now yields a delta chunk when doneText.length > seenLen, preventing UI stall/jump

Codex Review

• ✅ P1 DONE block: Same fix as above — final content is always emitted as a delta
• ✅ P2 upstreamExtraHeaders: execute() now accepts and merges upstreamExtraHeaders via mergeUpstreamExtraHeaders(), consistent with other executors
• ✅ P2 fetch timeout: Now applies FETCH_TIMEOUT_MS via AbortSignal.timeout() + mergeAbortSignals(), matching BaseExecutor behavior exactly

All 22 tests still passing.

[RaviTharuma]

@diegosouzapw Thank you for the kind words and for merging so quickly! Really appreciate it.

The test file has been converted to .test.ts as requested — included in the follow-up commit 7b2b542 along with all the review feedback fixes from Gemini and Codex.

Excited to see this ship in v3.6.6!

[RaviTharuma]

@diegosouzapw Hey Diego, just a heads up — I also sent you a message on LinkedIn. Would love to connect!